1 /*! @header QuesaCustomElements.h 2 Declares the Quesa custom elements inherited from QD3D. 3 */ 4 /* NAME: 5 QuesaCustomElements.h 6 7 DESCRIPTION: 8 Quesa public header. 9 10 COPYRIGHT: 11 Copyright (c) 1999-2004, Quesa Developers. All rights reserved. 12 13 For the current release of Quesa, please see: 14 15 <http://www.quesa.org/> 16 17 Redistribution and use in source and binary forms, with or without 18 modification, are permitted provided that the following conditions 19 are met: 20 21 o Redistributions of source code must retain the above copyright 22 notice, this list of conditions and the following disclaimer. 23 24 o Redistributions in binary form must reproduce the above 25 copyright notice, this list of conditions and the following 26 disclaimer in the documentation and/or other materials provided 27 with the distribution. 28 29 o Neither the name of Quesa nor the names of its contributors 30 may be used to endorse or promote products derived from this 31 software without specific prior written permission. 32 33 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 34 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 35 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 36 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 37 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 38 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 39 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 40 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 41 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 42 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 43 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 44 ___________________________________________________________________________ 45 */ 46 #ifndef QUESA_CUSTOMELEMENTS_HDR 47 #define QUESA_CUSTOMELEMENTS_HDR 48 //============================================================================= 49 // Include files 50 //----------------------------------------------------------------------------- 51 #include "Quesa.h" 52 53 // Disable QD3D header 54 #if defined(__QD3DCUSTOMELEMENTS__) 55 #error 56 #endif 57 58 #define __QD3DCUSTOMELEMENTS__ 59 60 61 62 63 64 //============================================================================= 65 // C++ preamble 66 //----------------------------------------------------------------------------- 67 #ifdef __cplusplus 68 extern "C" { 69 #endif 70 71 72 73 74 75 //============================================================================= 76 // Constants 77 //----------------------------------------------------------------------------- 78 // Custom element names (as defined by QD3D) 79 /*! 80 @constant CEcNameElementName 81 @discussion Class name of the name element. 82 83 Ordinarily you will not need to use the class name, because you 84 can manipulate name elements using the functions 85 CENameElement_SetData, CENameElement_GetData, and 86 CENameElement_EmptyData. 87 */ 88 #define CEcNameElementName "Apple Computer, Inc.:NameElement" 89 90 /*! 91 @constant CEcUrlElementName 92 @discussion Class name of the URL element. 93 94 Ordinarily you will not need to use the class name, because you 95 can manipulate name elements using the functions 96 CEUrlElement_SetData, CEUrlElement_GetData, and 97 CEUrlElement_EmptyData. 98 */ 99 #define CEcUrlElementName "Apple Computer, Inc.:URLElement" 100 101 /*! 102 @constant CEcWireElementName 103 @discussion Class name of the wire element. 104 105 Ordinarily you will not need to use the class name, because you 106 can manipulate name elements using the functions 107 CEWireElement_SetData, CEWireElement_SetData, and 108 CEWireElement_EmptyData. 109 */ 110 #define CEcWireElementName "Apple Computer, Inc.:WireElement" 111 112 113 /*! 114 * @enum 115 * TCEUrlOptions 116 * @discussion 117 * URL options. 118 * 119 * @constant kCEUrlOptionNone No options set. 120 * @constant kCEUrlOptionUseMap Map option set (meaning unknown). 121 */ 122 typedef enum { 123 kCEUrlOptionNone = 0, 124 kCEUrlOptionUseMap = 1, 125 kCEUrlOptionSize32 = 0xFFFFFFFF 126 } TCEUrlOptions; 127 128 129 #if QUESA_ALLOW_QD3D_EXTENSIONS 130 /*! 131 * @enum 132 * TQ3EventCallbackElementTypes 133 * @discussion 134 * Custom elements containing callback functions can be attached to objects, 135 * in order that client code can be notified by Quesa of certain events. 136 * The callback function has the type TQ3ObjectEventCallback. 137 * 138 * <em>This functionality is not available in QD3D.</em> 139 * 140 * Example of installing an event callback: 141 * 142 * <blockquote><pre><code> 143 * TQ3ObjectEventCallback callback = MyCallback; 144 * Q3Object_AddElement( theView, 145 * kQ3CallbackElementTypeBeforeRender, 146 * &callback ); 147 * </code></pre></blockquote> 148 * 149 * The before and after rendering callbacks should be attached to the view 150 * object. They are called not only for retained objects that you explicitly submit 151 * for rendering, but also for each object in the hierarchy of a group that 152 * you submit. 153 * 154 * @constant kQ3CallbackElementTypeBeforeRender 155 * The callback will be called just before each retained object 156 * is passed to the renderer. If the callback returns 157 * kQ3Failure, then the object will not be passed to the renderer. 158 * @constant kQ3CallbackElementTypeAfterRender 159 * The callback will be called just after each retained object 160 * is passed to the renderer. The callback's status result 161 * is ignored. 162 * @constant kQ3CallbackElementTypeBeforePick 163 * The callback will be called just before each retained object 164 * is submitted for picking. If the callback returns 165 * kQ3Failure, then the object will not be submitted. 166 * @constant kQ3CallbackElementTypeAfterPick 167 * The callback will be called just after each retained object 168 * is submitted for picking. The callback's status result 169 * is ignored. 170 */ 171 typedef enum { 172 kQ3CallbackElementTypeBeforeRender = Q3_OBJECT_TYPE(0xF0, 'b', 'r', 'e'), 173 kQ3CallbackElementTypeAfterRender = Q3_OBJECT_TYPE(0xF0, 'a', 'r', 'e'), 174 kQ3CallbackElementTypeBeforePick = Q3_OBJECT_TYPE(0xF0, 'b', 'p', 'k'), 175 kQ3CallbackElementTypeAfterPick = Q3_OBJECT_TYPE(0xF0, 'a', 'p', 'k') 176 } TQ3EventCallbackElementTypes; 177 178 #endif 179 180 181 182 //============================================================================= 183 // Types 184 //----------------------------------------------------------------------------- 185 /*! 186 * @struct 187 * TCEUrlData 188 * @discussion 189 * Describes the data for a URL. 190 191 * @field url C string containing the full (scheme + path) URL. 192 * @field description Human readable description of the URL. 193 * @field options Options for the URL. 194 */ 195 typedef struct TCEUrlData { 196 char *url; 197 char *description; 198 TCEUrlOptions options; 199 } TCEUrlData; 200 201 202 #if QUESA_ALLOW_QD3D_EXTENSIONS 203 204 /*! 205 * @typedef 206 * TQ3ObjectEventCallback 207 * @discussion 208 * Applications can obtain callbacks as objects are processed 209 * by Quesa. Callbacks are installed as custom elements. In some cases, 210 * it may be necessary to attach the element to each object of interest, 211 * while in other cases the element may be attached to another object 212 * such as a view. See the discussions of element types such as 213 * kQ3ElementTypeBeforeRender for details about specific callbacks. 214 * 215 * Callbacks should return kQ3Success to continue processing the 216 * object, or kQ3Failure to cancel the operation (if possible). 217 * Some events, e.g., those which indicate the completion of an 218 * event, can not be cancelled and the result will be ignored. 219 * 220 * Event callbacks are only available for retained mode objects. 221 * 222 * <em>This functionality is not available in QD3D.</em> 223 * 224 * @param theObject The object being processed. 225 * @param theEventType The event occurring to the object. 226 * @param theHost The object to which the callback element is attached. 227 * @result Whether to continue with the event. 228 */ 229 typedef Q3_CALLBACK_API_C(TQ3Status, TQ3ObjectEventCallback)( 230 TQ3Object theObject, 231 TQ3ElementType theEventType, 232 TQ3Object theHost ); 233 #endif 234 235 236 237 //============================================================================= 238 // Function prototypes 239 //----------------------------------------------------------------------------- 240 /*! 241 * @function 242 * CENameElement_SetData 243 * @discussion 244 * Set the name element for an object. 245 * 246 * The name parameter should point to a C string, and will be copied 247 * by CENameElement_SetData. 248 * 249 * @param object The object to assign the name to. 250 * @param name The C string to associate with the object. 251 * @result Success or failure of the operation. 252 */ 253 Q3_EXTERN_API_C ( TQ3Status ) 254 CENameElement_SetData ( 255 TQ3Object object, 256 const char *name 257 ); 258 259 260 261 /*! 262 * @function 263 * CENameElement_GetData 264 * @discussion 265 * Get the name element for an object. 266 * 267 * The name parameter will receive a C string, or NULL if no name has 268 * been associated with the object. If a non-NULL pointer is returned, 269 * it must be disposed of with CENameElement_EmptyData. 270 * 271 * @param object The object to query. 272 * @param name Receives the name associated with the object. 273 * @result Success or failure of the operation. 274 */ 275 Q3_EXTERN_API_C ( TQ3Status ) 276 CENameElement_GetData ( 277 TQ3Object object, 278 char **name 279 ); 280 281 282 283 /*! 284 * @function 285 * CENameElement_PeekData 286 * @discussion 287 * Get the name element for an object. 288 * 289 * The name parameter will receive a C string, or NULL if no name has 290 * been associated with the object. If a non-NULL pointer is returned, 291 * it should be considered read-only and temporary. Unlike 292 * CENameElement_GetData, this function returns the actual string within 293 * the element, not a copy. 294 * 295 * @availability This function is not available in QD3D. 296 * @param object The object to query. 297 * @param name Receives the name associated with the object. 298 * @result Success or failure of the operation. 299 */ 300 #if QUESA_ALLOW_QD3D_EXTENSIONS 301 302 Q3_EXTERN_API_C ( TQ3Status ) 303 CENameElement_PeekData ( 304 TQ3Object object, 305 const char **name 306 ); 307 308 #endif // QUESA_ALLOW_QD3D_EXTENSIONS 309 310 311 /*! 312 * @function 313 * CENameElement_EmptyData 314 * @discussion 315 * Release the data returned by CENameElement_GetData. 316 * 317 * @param name A pointer previously returned by CENameElement_GetData. 318 * @result Success or failure of the operation. 319 */ 320 Q3_EXTERN_API_C ( TQ3Status ) 321 CENameElement_EmptyData ( 322 char **name 323 ); 324 325 326 327 /*! 328 * @function 329 * CEUrlElement_SetData 330 * @discussion 331 * Set the URL element for an object. 332 * 333 * The URL element data will be copied by CEUrlElement_SetData. 334 * 335 * @param object The object to assign the URL element to. 336 * @param urlData The URL data to associate with the object. 337 * @result Success or failure of the operation. 338 */ 339 Q3_EXTERN_API_C ( TQ3Status ) 340 CEUrlElement_SetData ( 341 TQ3Object object, 342 TCEUrlData *urlData 343 ); 344 345 346 347 /*! 348 * @function 349 * CEUrlElement_GetData 350 * @discussion 351 * Get the URL element for an object. 352 * 353 * The urlData parameter will receive a pointer to the URL data, or NULL 354 * if no URL element has been associated with the object. If a non-NULL 355 * pointer is returned, it must be disposed of with CEUrlElement_EmptyData. 356 * 357 * @param object The object to retrieve the URL element from. 358 * @param urlData Receives the URL data. 359 * @result Success or failure of the operation. 360 */ 361 Q3_EXTERN_API_C ( TQ3Status ) 362 CEUrlElement_GetData ( 363 TQ3Object object, 364 TCEUrlData **urlData 365 ); 366 367 368 369 /*! 370 * @function 371 * CEUrlElement_EmptyData 372 * @discussion 373 * Release the data returned by CEUrlElement_GetData. 374 * 375 * @param urlData A pointer previously returned by CEUrlElement_GetData. 376 * @result Success or failure of the operation. 377 */ 378 Q3_EXTERN_API_C ( TQ3Status ) 379 CEUrlElement_EmptyData ( 380 TCEUrlData **urlData 381 ); 382 383 384 385 #if QUESA_SUPPORT_QUICKTIME 386 387 /*! 388 * @function 389 * CEWireElement_SetData 390 * @discussion 391 * Set the QuickTime wired element for an object. 392 * 393 * @param object The object to assign the element to. 394 * @param wireData The QuickTime wired element to associate with the object. 395 * @result Success or failure of the operation. 396 */ 397 Q3_EXTERN_API_C ( TQ3Status ) 398 CEWireElement_SetData ( 399 TQ3Object object, 400 QTAtomContainer wireData 401 ); 402 403 404 405 /*! 406 * @function 407 * CEWireElement_GetData 408 * @discussion 409 * Get the QuickTime wired element for an object. 410 * 411 * The wireData parameter will receive a QTAtomContainer, or NULL if no 412 * wired element has been associated with the object. If a non-NULL pointer 413 * is returned, it must be disposed of with CEWireElement_EmptyData. 414 * 415 * @param object The object to query. 416 * @param wireData Receives the QuickTime wired element associated with the object. 417 * @result Success or failure of the operation. 418 */ 419 Q3_EXTERN_API_C ( TQ3Status ) 420 CEWireElement_GetData ( 421 TQ3Object object, 422 QTAtomContainer *wireData 423 ); 424 425 426 427 /*! 428 * @function 429 * CEWireElement_EmptyData 430 * @discussion 431 * Release the data returned by CEWireElement_GetData. 432 * 433 * @param wireData A pointer previously returned by CEWireElement_GetData. 434 * @result Success or failure of the operation. 435 */ 436 Q3_EXTERN_API_C ( TQ3Status ) 437 CEWireElement_EmptyData ( 438 QTAtomContainer *wireData 439 ); 440 441 #endif // QUESA_SUPPORT_QUICKTIME 442 443 444 445 446 447 //============================================================================= 448 // C++ postamble 449 //----------------------------------------------------------------------------- 450 #ifdef __cplusplus 451 } 452 #endif 453 454 #endif 455 456 457