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. <type>char</type>, <type>uchar</type>, <type>int</type>,
  30 <type>long</type>, <type>float</type>, etc).
  31 </para>
  32
  33 @GTK_TYPE_INVALID:
  34 @GTK_TYPE_NONE:
  35 @GTK_TYPE_ENUM:
  36 @GTK_TYPE_FLAGS:
  37 @GTK_TYPE_CHAR:
  38 @GTK_TYPE_UCHAR:
  39 @GTK_TYPE_BOOL:
  40 @GTK_TYPE_INT:
  41 @GTK_TYPE_UINT:
  42 @GTK_TYPE_LONG:
  43 @GTK_TYPE_ULONG:
  44 @GTK_TYPE_FLOAT:
  45 @GTK_TYPE_DOUBLE:
  46 @GTK_TYPE_STRING:
  47 @GTK_TYPE_BOXED:
  48 @GTK_TYPE_POINTER:
  49
  50 <!-- ##### MACRO GTK_CLASS_NAME ##### -->
  51 <para>
  52 Returns the type name of @class.
  53 </para>
  54
  55 @class: a #GtkTypeClass.
  56
  57
  58 <!-- ##### MACRO GTK_CLASS_TYPE ##### -->
  59 <para>
  60 Returns the type of @class.
  61 </para>
  62
  63 @class: a #GtkTypeClass.
  64
  65
  66 <!-- ##### MACRO GTK_TYPE_IS_OBJECT ##### -->
  67 <para>
  68 Returns %TRUE if @type is a %GTK_TYPE_OBJECT.
  69 </para>
  70
  71 @type: a #GtkType.
  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 maximum fundamental enumerated type value.
  84 </para>
  85
  86
  87
  88 <!-- ##### MACRO GTK_STRUCT_OFFSET ##### -->
  89 <para>
  90 Use in place of <function>offsetof()</function>, 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 Casts 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 Casts 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 Converts 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 Defines a function pointer.
 171 </para>
 172
 173
 174 <!-- ##### TYPEDEF GtkObjectInitFunc ##### -->
 175 <para>
 176 Defines a function pointer.
 177 </para>
 178
 179
 180 <!-- ##### USER_FUNCTION GtkSignalFunc ##### -->
 181 <para>
 182 Defines a function pointer.
 183 </para>
 184
 185
 186
 187 <!-- ##### USER_FUNCTION GtkFunction ##### -->
 188 <para>
 189 Defines a function pointer.
 190 </para>
 191
 192 @data: gpointer
 193 @Returns: gint
 194
 195
 196 <!-- ##### USER_FUNCTION GtkDestroyNotify ##### -->
 197 <para>
 198 Defines a function pointer.
 199 </para>
 200
 201 @data: gpointer
 202
 203
 204 <!-- ##### USER_FUNCTION GtkCallbackMarshal ##### -->
 205 <para>
 206 Defines a function pointer.
 207 </para>
 208
 209 @object: GtkObject*
 210 @data: gpointer
 211 @n_args: guint
 212 @args: GtkArg*
 213
 214
 215 <!-- ##### TYPEDEF GtkSignalMarshaller ##### -->
 216 <para>
 217 Defines a function pointer.
 218 </para>
 219
 220
 221 <!-- ##### TYPEDEF GtkTypeObject ##### -->
 222 <para>
 223 A #GtkTypeObject defines the minimum structure requirements
 224 for type instances. Type instances returned from gtk_type_new ()
 225 and initialized through a #GtkObjectInitFunc need to directly inherit
 226 from this structure or at least copy its fields one by one.
 227 </para>
 228
 229
 230 <!-- ##### STRUCT GtkArg ##### -->
 231 <para>
 232 This is a structure that we use to pass in typed values (and names).
 233 </para>
 234
 235 @type:
 236 @name:
 237
 238 <!-- ##### MACRO GTK_VALUE_CHAR ##### -->
 239 <para>
 240 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_CHAR.
 241 </para>
 242
 243 @a: a #GtkArg.
 244
 245
 246 <!-- ##### MACRO GTK_VALUE_UCHAR ##### -->
 247 <para>
 248 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_UCHAR.
 249 </para>
 250
 251 @a: a #GtkArg.
 252
 253
 254 <!-- ##### MACRO GTK_VALUE_BOOL ##### -->
 255 <para>
 256 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_BOOL.
 257 </para>
 258
 259 @a: a #GtkArg.
 260
 261
 262 <!-- ##### MACRO GTK_VALUE_INT ##### -->
 263 <para>
 264 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_INT.
 265 </para>
 266
 267 @a: a #GtkArg.
 268
 269
 270 <!-- ##### MACRO GTK_VALUE_UINT ##### -->
 271 <para>
 272 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_UINT.
 273 </para>
 274
 275 @a: a #GtkArg.
 276
 277
 278 <!-- ##### MACRO GTK_VALUE_LONG ##### -->
 279 <para>
 280 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_LONG.
 281 </para>
 282
 283 @a: a #GtkArg.
 284
 285
 286 <!-- ##### MACRO GTK_VALUE_ULONG ##### -->
 287 <para>
 288 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_ULONG.
 289 </para>
 290
 291 @a: a #GtkArg.
 292
 293
 294 <!-- ##### MACRO GTK_VALUE_FLOAT ##### -->
 295 <para>
 296 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_FLOAT.
 297 </para>
 298
 299 @a: a #GtkArg.
 300
 301
 302 <!-- ##### MACRO GTK_VALUE_DOUBLE ##### -->
 303 <para>
 304 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_DOUBLE.
 305 </para>
 306
 307 @a: a #GtkArg.
 308
 309
 310 <!-- ##### MACRO GTK_VALUE_STRING ##### -->
 311 <para>
 312 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_STRING.
 313 </para>
 314
 315 @a: a #GtkArg.
 316
 317
 318 <!-- ##### MACRO GTK_VALUE_ENUM ##### -->
 319 <para>
 320 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_ENUM.
 321 </para>
 322
 323 @a: a #GtkArg.
 324
 325
 326 <!-- ##### MACRO GTK_VALUE_FLAGS ##### -->
 327 <para>
 328 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_FLAGS.
 329 </para>
 330
 331 @a: a #GtkArg.
 332
 333
 334 <!-- ##### MACRO GTK_VALUE_BOXED ##### -->
 335 <para>
 336 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_BOXED.
 337 </para>
 338
 339 @a: a #GtkArg.
 340
 341
 342 <!-- ##### MACRO GTK_VALUE_POINTER ##### -->
 343 <para>
 344 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_POINTER.
 345 </para>
 346
 347 @a: a #GtkArg.
 348
 349
 350 <!-- ##### MACRO GTK_VALUE_OBJECT ##### -->
 351 <para>
 352 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_OBJECT.
 353 </para>
 354
 355 @a: a #GtkArg.
 356
 357
 358 <!-- ##### MACRO GTK_VALUE_SIGNAL ##### -->
 359 <para>
 360 Gets the value of a #GtkArg whose #GtkType is %GTK_TYPE_SIGNAL.
 361 </para>
 362
 363 @a: a #GtkArg.
 364
 365
 366 <!-- ##### MACRO GTK_RETLOC_CHAR ##### -->
 367 <para>
 368 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_CHAR.
 369 </para>
 370
 371 @a: a #GtkArg.
 372
 373
 374 <!-- ##### MACRO GTK_RETLOC_UCHAR ##### -->
 375 <para>
 376 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_UCHAR.
 377 </para>
 378
 379 @a: a #GtkArg.
 380
 381
 382 <!-- ##### MACRO GTK_RETLOC_BOOL ##### -->
 383 <para>
 384 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_BOOL.
 385 </para>
 386
 387 @a: a #GtkArg.
 388
 389
 390 <!-- ##### MACRO GTK_RETLOC_INT ##### -->
 391 <para>
 392 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_INT.
 393 </para>
 394
 395 @a: a #GtkArg.
 396
 397
 398 <!-- ##### MACRO GTK_RETLOC_UINT ##### -->
 399 <para>
 400 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_UINT.
 401 </para>
 402
 403 @a: a #GtkArg.
 404
 405
 406 <!-- ##### MACRO GTK_RETLOC_LONG ##### -->
 407 <para>
 408 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_LONG.
 409 </para>
 410
 411 @a: a #GtkArg.
 412
 413
 414 <!-- ##### MACRO GTK_RETLOC_ULONG ##### -->
 415 <para>
 416 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_ULONG.
 417 </para>
 418
 419 @a: a #GtkArg.
 420
 421
 422 <!-- ##### MACRO GTK_RETLOC_FLOAT ##### -->
 423 <para>
 424 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_FLOAT.
 425 </para>
 426
 427 @a: a #GtkArg.
 428
 429
 430 <!-- ##### MACRO GTK_RETLOC_DOUBLE ##### -->
 431 <para>
 432 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_DOUBLE.
 433 </para>
 434
 435 @a: a #GtkArg.
 436
 437
 438 <!-- ##### MACRO GTK_RETLOC_STRING ##### -->
 439 <para>
 440 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_STRING.
 441 </para>
 442
 443 @a: a #GtkArg.
 444
 445
 446 <!-- ##### MACRO GTK_RETLOC_ENUM ##### -->
 447 <para>
 448 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_ENUM.
 449 </para>
 450
 451 @a: a #GtkArg.
 452
 453
 454 <!-- ##### MACRO GTK_RETLOC_FLAGS ##### -->
 455 <para>
 456 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_FLAGS.
 457 </para>
 458
 459 @a: a #GtkArg.
 460
 461
 462 <!-- ##### MACRO GTK_RETLOC_BOXED ##### -->
 463 <para>
 464 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_BOXED.
 465 </para>
 466
 467 @a: a #GtkArg.
 468
 469
 470 <!-- ##### MACRO GTK_RETLOC_POINTER ##### -->
 471 <para>
 472 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_POINTER.
 473 </para>
 474
 475 @a: a #GtkArg.
 476
 477
 478 <!-- ##### MACRO GTK_RETLOC_OBJECT ##### -->
 479 <para>
 480 If the #GtkArg contains a pointer to the value, this macro will be a pointer to a %GTK_TYPE_OBJECT.
 481 </para>
 482
 483 @a: a #GtkArg.
 484
 485
 486 <!-- ##### STRUCT GtkTypeInfo ##### -->
 487 <para>
 488 Holds information about the type.  gtk_type_name() returns the name.
 489 @object_size is somehow set to the number of bytes that an instance of
 490 the object will occupy.  @class_init_func holds the type's
 491 initialization function.  @object_init_func holds the initialization
 492 function for an instance of the object.  @reserved_1 is used for
 493 #GtkEnumValue to hold the enumerated values.
 494 </para>
 495
 496 @type_name:
 497 @object_size:
 498 @class_size:
 499 @class_init_func:
 500 @object_init_func:
 501 @reserved_1:
 502 @reserved_2:
 503 @base_class_init_func:
 504
 505 <!-- ##### TYPEDEF GtkTypeClass ##### -->
 506 <para>
 507 The base structure for a Gtk type. Every type inherits this as a base structure.
 508 </para>
 509
 510
 511 <!-- ##### TYPEDEF GtkEnumValue ##### -->
 512 <para>
 513 A structure which contains a single enum value, and its name, and it's
 514 nickname.
 515 </para>
 516
 517
 518 <!-- ##### TYPEDEF GtkFlagValue ##### -->
 519 <para>
 520
 521 </para>
 522
 523
 524 <!-- ##### FUNCTION gtk_type_init ##### -->
 525 <para>
 526 Initializes the data structures associated with Gtk types.
 527 </para>
 528
 529 @debug_flags:
 530
 531
 532 <!-- ##### FUNCTION gtk_type_unique ##### -->
 533 <para>
 534 Creates a new, unique type.
 535 </para>
 536
 537 @parent_type: if zero, a fundamental type is created.
 538 @gtkinfo:
 539 @Returns: the new #GtkType.
 540 <!-- # Unused Parameters # -->
 541 @type_info: must not be %NULL, and @type_info->type_name must also not be %NULL.
 542
 543
 544 <!-- ##### MACRO gtk_type_name ##### -->
 545 <para>
 546 Returns a pointer to the name of a type, or %NULL if it has none.
 547 </para>
 548
 549 @type: a #GtkType.
 550 @Returns: a pointer to the name of a type, or %NULL if it has none.
 551
 552
 553 <!-- ##### MACRO gtk_type_from_name ##### -->
 554 <para>
 555 Gets the internal representation of a type, given its name.
 556 </para>
 557
 558 @name: the name of a Gtk type
 559 @Returns: a #GtkType.
 560
 561
 562 <!-- ##### MACRO gtk_type_parent ##### -->
 563 <para>
 564 Returns the parent type of a #GtkType.
 565 </para>
 566
 567 @type: a #GtkType.
 568 @Returns: the #GtkType of the parent.
 569
 570
 571 <!-- ##### FUNCTION gtk_type_class ##### -->
 572 <para>
 573 Returns a pointer pointing to the class of @type or %NULL if there was
 574 any trouble identifying @type.  Initializes the class if necessary.
 575 </para>
 576
 577 @type: a #GtkType.
 578 @Returns: pointer to the class.
 579
 580
 581 <!-- ##### FUNCTION gtk_type_new ##### -->
 582 <para>
 583 Creates a new object of a given type, and return a pointer to it.
 584 Returns %NULL if you give it an invalid type.  It allocates the object
 585 out of the type's memory chunk if there is a memory chunk.  The object
 586 has all the proper initializers called.
 587 </para>
 588
 589 @type: a #GtkType.
 590 @Returns: pointer to a #GtkTypeObject.
 591
 592
 593 <!-- ##### MACRO gtk_type_is_a ##### -->
 594 <para>
 595 Looks in the type hierarchy to see if @type has @is_a_type among its
 596 ancestors.  Do so with a simple lookup, not a loop.
 597 </para>
 598
 599 @type: a #GtkType.
 600 @is_a_type: another #GtkType.
 601 @Returns: %TRUE if @type is a @is_a_type.
 602
 603
 604 <!-- ##### FUNCTION gtk_type_enum_get_values ##### -->
 605 <para>
 606 If @enum_type has values, then return a pointer to all of them.
 607 </para>
 608
 609 @enum_type: a #GtkType.
 610 @Returns: #GtkEnumValue*
 611
 612
 613 <!-- ##### FUNCTION gtk_type_flags_get_values ##### -->
 614 <para>
 615 If @flags_type has values, then return a pointer to all of them.
 616 </para>
 617
 618 @flags_type: a #GtkType.
 619 @Returns: #GtkFlagValue*
 620
 621
 622 <!-- ##### FUNCTION gtk_type_enum_find_value ##### -->
 623 <para>
 624 Returns a pointer to one of @enum_type's #GtkEnumValues's whose name (or nickname) matches @value_name.
 625 </para>
 626
 627 @enum_type: a #GtkType.
 628 @value_name: the name to look for.
 629 @Returns: #GtkEnumValue*
 630
 631
 632 <!-- ##### FUNCTION gtk_type_flags_find_value ##### -->
 633 <para>
 634 Returns a pointer to one of @flag_type's #GtkFlagValue's whose name (or nickname) matches @value_name.
 635 </para>
 636
 637 @flags_type: a #GtkType.
 638 @value_name: the name to look for.
 639 @Returns: #GtkFlagValue*
 640 <!-- # Unused Parameters # -->
 641 @flag_type: GtkType
 642
 643