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