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