Pileus Git - ~andy/gtk/blob - docs/reference/gtk/tmpl/gtktypeutils.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 Types
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Handle run-time type creation.
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Gtk's type system is extensible.  Because of that, types have to be
  10 managed at runtime.
  11 </para>
  12
  13 <!-- ##### SECTION See_Also ##### -->
  14 <para>
  15
  16 </para>
  17
  18 <!-- ##### TYPEDEF GtkType ##### -->
  19 <para>
  20 @GtkType is unique integer identifying the type.  The guts of the
  21 information about the type is held in a private struct named
  22 GtkTypeNode.
  23 </para>
  24
  25
  26 <!-- ##### ENUM GtkFundamentalType ##### -->
  27 <para>
  28 @GtkFundamentalType is an enumerated type which lists all the possible
  29 fundamental types (e.g. char, uchar, int, long, float, etc).
  30 </para>
  31
  32 @GTK_TYPE_INVALID:
  33 @GTK_TYPE_NONE:
  34 @GTK_TYPE_ENUM:
  35 @GTK_TYPE_FLAGS:
  36 @GTK_TYPE_CHAR:
  37 @GTK_TYPE_UCHAR:
  38 @GTK_TYPE_BOOL:
  39 @GTK_TYPE_INT:
  40 @GTK_TYPE_UINT:
  41 @GTK_TYPE_LONG:
  42 @GTK_TYPE_ULONG:
  43 @GTK_TYPE_FLOAT:
  44 @GTK_TYPE_DOUBLE:
  45 @GTK_TYPE_STRING:
  46 @GTK_TYPE_BOXED:
  47 @GTK_TYPE_POINTER:
  48
  49 <!-- ##### MACRO GTK_CLASS_NAME ##### -->
  50 <para>
  51
  52 </para>
  53
  54 @class:
  55
  56
  57 <!-- ##### MACRO GTK_CLASS_TYPE ##### -->
  58 <para>
  59
  60 </para>
  61
  62 @class:
  63
  64
  65 <!-- ##### MACRO GTK_TYPE_IS_OBJECT ##### -->
  66 <para>
  67
  68 </para>
  69
  70 @type:
  71
  72
  73 <!-- ##### MACRO GTK_TYPE_FUNDAMENTAL_LAST ##### -->
  74 <para>
  75 The highest-numbered structured or flat enumerated type value.
  76 </para>
  77
  78
  79
  80 <!-- ##### MACRO GTK_TYPE_FUNDAMENTAL_MAX ##### -->
  81 <para>
  82 The highest maximum fundamental enumerated type value.
  83 </para>
  84
  85
  86
  87 <!-- ##### MACRO GTK_STRUCT_OFFSET ##### -->
  88 <para>
  89 Use in place of offsetof(), which is used if it exists.
  90 </para>
  91
  92 <!-- # Unused Parameters # -->
  93 @struct: The type of the structure.
  94 @field: The field within the structure.
  95
  96
  97 <!-- ##### MACRO GTK_CHECK_CAST ##### -->
  98 <para>
  99 Cast the object in @tobj into @cast.  If GTK_NO_CHECK_CASTS is
 100 defined, just cast it.  Otherwise, check to see if we can cast @tobj
 101 into a @cast.
 102 </para>
 103
 104 <!-- # Unused Parameters # -->
 105 @tobj: a pointer to a GtkObject.
 106 @cast_type: a Gtk type.
 107 @cast: a C type
 108
 109
 110 <!-- ##### MACRO GTK_CHECK_CLASS_CAST ##### -->
 111 <para>
 112 Cast the object in @tobj into @cast.  If GTK_NO_CHECK_CASTS is
 113 defined, just cast it.  Otherwise, check to see if we can cast @tobj
 114 into a @cast.
 115 </para>
 116
 117 <!-- # Unused Parameters # -->
 118 @tclass: a pointer to a GtkClassInitFunc
 119 @cast_type: a Gtk type.
 120 @cast: a C type
 121
 122
 123 <!-- ##### MACRO GTK_CHECK_TYPE ##### -->
 124 <para>
 125 Determines whether @type_object is a type of @otype.
 126 </para>
 127
 128 <!-- # Unused Parameters # -->
 129 @type_object: A GtkTypeObject object.
 130 @otype:
 131
 132
 133 <!-- ##### MACRO GTK_CHECK_CLASS_TYPE ##### -->
 134 <para>
 135 Determines whether @type_class is a type of @otype.
 136 </para>
 137
 138 <!-- # Unused Parameters # -->
 139 @type_class: A GtkTypeClass class.
 140 @otype:
 141
 142
 143 <!-- ##### MACRO GTK_CHECK_GET_CLASS ##### -->
 144 <para>
 145
 146 </para>
 147
 148
 149
 150 <!-- ##### MACRO GTK_FUNDAMENTAL_TYPE ##### -->
 151 <para>
 152 Convert a gtk type into a fundamental type
 153 </para>
 154
 155 <!-- # Unused Parameters # -->
 156 @type:
 157
 158
 159 <!-- ##### MACRO GTK_SIGNAL_FUNC ##### -->
 160 <para>
 161 Just a macroized cast into a GtkSignalFunc
 162 </para>
 163
 164 @f:
 165
 166
 167 <!-- ##### TYPEDEF GtkClassInitFunc ##### -->
 168 <para>
 169 Define a function pointer.
 170 </para>
 171
 172
 173 <!-- ##### TYPEDEF GtkObjectInitFunc ##### -->
 174 <para>
 175 Define a function pointer.
 176 </para>
 177
 178
 179 <!-- ##### USER_FUNCTION GtkSignalFunc ##### -->
 180 <para>
 181 Define a function pointer.
 182 </para>
 183
 184
 185
 186 <!-- ##### USER_FUNCTION GtkFunction ##### -->
 187 <para>
 188 Define a function pointer.
 189 </para>
 190
 191 @data: gpointer
 192 @Returns: gint
 193
 194
 195 <!-- ##### USER_FUNCTION GtkDestroyNotify ##### -->
 196 <para>
 197 Define a function pointer.
 198 </para>
 199
 200 @data: gpointer
 201
 202
 203 <!-- ##### USER_FUNCTION GtkCallbackMarshal ##### -->
 204 <para>
 205 Define a function pointer.
 206 </para>
 207
 208 @object: GtkObject*
 209 @data: gpointer
 210 @n_args: guint
 211 @args: GtkArg*
 212
 213
 214 <!-- ##### TYPEDEF GtkSignalMarshaller ##### -->
 215 <para>
 216 Define a function pointer.
 217 </para>
 218
 219
 220 <!-- ##### USER_FUNCTION GtkArgGetFunc ##### -->
 221 <para>
 222 Define a function pointer.  Deprecated.
 223 </para>
 224
 225 @object:
 226 @arg:
 227 @arg_id:
 228
 229
 230 <!-- ##### USER_FUNCTION GtkArgSetFunc ##### -->
 231 <para>
 232 Define a function pointer.  Deprecated.
 233 </para>
 234
 235 @object:
 236 @arg:
 237 @arg_id:
 238
 239
 240 <!-- ##### TYPEDEF GtkTypeObject ##### -->
 241 <para>
 242 A GtkTypeObject defines the minimum structure requirements
 243 for type instances. Type instances returned from gtk_type_new ()
 244 and initialized through a GtkObjectInitFunc need to directly inherit
 245 from this structure or at least copy its fields one by one.
 246 </para>
 247
 248
 249 <!-- ##### STRUCT GtkArg ##### -->
 250 <para>
 251 This is a structure that we use to pass in typed values (and names).
 252 </para>
 253
 254 @type:
 255 @name:
 256
 257 <!-- ##### MACRO GTK_VALUE_CHAR ##### -->
 258 <para>
 259 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_CHAR
 260 </para>
 261
 262 @a:
 263
 264
 265 <!-- ##### MACRO GTK_VALUE_UCHAR ##### -->
 266 <para>
 267 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_UCHAR
 268 </para>
 269
 270 @a:
 271
 272
 273 <!-- ##### MACRO GTK_VALUE_BOOL ##### -->
 274 <para>
 275 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_BOOL
 276 </para>
 277
 278 @a:
 279
 280
 281 <!-- ##### MACRO GTK_VALUE_INT ##### -->
 282 <para>
 283 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_INT
 284 </para>
 285
 286 @a:
 287
 288
 289 <!-- ##### MACRO GTK_VALUE_UINT ##### -->
 290 <para>
 291 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_UINT
 292 </para>
 293
 294 @a:
 295
 296
 297 <!-- ##### MACRO GTK_VALUE_LONG ##### -->
 298 <para>
 299 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_LONG
 300 </para>
 301
 302 @a:
 303
 304
 305 <!-- ##### MACRO GTK_VALUE_ULONG ##### -->
 306 <para>
 307 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ULONG
 308 </para>
 309
 310 @a:
 311
 312
 313 <!-- ##### MACRO GTK_VALUE_FLOAT ##### -->
 314 <para>
 315 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_FLOAT
 316 </para>
 317
 318 @a:
 319
 320
 321 <!-- ##### MACRO GTK_VALUE_DOUBLE ##### -->
 322 <para>
 323 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_DOUBLE
 324 </para>
 325
 326 @a:
 327
 328
 329 <!-- ##### MACRO GTK_VALUE_STRING ##### -->
 330 <para>
 331 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_STRING
 332 </para>
 333
 334 @a:
 335
 336
 337 <!-- ##### MACRO GTK_VALUE_ENUM ##### -->
 338 <para>
 339 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_ENUM
 340 </para>
 341
 342 @a:
 343
 344
 345 <!-- ##### MACRO GTK_VALUE_FLAGS ##### -->
 346 <para>
 347 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_FLAGS
 348 </para>
 349
 350 @a:
 351
 352
 353 <!-- ##### MACRO GTK_VALUE_BOXED ##### -->
 354 <para>
 355 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_BOXED
 356 </para>
 357
 358 @a:
 359
 360
 361 <!-- ##### MACRO GTK_VALUE_POINTER ##### -->
 362 <para>
 363 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_POINTER
 364 </para>
 365
 366 @a:
 367
 368
 369 <!-- ##### MACRO GTK_VALUE_OBJECT ##### -->
 370 <para>
 371 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_OBJECT
 372 </para>
 373
 374 @a:
 375
 376
 377 <!-- ##### MACRO GTK_VALUE_SIGNAL ##### -->
 378 <para>
 379 Use to get the value of a GtkArg whose GtkType is GTK_TYPE_SIGNAL
 380 </para>
 381
 382 @a:
 383
 384
 385 <!-- ##### MACRO GTK_RETLOC_CHAR ##### -->
 386 <para>
 387 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_CHAR
 388 </para>
 389
 390 @a:
 391
 392
 393 <!-- ##### MACRO GTK_RETLOC_UCHAR ##### -->
 394 <para>
 395 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_UCHAR
 396 </para>
 397
 398 @a:
 399
 400
 401 <!-- ##### MACRO GTK_RETLOC_BOOL ##### -->
 402 <para>
 403 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_BOOL
 404 </para>
 405
 406 @a:
 407
 408
 409 <!-- ##### MACRO GTK_RETLOC_INT ##### -->
 410 <para>
 411 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_INT
 412 </para>
 413
 414 @a:
 415
 416
 417 <!-- ##### MACRO GTK_RETLOC_UINT ##### -->
 418 <para>
 419 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_UINT
 420 </para>
 421
 422 @a:
 423
 424
 425 <!-- ##### MACRO GTK_RETLOC_LONG ##### -->
 426 <para>
 427 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_LONG
 428 </para>
 429
 430 @a:
 431
 432
 433 <!-- ##### MACRO GTK_RETLOC_ULONG ##### -->
 434 <para>
 435 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_ULONG
 436 </para>
 437
 438 @a:
 439
 440
 441 <!-- ##### MACRO GTK_RETLOC_FLOAT ##### -->
 442 <para>
 443 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_FLOAT
 444 </para>
 445
 446 @a:
 447
 448
 449 <!-- ##### MACRO GTK_RETLOC_DOUBLE ##### -->
 450 <para>
 451 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_DOUBLE
 452 </para>
 453
 454 @a:
 455
 456
 457 <!-- ##### MACRO GTK_RETLOC_STRING ##### -->
 458 <para>
 459 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_STRING
 460 </para>
 461
 462 @a:
 463
 464
 465 <!-- ##### MACRO GTK_RETLOC_ENUM ##### -->
 466 <para>
 467 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_ENUM
 468 </para>
 469
 470 @a:
 471
 472
 473 <!-- ##### MACRO GTK_RETLOC_FLAGS ##### -->
 474 <para>
 475 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_FLAGS
 476 </para>
 477
 478 @a:
 479
 480
 481 <!-- ##### MACRO GTK_RETLOC_BOXED ##### -->
 482 <para>
 483 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_BOXED
 484 </para>
 485
 486 @a:
 487
 488
 489 <!-- ##### MACRO GTK_RETLOC_POINTER ##### -->
 490 <para>
 491 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_POINTER
 492 </para>
 493
 494 @a:
 495
 496
 497 <!-- ##### MACRO GTK_RETLOC_OBJECT ##### -->
 498 <para>
 499 If the GtkArg contains a pointer to the value, this macro will be a pointer to a GTK_TYPE_OBJECT
 500 </para>
 501
 502 @a:
 503
 504
 505 <!-- ##### STRUCT GtkTypeInfo ##### -->
 506 <para>
 507 Holds information about the type.  @gtk_type_name returns the name.
 508 @object_size is somehow set to the number of bytes that an instance of
 509 the object will occupy.  @class_init_func holds the type's
 510 initialization function.  @object_init_func holds the initialization
 511 function for an instance of the object.  @reserved_1 is used for
 512 GtkEnumValue to hold the enumerated values.
 513 </para>
 514
 515 @type_name:
 516 @object_size:
 517 @class_size:
 518 @class_init_func:
 519 @object_init_func:
 520 @reserved_1:
 521 @reserved_2:
 522 @base_class_init_func:
 523
 524 <!-- ##### TYPEDEF GtkTypeClass ##### -->
 525 <para>
 526 The base structure for a Gtk Type.  Every type inherits this as a base structure.
 527 </para>
 528
 529
 530 <!-- ##### TYPEDEF GtkEnumValue ##### -->
 531 <para>
 532 A structure which contains a single enum value, and its name, and it's
 533 nickname.
 534 </para>
 535
 536
 537 <!-- ##### TYPEDEF GtkFlagValue ##### -->
 538 <para>
 539
 540 </para>
 541
 542
 543 <!-- ##### FUNCTION gtk_type_init ##### -->
 544 <para>
 545 Initialize the data structures associated with gtk types.
 546 </para>
 547
 548 @debug_flags:
 549
 550
 551 <!-- ##### FUNCTION gtk_type_unique ##### -->
 552 <para>
 553 Create a new, unique type.
 554 </para>
 555
 556 @parent_type: if zero, a fundamental type is created.
 557 @gtkinfo:
 558 @Returns: the new GtkType.
 559 <!-- # Unused Parameters # -->
 560 @type_info: must not be null, and @type_info->type_name must also not be null.
 561
 562
 563 <!-- ##### FUNCTION gtk_type_name ##### -->
 564 <para>
 565 </para>
 566
 567 @type: a GtkType
 568 @Returns: a pointer to the name of a type, or NULL if it has none.
 569
 570
 571 <!-- ##### FUNCTION gtk_type_from_name ##### -->
 572 <para>
 573 Get the internal representation of a type given its name.
 574 </para>
 575
 576 @name: the name of a gtk type
 577 @Returns: a GtkType
 578
 579
 580 <!-- ##### FUNCTION gtk_type_parent ##### -->
 581 <para>
 582
 583 </para>
 584
 585 @type: a GtkType
 586 @Returns: the GtkType of the parent
 587
 588
 589 <!-- ##### FUNCTION gtk_type_class ##### -->
 590 <para>
 591 Return a gpointer pointing to the class of @type or NULL if there was
 592 any trouble identifying @type.  Initialize the class if necessary.
 593 </para>
 594
 595 @type: a GtkType
 596 @Returns: gpointer to the klass.
 597
 598
 599 <!-- ##### FUNCTION gtk_type_new ##### -->
 600 <para>
 601 Create a new object of a given type, and return a gpointer to it.
 602 Returns NULL if you give it an invalid type.  It allocates the object
 603 out of the type's memory chunk if there is a memory chunk.  The object
 604 has all the proper initializers called.
 605 </para>
 606
 607 @type: GtkType
 608 @Returns: gpointer to a GtkTypeObject
 609
 610
 611 <!-- ##### FUNCTION gtk_type_is_a ##### -->
 612 <para>
 613 Look in the type hierarchy to see if @type has @is_a_type among its
 614 ancestors.  Do so with a simple lookup, not a loop.
 615 </para>
 616
 617 @type: GtkType
 618 @is_a_type: GtkType
 619 @Returns:
 620
 621
 622 <!-- ##### FUNCTION gtk_type_enum_get_values ##### -->
 623 <para>
 624 If @enum_type has values, then return a pointer to all of them.
 625 </para>
 626
 627 @enum_type: GtkType
 628 @Returns: GtkEnumValue*
 629
 630
 631 <!-- ##### FUNCTION gtk_type_flags_get_values ##### -->
 632 <para>
 633 If @flags_type has values, then return a pointer to all of them.
 634 </para>
 635
 636 @flags_type:
 637 @Returns: GtkFlagValue*
 638
 639
 640 <!-- ##### FUNCTION gtk_type_enum_find_value ##### -->
 641 <para>
 642 Return a pointer to one of @enum_type's GtkEnumValues's whose name (or nickname) matches @value_name.
 643 </para>
 644
 645 @enum_type: GtkType
 646 @value_name:
 647 @Returns: GtkEnumValue*
 648
 649
 650 <!-- ##### FUNCTION gtk_type_flags_find_value ##### -->
 651 <para>
 652 Return a pointer to one of @flag_type's GtkFlagValue's whose name (or nickname) matches @value_name.
 653 </para>
 654
 655 @flags_type:
 656 @value_name:
 657 @Returns: GtkFlagValue*
 658 <!-- # Unused Parameters # -->
 659 @flag_type: GtkType
 660
 661