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