docs/reference/gobject/tmpl/gobject-unused.sgml

   1 <!-- ##### SECTION ./tmpl/closures.sgml:Long_Description ##### -->
   2 <para>
   3
   4 </para>
   5
   6
   7 <!-- ##### SECTION ./tmpl/closures.sgml:See_Also ##### -->
   8 <para>
   9
  10 </para>
  11
  12
  13 <!-- ##### SECTION ./tmpl/closures.sgml:Short_Description ##### -->
  14
  15
  16
  17 <!-- ##### SECTION ./tmpl/closures.sgml:Title ##### -->
  18 Closures
  19
  20
  21 <!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Long_Description ##### -->
  22 <para>
  23
  24 </para>
  25
  26
  27 <!-- ##### SECTION ./tmpl/enumerations_flags.sgml:See_Also ##### -->
  28 <para>
  29
  30 </para>
  31
  32
  33 <!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Short_Description ##### -->
  34
  35
  36
  37 <!-- ##### SECTION ./tmpl/enumerations_flags.sgml:Title ##### -->
  38 Enumeration and Flag Types
  39
  40
  41 <!-- ##### SECTION ./tmpl/gboxed.sgml:Long_Description ##### -->
  42 <para>
  43
  44 </para>
  45
  46
  47 <!-- ##### SECTION ./tmpl/gboxed.sgml:See_Also ##### -->
  48 <para>
  49
  50 </para>
  51
  52
  53 <!-- ##### SECTION ./tmpl/gboxed.sgml:Short_Description ##### -->
  54
  55
  56
  57 <!-- ##### SECTION ./tmpl/gboxed.sgml:Title ##### -->
  58 gboxed
  59
  60
  61 <!-- ##### SECTION ./tmpl/generic_values.sgml:Long_Description ##### -->
  62 <para>
  63
  64 </para>
  65
  66
  67 <!-- ##### SECTION ./tmpl/generic_values.sgml:See_Also ##### -->
  68 <para>
  69
  70 </para>
  71
  72
  73 <!-- ##### SECTION ./tmpl/generic_values.sgml:Short_Description ##### -->
  74
  75
  76
  77 <!-- ##### SECTION ./tmpl/generic_values.sgml:Title ##### -->
  78 Generic values
  79
  80
  81 <!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Long_Description ##### -->
  82 <para>
  83
  84 </para>
  85
  86
  87 <!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:See_Also ##### -->
  88 <para>
  89
  90 </para>
  91
  92
  93 <!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Short_Description ##### -->
  94
  95
  96
  97 <!-- ##### SECTION ./tmpl/gtypemodule.sgml.sgml:Title ##### -->
  98 gtypemodule.sgml
  99
 100
 101 <!-- ##### SECTION ./tmpl/gtypemodule.sgml:Long_Description ##### -->
 102 <para>
 103 #GTypeModule provides a simple implementation of the #GTypePlugin
 104 interface. The model of #GTypeModule is a dynamically loaded module
 105 which implements some number of types and interface
 106 implementations. When the module is loaded, it registerse its types
 107 and interfaces using g_type_module_register_type() and
 108 g_type_module_add_interface().  As long as any instances of these
 109 types and interface implementations are in use, the module is kept
 110 loaded. When the types and interfaces are gone, the module may be
 111 unloaded. If the types and interfaces become used again, the module
 112 will be reloaded.
 113 </para>
 114 <para>
 115 Keeping track of whether the module should be loaded or not is done by
 116 using a use count - it starts at zero, and whenever it is greater than
 117 zero, the module is loaded. The use count is maintained internally by
 118 the type system, but also can be explicitely controlled by
 119 g_type_module_use() and g_type_module_unuse(). Typically, when loading
 120 a module for the first type, g_type_module_use() will be used to load
 121 it so that it can initialize its types. At some later point, when the
 122 module no longer needs to be loaded except for the type
 123 implementations it contains, g_type_module_unuse() is called.
 124 </para>
 125 <para>
 126 #GTypeModule does not actually provide any implementation of module
 127 loading and unloading. To create a particular module type you must
 128 derive from #GTypeModule and implement the load and unload functions
 129 in #GTypeModuleClass.
 130 </para>
 131
 132
 133 <!-- ##### SECTION ./tmpl/gtypemodule.sgml:See_Also ##### -->
 134 <para>
 135 <variablelist>
 136
 137 <varlistentry>
 138 <term>#GTypePlugin</term>
 139 <listitem><para>The abstract type loader interface.</para></listitem>
 140 </varlistentry>
 141
 142 <varlistentry>
 143 <term>#GModule</term>
 144 <listitem><para>Portable mechanism for dynamically loaded modules.</para></listitem>
 145 </varlistentry>
 146
 147 </variablelist>
 148 </para>
 149
 150
 151 <!-- ##### SECTION ./tmpl/gtypemodule.sgml:Short_Description ##### -->
 152 Type Loading Modules
 153
 154
 155 <!-- ##### SECTION ./tmpl/gtypemodule.sgml:Title ##### -->
 156 GTypeModule
 157
 158
 159 <!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Long_Description ##### -->
 160 <para>
 161
 162 </para>
 163
 164
 165 <!-- ##### SECTION ./tmpl/gtypeplugin.sgml:See_Also ##### -->
 166 <para>
 167
 168 </para>
 169
 170
 171 <!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Short_Description ##### -->
 172
 173
 174
 175 <!-- ##### SECTION ./tmpl/gtypeplugin.sgml:Title ##### -->
 176 GTypePlugin
 177
 178
 179 <!-- ##### SECTION ./tmpl/objects.sgml:Long_Description ##### -->
 180 <para>
 181
 182 </para>
 183
 184
 185 <!-- ##### SECTION ./tmpl/objects.sgml:See_Also ##### -->
 186 <para>
 187
 188 </para>
 189
 190
 191 <!-- ##### SECTION ./tmpl/objects.sgml:Short_Description ##### -->
 192
 193
 194
 195 <!-- ##### SECTION ./tmpl/objects.sgml:Title ##### -->
 196 The Base Object Type
 197
 198
 199 <!-- ##### SECTION ./tmpl/param_specs.sgml:Long_Description ##### -->
 200 <para>
 201
 202 </para>
 203
 204
 205 <!-- ##### SECTION ./tmpl/param_specs.sgml:See_Also ##### -->
 206 <para>
 207
 208 </para>
 209
 210
 211 <!-- ##### SECTION ./tmpl/param_specs.sgml:Short_Description ##### -->
 212
 213
 214
 215 <!-- ##### SECTION ./tmpl/param_specs.sgml:Title ##### -->
 216 Parameter Specifications
 217
 218
 219 <!-- ##### SECTION ./tmpl/signals.sgml:Long_Description ##### -->
 220 <para>
 221 The basic concept of the signal system is that of the <emphasis>emission</emphasis>
 222 of a signal.
 223 Signals are introduced per-type and are identified through strings.
 224 Signals introduced for a parent type are availale in derived types as well,
 225 so basically they are a per-type facility that is inherited.
 226 A signal emission mainly involves invocation of a certain set of callbacks in
 227 precisely defined manner. There are two main categories of such callbacks,
 228 per-object
 229         <footnote><para> Although signals can deal with any kind of type, i'm
 230         referring to those types as "object types" in the following, simply
 231         because that is the context most users will encounter signals in.
 232         </para></footnote>
 233 ones and user provided ones.
 234 The per-object callbacks are most often referred to as "object method
 235 handler" or "default (signal) handler", while user provided callbacks are
 236 usually just called "signal handler".
 237 The object method handler is provided at signal creation time (this most
 238 frequently happens at the end of an object class' creation), while user
 239 provided handlers are frequently connected and disconnected to/from a certain
 240 signal on certain object instances.
 241 </para>
 242 <para>
 243 A signal emission consists of five stages, unless prematurely stopped:
 244 <variablelist>
 245   <varlistentry><term></term><listitem><para>
 246         1 - Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
 247   </para></listitem></varlistentry>
 248   <varlistentry><term></term><listitem><para>
 249         2 - Invocation of normal user-provided signal handlers (<emphasis>after</emphasis> flag %FALSE)
 250   </para></listitem></varlistentry>
 251   <varlistentry><term></term><listitem><para>
 252         3 - Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
 253   </para></listitem></varlistentry>
 254   <varlistentry><term></term><listitem><para>
 255         4 - Invocation of user provided signal handlers, connected with an <emphasis>after</emphasis> flag of %TRUE
 256   </para></listitem></varlistentry>
 257   <varlistentry><term></term><listitem><para>
 258         5 - Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
 259   </para></listitem></varlistentry>
 260 </variablelist>
 261 The user provided signal handlers are called in the order they were
 262 connected in.
 263 All handlers may prematurely stop a signal emission, and any number of
 264 handlers may be connected, disconnected, blocked or unblocked during
 265 a signal emission.
 266 There are certain criteria for skipping user handlers in stages 2 and 4
 267 of a signal emission.
 268 First, user handlers may be <emphasis>blocked</emphasis>, blocked handlers are omitted
 269 during callback invocation, to return from the "blocked" state, a
 270 handler has to get unblocked exactly the same amount of times
 271 it has been blocked before.
 272 Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
 273 "detail" argument passed in to g_signal_emit() has to match the detail
 274 argument of the signal handler currently subject to invocation.
 275 Specification of no detail argument for signal handlers (omission of the
 276 detail part of the signal specification upon connection) serves as a
 277 wildcard and matches any detail argument passed in to emission.
 278 </para>
 279
 280
 281 <!-- ##### SECTION ./tmpl/signals.sgml:See_Also ##### -->
 282 <para>
 283
 284 </para>
 285
 286
 287 <!-- ##### SECTION ./tmpl/signals.sgml:Short_Description ##### -->
 288 Signals provide a means for customization of object behaviour and are used
 289 as general purpose notification mechanism.
 290
 291
 292 <!-- ##### SECTION ./tmpl/signals.sgml:Title ##### -->
 293 Signals
 294
 295
 296 <!-- ##### SECTION ./tmpl/standard_params.sgml:Long_Description ##### -->
 297 <para>
 298
 299 </para>
 300
 301
 302 <!-- ##### SECTION ./tmpl/standard_params.sgml:See_Also ##### -->
 303 <para>
 304
 305 </para>
 306
 307
 308 <!-- ##### SECTION ./tmpl/standard_params.sgml:Short_Description ##### -->
 309
 310
 311
 312 <!-- ##### SECTION ./tmpl/standard_params.sgml:Title ##### -->
 313 Standard Parameter Types
 314
 315
 316 <!-- ##### SECTION ./tmpl/value_collection.sgml:Long_Description ##### -->
 317 <para>
 318
 319 </para>
 320
 321
 322 <!-- ##### SECTION ./tmpl/value_collection.sgml:See_Also ##### -->
 323 <para>
 324
 325 </para>
 326
 327
 328 <!-- ##### SECTION ./tmpl/value_collection.sgml:Short_Description ##### -->
 329
 330
 331
 332 <!-- ##### SECTION ./tmpl/value_collection.sgml:Title ##### -->
 333 Varargs Value Collection
 334
 335
 336 <!-- ##### SECTION ./tmpl/value_types.sgml:Long_Description ##### -->
 337 <para>
 338
 339 </para>
 340
 341
 342 <!-- ##### SECTION ./tmpl/value_types.sgml:See_Also ##### -->
 343 <para>
 344
 345 </para>
 346
 347
 348 <!-- ##### SECTION ./tmpl/value_types.sgml:Short_Description ##### -->
 349
 350
 351
 352 <!-- ##### SECTION ./tmpl/value_types.sgml:Title ##### -->
 353 Standard value types
 354
 355
 356 <!-- ##### USER_FUNCTION GObjectGetParamFunc ##### -->
 357 <para>
 358
 359 </para>
 360
 361 @object:
 362 @param_id:
 363 @value:
 364 @pspec:
 365 @trailer:
 366
 367 <!-- ##### USER_FUNCTION GObjectSetParamFunc ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @object:
 373 @param_id:
 374 @value:
 375 @pspec:
 376 @trailer:
 377
 378 <!-- ##### ENUM GSignalType ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @G_SIGNAL_RUN_FIRST:
 384 @G_SIGNAL_RUN_LAST:
 385 @G_SIGNAL_RUN_CLEANUP:
 386 @G_SIGNAL_NO_RECURSE:
 387 @G_SIGNAL_ACTION:
 388 @G_SIGNAL_NO_HOOKS:
 389
 390 <!-- ##### USER_FUNCTION GTypePluginFillInterfaceInfo ##### -->
 391 <para>
 392
 393 </para>
 394
 395 @plugin:
 396 @interface_type:
 397 @instance_type:
 398 @info:
 399
 400 <!-- ##### USER_FUNCTION GTypePluginFillTypeInfo ##### -->
 401 <para>
 402
 403 </para>
 404
 405 @plugin:
 406 @g_type:
 407 @info:
 408 @value_table:
 409
 410 <!-- ##### USER_FUNCTION GTypePluginRef ##### -->
 411 <para>
 412
 413 </para>
 414
 415 @plugin:
 416
 417 <!-- ##### USER_FUNCTION GTypePluginUnRef ##### -->
 418 <para>
 419
 420 </para>
 421
 422 @plugin:
 423
 424 <!-- ##### STRUCT GTypePluginVTable ##### -->
 425 <para>
 426
 427 </para>
 428
 429 @plugin_ref:
 430 @plugin_unref:
 431 @complete_type_info:
 432 @complete_interface_info:
 433
 434 <!-- ##### MACRO G_IS_PARAM_VALUE ##### -->
 435 <para>
 436
 437 </para>
 438
 439 @pspec:
 440 @value:
 441
 442 <!-- ##### MACRO G_NOTIFY_PRIORITY ##### -->
 443 <para>
 444
 445 </para>
 446
 447
 448 <!-- ##### MACRO G_WARN_INVALID_PARAM_ID ##### -->
 449 <para>
 450
 451 </para>
 452
 453 @object:
 454 @param_id:
 455 @pspec:
 456
 457 <!-- ##### FUNCTION g_object_class_find_param_spec ##### -->
 458 <para>
 459
 460 </para>
 461
 462 @oclass:
 463 @param_name:
 464 @Returns:
 465
 466 <!-- ##### FUNCTION g_object_class_install_param ##### -->
 467 <para>
 468
 469 </para>
 470
 471 @oclass:
 472 @param_id:
 473 @pspec:
 474
 475 <!-- ##### FUNCTION g_object_get_param ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @object:
 481 @param_name:
 482 @value:
 483
 484 <!-- ##### FUNCTION g_object_queue_param_changed ##### -->
 485 <para>
 486
 487 </para>
 488
 489 @object:
 490 @param_name:
 491
 492 <!-- ##### FUNCTION g_object_set_param ##### -->
 493 <para>
 494
 495 </para>
 496
 497 @object:
 498 @param_name:
 499 @value:
 500
 501 <!-- ##### FUNCTION g_param_spec_hash_table_insert ##### -->
 502 <para>
 503
 504 </para>
 505
 506 @hash_table:
 507 @pspec:
 508 @owner_type:
 509
 510 <!-- ##### FUNCTION g_param_spec_hash_table_lookup ##### -->
 511 <para>
 512
 513 </para>
 514
 515 @hash_table:
 516 @param_name:
 517 @owner_type:
 518 @try_ancestors:
 519 @trailer:
 520 @Returns:
 521
 522 <!-- ##### FUNCTION g_param_spec_hash_table_new ##### -->
 523 <para>
 524
 525 </para>
 526
 527 @Returns:
 528
 529 <!-- ##### FUNCTION g_param_spec_hash_table_remove ##### -->
 530 <para>
 531
 532 </para>
 533
 534 @hash_table:
 535 @pspec:
 536
 537 <!-- ##### FUNCTION g_signal_type_closure_new ##### -->
 538 <para>
 539
 540 </para>
 541
 542 @itype:
 543 @struct_offset:
 544 @Returns:
 545
 546 <!-- ##### FUNCTION g_signals_destroy ##### -->
 547 <para>
 548
 549 </para>
 550
 551 @itype:
 552
 553 <!-- ##### FUNCTION g_type_conforms_to ##### -->
 554 <para>
 555
 556 </para>
 557
 558 @type:
 559 @iface_type:
 560 @Returns:
 561
 562 <!-- ##### FUNCTION g_type_instance_conforms_to ##### -->
 563 <para>
 564
 565 </para>
 566
 567 @instance:
 568 @iface_type:
 569 @Returns:
 570
 571 <!-- ##### FUNCTION g_type_is_dynamic ##### -->
 572 <para>
 573
 574 </para>
 575
 576 @type:
 577 @flags:
 578 @Returns:
 579
 580 <!-- ##### FUNCTION g_type_value_conforms_to ##### -->
 581 <para>
 582
 583 </para>
 584
 585 @value:
 586 @type:
 587 @Returns:
 588