luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-12-26 15:36:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'migrate-to-gi-docgen3' into 'main'

Browse Source 
Switch to using gi-docgen for docs (batch 3)

See merge request GNOME/glib!3645
This commit is contained in:
Philip Withnall 2023-10-16 23:08:36 +00:00
commit 43b5985d03
25 changed files with 291 additions and 383 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/reference/gobject/gobject.toml.in
View File

@ -44,6 +44,8 @@ urlmap_file = "urlmap.js"
content_files = [
"concepts.md",
"tutorial.md",
"types.md",
"signals.md",
"floating-refs.md",
"boxed.md",
"enum-types.md",

2
docs/reference/gobject/meson.build
View File

@ -72,6 +72,8 @@ expand_content_files = [
'floating-refs.md',
'gvalue.md',
'tutorial.md',
'types.md',
'signals.md',
]
gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir'

95
docs/reference/gobject/signals.md Normal file
View File

@ -0,0 +1,95 @@
Title: Signals
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2000, 2001 Tim Janik
SPDX-FileCopyrightText: 2000 Owen Taylor
SPDX-FileCopyrightText: 2002, 2014 Matthias Clasen
SPDX-FileCopyrightText: 2014 Collabora, Ltd.
SPDX-FileCopyrightText: 2019 Endless Mobile, Inc.
# Signals
The basic concept of the signal system is that of the emission
of a signal. Signals are introduced per-type and are identified
through strings. Signals introduced for a parent type are available
in derived types as well, so basically they are a per-type facility
that is inherited.
A signal emission mainly involves invocation of a certain set of
callbacks in precisely defined manner. There are two main categories
of such callbacks, per-object ones and user provided ones.
(Although signals can deal with any kind of instantiatable type, I'm
referring to those types as "object types" in the following, simply
because that is the context most users will encounter signals in.)
The per-object callbacks are most often referred to as "object method
handler" or "default (signal) handler", while user provided callbacks are
usually just called "signal handler".
The object method handler is provided at signal creation time (this most
frequently happens at the end of an object class' creation), while user
provided handlers are frequently connected and disconnected to/from a
certain signal on certain object instances.
A signal emission consists of five stages, unless prematurely stopped:
1. Invocation of the object method handler for `G_SIGNAL_RUN_FIRST` signals
2. Invocation of normal user-provided signal handlers (where the @after
flag is not set)
3. Invocation of the object method handler for `G_SIGNAL_RUN_LAST` signals
4. Invocation of user provided signal handlers (where the @after flag is set)
5. Invocation of the object method handler for `G_SIGNAL_RUN_CLEANUP` signals
The user-provided signal handlers are called in the order they were
connected in.
All handlers may prematurely stop a signal emission, and any number of
handlers may be connected, disconnected, blocked or unblocked during
a signal emission.
There are certain criteria for skipping user handlers in stages 2 and 4
of a signal emission.
First, user handlers may be blocked. Blocked handlers are omitted during
callback invocation, to return from the blocked state, a handler has to
get unblocked exactly the same amount of times it has been blocked before.
Second, upon emission of a `G_SIGNAL_DETAILED` signal, an additional
`detail` argument passed in to [func@GObject.signal_emit] has to match
the detail argument of the signal handler currently subject to invocation.
Specification of no detail argument for signal handlers (omission of the
detail part of the signal specification upon connection) serves as a
wildcard and matches any detail argument passed in to emission.
While the `detail` argument is typically used to pass an object property name
(as with `GObject::notify`), no specific format is mandated for the detail
string, other than that it must be non-empty.
## Memory management of signal handlers
If you are connecting handlers to signals and using a `GObject` instance as
your signal handler user data, you should remember to pair calls to
[func@GObject.signal_connect] with calls to [func@GObject.signal_handler_disconnect]
or [func@GObject.signal_handlers_disconnect_by_func]. While signal handlers are
automatically disconnected when the object emitting the signal is finalised,
they are not automatically disconnected when the signal handler user data is
destroyed. If this user data is a `GObject` instance, using it from a
signal handler after it has been finalised is an error.
There are two strategies for managing such user data. The first is to
disconnect the signal handler (using [func@GObject.signal_handler_disconnect]
or [func@GObject.signal_handlers_disconnect_by_func]) when the user data (object)
is finalised; this has to be implemented manually. For non-threaded programs,
[func@GObject.signal_connect_object] can be used to implement this automatically.
Currently, however, it is unsafe to use in threaded programs.
The second is to hold a strong reference on the user data until after the
signal is disconnected for other reasons. This can be implemented
automatically using [func@GObject.signal_connect_data].
The first approach is recommended, as the second approach can result in
effective memory leaks of the user data if the signal handler is never
disconnected for some reason.

64
docs/reference/gobject/types.md Normal file
View File

@ -0,0 +1,64 @@
Title: Types
SPDX-License-Identifier: LGPL-2.1-or-later
SPDX-FileCopyrightText: 2001, 2003 Owen Taylor
SPDX-FileCopyrightText: 2002, 2003, 2004, 2005 Matthias Clasen
SPDX-FileCopyrightText: 2003, 2006 Josh Parsons
SPDX-FileCopyrightText: 2005 Stefan Kost
SPDX-FileCopyrightText: 2015 Collabora, Ltd.
SPDX-FileCopyrightText: 2021 Emmanuele Bassi
SPDX-FileCopyrightText: 2023 Endless OS Foundation, LLC
# Types
The GType API is the foundation of the GObject system. It provides the
facilities for registering and managing all fundamental data types,
user-defined object and interface types.
For type creation and registration purposes, all types fall into one of
two categories: static or dynamic. Static types are never loaded or
unloaded at run-time as dynamic types may be. Static types are created
with [func@GObject.type_register_static] that gets type specific
information passed in via a `GTypeInfo` structure.
Dynamic types are created with [func@GObject.type_register_dynamic],
which takes a `GTypePlugin` structure instead. The remaining type information
(the `GTypeInfo` structure) is retrieved during runtime through `GTypePlugin`
and the `g_type_plugin_*()` API.
These registration functions are usually called only once from a
function whose only purpose is to return the type identifier for a
specific class. Once the type (or class or interface) is registered,
it may be instantiated, inherited, or implemented depending on exactly
what sort of type it is.
There is also a third registration function for registering fundamental
types called [func@GObject.type_register_fundamental], which requires
both a `GTypeInfo` structure and a `GTypeFundamentalInfo` structure, but it
is rarely used since most fundamental types are predefined rather than user-defined.
Type instance and class structs are limited to a total of 64 KiB,
including all parent types. Similarly, type instances' private data
(as created by `G_ADD_PRIVATE()`) are limited to a total of
64 KiB. If a type instance needs a large static buffer, allocate it
separately (typically by using [`struct@GLib.Array`] or [`struct@GLib.PtrArray`])
and put a pointer to the buffer in the structure.
As mentioned in the [GType conventions](concepts.html#conventions), type names must
be at least three characters long. There is no upper length limit. The first
character must be a letter (a–z or A–Z) or an underscore (‘\_’). Subsequent
characters can be letters, numbers or any of ‘-\_+’.
# Runtime Debugging
When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
supports an environment variable `GOBJECT_DEBUG` that can be set to a
combination of flags to trigger debugging messages about
object bookkeeping and signal emissions during runtime.
The currently supported flags are:
- `objects`: Tracks all `GObject` instances in a global hash table called
`debug_objects_ht`, and prints the still-alive objects on exit.
- `instance-count`: Tracks the number of instances of every `GType` and makes
it available via the [func@GObject.type_get_instance_count] function.
- `signals`: Currently unused.

41
gobject/gbinding.c
View File

@ -21,36 +21,33 @@
*/
/**
* SECTION:gbinding
* @Title: GBinding
* @Short_Description: Bind two object properties
* GBinding:
*
* #GBinding is the representation of a binding between a property on a
* #GObject instance (or source) and another property on another #GObject
* `GObject` instance (or source) and another property on another `GObject`
* instance (or target).
*
* Whenever the source property changes, the same value is applied to the
* target property; for instance, the following binding:
*
* |[<!-- language="C" -->
* ```c
* g_object_bind_property (object1, "property-a",
* object2, "property-b",
* G_BINDING_DEFAULT);
* ]|
* ```
*
* will cause the property named "property-b" of @object2 to be updated
* every time g_object_set() or the specific accessor changes the value of
* every time [method@GObject.set] or the specific accessor changes the value of
* the property "property-a" of @object1.
*
* It is possible to create a bidirectional binding between two properties
* of two #GObject instances, so that if either property changes, the
* of two `GObject` instances, so that if either property changes, the
* other is updated as well, for instance:
*
* |[<!-- language="C" -->
* ```c
* g_object_bind_property (object1, "property-a",
* object2, "property-b",
* G_BINDING_BIDIRECTIONAL);
* ]|
* ```
*
* will keep the two properties in sync.
*
@ -59,14 +56,14 @@
* transformation from the source value to the target value before
* applying it; for instance, the following binding:
*
* |[<!-- language="C" -->
* ```c
* g_object_bind_property_full (adjustment1, "value",
* adjustment2, "value",
* G_BINDING_BIDIRECTIONAL,
* celsius_to_fahrenheit,
* fahrenheit_to_celsius,
* NULL, NULL);
* ]|
* ```
*
* will keep the "value" property of the two adjustments in sync; the
* @celsius_to_fahrenheit function will be called whenever the "value"
@ -80,29 +77,29 @@
*
* Note that #GBinding does not resolve cycles by itself; a cycle like
*
* |[
* ```
* object1:propertyA -> object2:propertyB
* object2:propertyB -> object3:propertyC
* object3:propertyC -> object1:propertyA
* ]|
* ```
*
* might lead to an infinite loop. The loop, in this particular case,
* can be avoided if the objects emit the #GObject::notify signal only
* can be avoided if the objects emit the `GObject::notify` signal only
* if the value has effectively been changed. A binding is implemented
* using the #GObject::notify signal, so it is susceptible to all the
* various ways of blocking a signal emission, like g_signal_stop_emission()
* or g_signal_handler_block().
* using the `GObject::notify` signal, so it is susceptible to all the
* various ways of blocking a signal emission, like [func@GObject.signal_stop_emission]
* or [func@GObject.signal_handler_block].
*
* A binding will be severed, and the resources it allocates freed, whenever
* either one of the #GObject instances it refers to are finalized, or when
* either one of the `GObject` instances it refers to are finalized, or when
* the #GBinding instance loses its last reference.
*
* Bindings for languages with garbage collection can use
* g_binding_unbind() to explicitly release a binding between the source
* [method@GObject.Binding.unbind] to explicitly release a binding between the source
* and target properties, instead of relying on the last reference on the
* binding, source, and target instances to drop.
*
* #GBinding is available since GObject 2.26
* Since: 2.26
*/
#include "config.h"

8
gobject/gbinding.h
View File

@ -38,14 +38,6 @@ G_BEGIN_DECLS
#define G_BINDING(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), G_TYPE_BINDING, GBinding))
#define G_IS_BINDING(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING))
/**
* GBinding:
*
* GBinding is an opaque structure whose members
* cannot be accessed directly.
*
* Since: 2.26
*/
typedef struct _GBinding GBinding;
/**

9
gobject/gbindinggroup.c
View File

@ -27,18 +27,15 @@
#include "gparamspecs.h"
/**
* SECTION:gbindinggroup
* @Title: GBindingGroup
* @Short_description: Binding multiple properties as a group
* @include: glib-object.h
* GBindingGroup:
*
* The #GBindingGroup can be used to bind multiple properties
* `GBindingGroup` can be used to bind multiple properties
* from an object collectively.
*
* Use the various methods to bind properties from a single source
* object to multiple destination objects. Properties can be bound
* bidirectionally and are connected when the source object is set
* with g_binding_group_set_source().
* with [method@GObject.BindingGroup.set_source].
*
* Since: 2.72
*/

8
gobject/gbindinggroup.h
View File

@ -36,14 +36,6 @@ G_BEGIN_DECLS
#define G_IS_BINDING_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_BINDING_GROUP))
#define G_TYPE_BINDING_GROUP (g_binding_group_get_type())
/**
* GBindingGroup:
*
* GBindingGroup is an opaque structure whose members
* cannot be accessed directly.
*
* Since: 2.72
*/
typedef struct _GBindingGroup GBindingGroup;
GOBJECT_AVAILABLE_IN_2_72

12
gobject/gclosure.c
View File

@ -39,11 +39,13 @@
/**
* SECTION:gclosure
* @short_description: Functions as first-class objects
* @title: Closures
* GClosure:
* @in_marshal: Indicates whether the closure is currently being invoked with
* g_closure_invoke()
* @is_invalid: Indicates whether the closure has been invalidated by
* g_closure_invalidate()
*
* A #GClosure represents a callback supplied by the programmer.
* A `GClosure` represents a callback supplied by the programmer.
*
* It will generally comprise a function of some kind and a marshaller
* used to call it. It is the responsibility of the marshaller to
@ -76,7 +78,7 @@
*
* Using closures has a number of important advantages over a simple
* callback function/data pointer combination:
*
*
* - Closures allow the callee to get the types of the callback parameters,
* which means that language bindings don't have to write individual glue
* for each callback type.

10
gobject/gclosure.h
View File

@ -169,15 +169,7 @@ struct _GClosureNotifyData
gpointer data;
GClosureNotify notify;
};
/**
* GClosure:
* @in_marshal: Indicates whether the closure is currently being invoked with
* g_closure_invoke()
* @is_invalid: Indicates whether the closure has been invalidated by
* g_closure_invalidate()
*
* A #GClosure represents a callback supplied by the programmer.
*/
struct _GClosure
{
/*< private >*/

32
gobject/gobject.c
View File

@ -38,22 +38,30 @@
#include "gconstructor.h"
/**
* SECTION:objects
* @title: GObject
* @short_description: The base object type
* @see_also: #GParamSpecObject, g_param_spec_object()
* GObject:
*
* GObject is the fundamental type providing the common attributes and
* The base object type.
*
* `GObject` is the fundamental type providing the common attributes and
* methods for all object types in GTK, Pango and other libraries
* based on GObject. The GObject class provides methods for object
* based on GObject. The `GObject` class provides methods for object
* construction and destruction, property access methods, and signal
* support. Signals are described in detail [here][gobject-Signals].
* support. Signals are described in detail [here][gobject-Signals].
*
* For a tutorial on implementing a new GObject class, see [How to define and
* implement a new GObject][howto-gobject]. For a list of naming conventions for
* GObjects and their methods, see the [GType conventions][gtype-conventions].
* For the high-level concepts behind GObject, read [Instantiatable classed types:
* Objects][gtype-instantiatable-classed].
* For a tutorial on implementing a new `GObject` class, see [How to define and
* implement a new GObject](tutorial.html#how-to-define-and-implement-a-new-gobject).
* For a list of naming conventions for GObjects and their methods, see the
* [GType conventions](concepts.html#conventions). For the high-level concepts
* behind GObject, read
* [Instantiatable classed types: Objects](concepts.html#instantiatable-classed-types-objects).
*
* Since GLib 2.72, all `GObject`s are guaranteed to be aligned to at least the
* alignment of the largest basic GLib type (typically this is `guint64` or
* `gdouble`). If you need larger alignment for an element in a `GObject`, you
* should allocate it on the heap (aligned), or arrange for your `GObject` to be
* appropriately padded. This guarantee applies to the `GObject` (or derived)
* struct, the `GObjectClass` (or derived) struct, and any private data allocated
* by `G_ADD_PRIVATE()`.
*/
/* --- macros --- */

17
gobject/gobject.h
View File

@ -248,22 +248,7 @@ typedef void (*GObjectFinalizeFunc) (GObject *object);
*/
typedef void (*GWeakNotify) (gpointer data,
GObject *where_the_object_was);
/**
* GObject:
*
* The base object type.
*
* All the fields in the `GObject` structure are private to the implementation
* and should never be accessed directly.
*
* Since GLib 2.72, all #GObjects are guaranteed to be aligned to at least the
* alignment of the largest basic GLib type (typically this is #guint64 or
* #gdouble). If you need larger alignment for an element in a #GObject, you
* should allocate it on the heap (aligned), or arrange for your #GObject to be
* appropriately padded. This guarantee applies to the #GObject (or derived)
* struct, the #GObjectClass (or derived) struct, and any private data allocated
* by G_ADD_PRIVATE().
*/
struct _GObject
{
GTypeInstance g_type_instance;

22
gobject/gparam.c
View File

@ -31,29 +31,27 @@
#include "gtype-private.h"
/**
* SECTION:gparamspec
* @short_description: Metadata for parameter specifications
* @see_also: g_object_class_install_property(), g_object_set(),
* g_object_get(), g_object_set_property(), g_object_get_property(),
* g_value_register_transform_func()
* @title: GParamSpec
* GParamSpec: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
* @g_type_instance: private `GTypeInstance` portion
* @name: name of this parameter: always an interned string
* @flags: `GParamFlags` flags for this parameter
* @value_type: the `GValue` type for this parameter
* @owner_type: `GType` type that uses (introduces) this parameter
*
* #GParamSpec is an object structure that encapsulates the metadata
* required to specify parameters, such as e.g. #GObject properties.
* `GParamSpec` encapsulates the metadata required to specify parameters, such as `GObject` properties.
*
* ## Parameter names # {#canonical-parameter-names}
* ## Parameter names
*
* A property name consists of one or more segments consisting of ASCII letters
* and digits, separated by either the `-` or `_` character. The first
* character of a property name must be a letter. These are the same rules as
* for signal naming (see g_signal_new()).
* for signal naming (see [func@GObject.signal_new]).
*
* When creating and looking up a #GParamSpec, either separator can be
* When creating and looking up a `GParamSpec`, either separator can be
* used, but they cannot be mixed. Using `-` is considerably more
* efficient, and is the ‘canonical form’. Using `_` is discouraged.
*/
/* --- defines --- */
#define PARAM_FLOATING_FLAG 0x2
#define G_PARAM_USER_MASK (~0U << G_PARAM_USER_SHIFT)

12
gobject/gparam.h
View File

@ -203,17 +203,7 @@ typedef struct _GParamSpec GParamSpec;
typedef struct _GParamSpecClass GParamSpecClass;
typedef struct _GParameter GParameter GOBJECT_DEPRECATED_TYPE_IN_2_54;
typedef struct _GParamSpecPool GParamSpecPool;
/**
* GParamSpec: (ref-func g_param_spec_ref_sink) (unref-func g_param_spec_unref) (set-value-func g_value_set_param) (get-value-func g_value_get_param)
* @g_type_instance: private #GTypeInstance portion
* @name: name of this parameter: always an interned string
* @flags: #GParamFlags flags for this parameter
* @value_type: the #GValue type for this parameter
* @owner_type: #GType type that uses (introduces) this parameter
*
* All other fields of the GParamSpec struct are private and
* should not be used directly.
*/
struct _GParamSpec
{
GTypeInstance g_type_instance;

23
gobject/gparamspecs.c
View File

@ -37,29 +37,6 @@
#include "gvaluearray.h"
/**
* SECTION:param_value_types
* @short_description: Standard Parameter and Value Types
* @see_also: #GParamSpec, #GValue, g_object_class_install_property().
* @title: Parameters and Values
*
* #GValue provides an abstract container structure which can be
* copied, transformed and compared while holding a value of any
* (derived) type, which is registered as a #GType with a
* #GTypeValueTable in its #GTypeInfo structure. Parameter
* specifications for most value types can be created as #GParamSpec
* derived instances, to implement e.g. #GObject properties which
* operate on #GValue containers.
*
* Parameter names need to start with a letter (a-z or A-Z). Subsequent
* characters can be letters, numbers or a '-'.
* All other characters are replaced by a '-' during construction.
*
* See also #GValue for more information.
*
*/
#define G_FLOAT_EPSILON (1e-30)
#define G_DOUBLE_EPSILON (1e-90)

93
gobject/gsignal.c
View File

@ -39,99 +39,6 @@
#include "gobject_trace.h"
/**
* SECTION:signals
* @short_description: A means for customization of object behaviour
* and a general purpose notification mechanism
* @title: Signals
*
* The basic concept of the signal system is that of the emission
* of a signal. Signals are introduced per-type and are identified
* through strings. Signals introduced for a parent type are available
* in derived types as well, so basically they are a per-type facility
* that is inherited.
*
* A signal emission mainly involves invocation of a certain set of
* callbacks in precisely defined manner. There are two main categories
* of such callbacks, per-object ones and user provided ones.
* (Although signals can deal with any kind of instantiatable type, I'm
* referring to those types as "object types" in the following, simply
* because that is the context most users will encounter signals in.)
* The per-object callbacks are most often referred to as "object method
* handler" or "default (signal) handler", while user provided callbacks are
* usually just called "signal handler".
*
* The object method handler is provided at signal creation time (this most
* frequently happens at the end of an object class' creation), while user
* provided handlers are frequently connected and disconnected to/from a
* certain signal on certain object instances.
*
* A signal emission consists of five stages, unless prematurely stopped:
*
* 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals
*
* 2. Invocation of normal user-provided signal handlers (where the @after
* flag is not set)
*
* 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals
*
* 4. Invocation of user provided signal handlers (where the @after flag is set)
*
* 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals
*
* The user-provided signal handlers are called in the order they were
* connected in.
*
* All handlers may prematurely stop a signal emission, and any number of
* handlers may be connected, disconnected, blocked or unblocked during
* a signal emission.
*
* There are certain criteria for skipping user handlers in stages 2 and 4
* of a signal emission.
*
* First, user handlers may be blocked. Blocked handlers are omitted during
* callback invocation, to return from the blocked state, a handler has to
* get unblocked exactly the same amount of times it has been blocked before.
*
* Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional
* @detail argument passed in to g_signal_emit() has to match the detail
* argument of the signal handler currently subject to invocation.
* Specification of no detail argument for signal handlers (omission of the
* detail part of the signal specification upon connection) serves as a
* wildcard and matches any detail argument passed in to emission.
*
* While the @detail argument is typically used to pass an object property name
* (as with #GObject::notify), no specific format is mandated for the detail
* string, other than that it must be non-empty.
*
* ## Memory management of signal handlers # {#signal-memory-management}
*
* If you are connecting handlers to signals and using a #GObject instance as
* your signal handler user data, you should remember to pair calls to
* g_signal_connect() with calls to g_signal_handler_disconnect() or
* g_signal_handlers_disconnect_by_func(). While signal handlers are
* automatically disconnected when the object emitting the signal is finalised,
* they are not automatically disconnected when the signal handler user data is
* destroyed. If this user data is a #GObject instance, using it from a
* signal handler after it has been finalised is an error.
*
* There are two strategies for managing such user data. The first is to
* disconnect the signal handler (using g_signal_handler_disconnect() or
* g_signal_handlers_disconnect_by_func()) when the user data (object) is
* finalised; this has to be implemented manually. For non-threaded programs,
* g_signal_connect_object() can be used to implement this automatically.
* Currently, however, it is unsafe to use in threaded programs.
*
* The second is to hold a strong reference on the user data until after the
* signal is disconnected for other reasons. This can be implemented
* automatically using g_signal_connect_data().
*
* The first approach is recommended, as the second approach can result in
* effective memory leaks of the user data if the signal handler is never
* disconnected for some reason.
*/
#define REPORT_BUG "please report occurrence circumstances to https://gitlab.gnome.org/GNOME/glib/issues/new"
/* --- typedefs --- */

21
gobject/gsignalgroup.c
View File

@ -28,13 +28,12 @@
#include "gvaluetypes.h"
/**
* SECTION:gsignalgroup
* @Title: GSignalGroup
* @Short_description: Manage a collection of signals on a GObject
* GSignalGroup:
*
* #GSignalGroup manages to simplify the process of connecting
* many signals to a #GObject as a group. As such there is no API
* to disconnect a signal from the group.
* `GSignalGroup` manages a collection of signals on a `GObject`.
*
* `GSignalGroup` simplifies the process of connecting many signals to a `GObject`
* as a group. As such there is no API to disconnect a signal from the group.
*
* In particular, this allows you to:
*
@ -43,12 +42,12 @@
* - Block and unblock signals as a group
* - Ensuring that blocked state transfers across target instances.
*
* One place you might want to use such a structure is with #GtkTextView and
* #GtkTextBuffer. Often times, you'll need to connect to many signals on
* #GtkTextBuffer from a #GtkTextView subclass. This allows you to create a
* One place you might want to use such a structure is with `GtkTextView` and
* `GtkTextBuffer`. Often times, you'll need to connect to many signals on
* `GtkTextBuffer` from a `GtkTextView` subclass. This allows you to create a
* signal group during instance construction, simply bind the
* #GtkTextView:buffer property to #GSignalGroup:target and connect
* all the signals you need. When the #GtkTextView:buffer property changes
* `GtkTextView:buffer` property to `GSignalGroup:target` and connect
* all the signals you need. When the `GtkTextView:buffer` property changes
* all of the signals will be transitioned correctly.
*
* Since: 2.72

8
gobject/gsignalgroup.h
View File

@ -36,14 +36,6 @@ G_BEGIN_DECLS
#define G_IS_SIGNAL_GROUP(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), G_TYPE_SIGNAL_GROUP))
#define G_TYPE_SIGNAL_GROUP (g_signal_group_get_type())
/**
* GSignalGroup:
*
* #GSignalGroup is an opaque structure whose members
* cannot be accessed directly.
*
* Since: 2.72
*/
typedef struct _GSignalGroup GSignalGroup;
GOBJECT_AVAILABLE_IN_2_72

59
gobject/gtype.c
View File

@ -44,65 +44,6 @@
#define IF_DEBUG(debug_type) if (_g_type_debug_flags & G_TYPE_DEBUG_ ## debug_type)
#endif
/**
* SECTION:gtype
* @short_description: The GLib Runtime type identification and
* management system
* @title:Type Information
*
* The GType API is the foundation of the GObject system. It provides the
* facilities for registering and managing all fundamental data types,
* user-defined object and interface types.
*
* For type creation and registration purposes, all types fall into one of
* two categories: static or dynamic. Static types are never loaded or
* unloaded at run-time as dynamic types may be. Static types are created
* with g_type_register_static() that gets type specific information passed
* in via a #GTypeInfo structure.
*
* Dynamic types are created with g_type_register_dynamic() which takes a
* #GTypePlugin structure instead. The remaining type information (the
* #GTypeInfo structure) is retrieved during runtime through #GTypePlugin
* and the g_type_plugin_*() API.
*
* These registration functions are usually called only once from a
* function whose only purpose is to return the type identifier for a
* specific class. Once the type (or class or interface) is registered,
* it may be instantiated, inherited, or implemented depending on exactly
* what sort of type it is.
*
* There is also a third registration function for registering fundamental
* types called g_type_register_fundamental() which requires both a #GTypeInfo
* structure and a #GTypeFundamentalInfo structure but it is seldom used
* since most fundamental types are predefined rather than user-defined.
*
* Type instance and class structs are limited to a total of 64 KiB,
* including all parent types. Similarly, type instances' private data
* (as created by G_ADD_PRIVATE()) are limited to a total of
* 64 KiB. If a type instance needs a large static buffer, allocate it
* separately (typically by using #GArray or #GPtrArray) and put a pointer
* to the buffer in the structure.
*
* As mentioned in the [GType conventions][gtype-conventions], type names must
* be at least three characters long. There is no upper length limit. The first
* character must be a letter (a–z or A–Z) or an underscore (‘_’). Subsequent
* characters can be letters, numbers or any of ‘-_+’.
*
* # Runtime Debugging
*
* When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
* supports an environment variable `GOBJECT_DEBUG` that can be set to a
* combination of flags to trigger debugging messages about
* object bookkeeping and signal emissions during runtime.
*
* The currently supported flags are:
* - `objects`: Tracks all #GObject instances in a global hash table called
* `debug_objects_ht`, and prints the still-alive objects on exit.
* - `instance-count`: Tracks the number of instances of every #GType and makes
* it available via the g_type_get_instance_count() function.
* - `signals`: Currently unused.
*/
/* NOTE: some functions (some internal variants and exported ones)
* invalidate data portions of the TypeNodes. if external functions/callbacks

31
gobject/gtypemodule.c
View File

@ -26,41 +26,40 @@
/**
* SECTION:gtypemodule
* @short_description: Type loading modules
* @see_also: #GTypePlugin, #GModule
* @title: GTypeModule
* GTypeModule:
* @name: the name of the module
*
* #GTypeModule provides a simple implementation of the #GTypePlugin
* `GTypeModule` provides a simple implementation of the `GTypePlugin`
* interface.
*
* The model of #GTypeModule is a dynamically loaded module which
* The model of `GTypeModule` is a dynamically loaded module which
* implements some number of types and interface implementations.
*
* When the module is loaded, it registers its types and interfaces
* using g_type_module_register_type() and g_type_module_add_interface().
* using [method@GObject.TypeModule.register_type] and
* [method@GObject.TypeModule.add_interface].
* As long as any instances of these types and interface implementations
* are in use, the module is kept loaded. When the types and interfaces
* are gone, the module may be unloaded. If the types and interfaces
* become used again, the module will be reloaded. Note that the last
* reference cannot be released from within the module code, since that
* would lead to the caller's code being unloaded before g_object_unref()
* would lead to the caller's code being unloaded before `g_object_unref()`
* returns to it.
*
* Keeping track of whether the module should be loaded or not is done by
* using a use count - it starts at zero, and whenever it is greater than
* zero, the module is loaded. The use count is maintained internally by
* the type system, but also can be explicitly controlled by
* g_type_module_use() and g_type_module_unuse(). Typically, when loading
* a module for the first type, g_type_module_use() will be used to load
* it so that it can initialize its types. At some later point, when the
* module no longer needs to be loaded except for the type
* implementations it contains, g_type_module_unuse() is called.
* [func@GObject.type_module_use] and [func@GObject.type_module_unuse].
* Typically, when loading a module for the first type, `g_type_module_use()`
* will be used to load it so that it can initialize its types. At some later
* point, when the module no longer needs to be loaded except for the type
* implementations it contains, `g_type_module_unuse()` is called.
*
* #GTypeModule does not actually provide any implementation of module
* `GTypeModule` does not actually provide any implementation of module
* loading and unloading. To create a particular module type you must
* derive from #GTypeModule and implement the load and unload functions
* in #GTypeModuleClass.
* derive from `GTypeModule` and implement the load and unload functions
* in `GTypeModuleClass`.
*/
typedef struct _ModuleTypeInfo ModuleTypeInfo;

7
gobject/gtypemodule.h
View File

@ -40,13 +40,6 @@ typedef struct _GTypeModuleClass GTypeModuleClass;
G_DEFINE_AUTOPTR_CLEANUP_FUNC(GTypeModule, g_object_unref)
/**
* GTypeModule:
* @name: the name of the module
*
* The members of the GTypeModule structure should not
* be accessed directly, except for the @name field.
*/
struct _GTypeModule
{
GObject parent_instance;

47
gobject/gtypeplugin.c
View File

@ -23,10 +23,7 @@
/**
* SECTION:gtypeplugin
* @short_description: An interface for dynamically loadable types
* @see_also: #GTypeModule and g_type_register_dynamic().
* @title: GTypePlugin
* GTypePlugin:
*
* An interface that handles the lifecycle of dynamically loaded types.
*
@ -36,45 +33,45 @@
* 1. The type is initially introduced (usually upon loading the module
* the first time, or by your main application that knows what modules
* introduces what types), like this:
* |[<!-- language="C" -->
* ```c
* new_type_id = g_type_register_dynamic (parent_type_id,
* "TypeName",
* new_type_plugin,
* type_flags);
* ]|
* ```
* where @new_type_plugin is an implementation of the
* #GTypePlugin interface.
* `GTypePlugin` interface.
*
* 2. The type's implementation is referenced, e.g. through
* g_type_class_ref() or through g_type_create_instance() (this is
* being called by g_object_new()) or through one of the above done on
* a type derived from @new_type_id.
* [func@GObject.type_class_ref] or through [func@GObject.type_create_instance]
* (this is being called by [func@GObject.object_new]) or through one of the above
* done on a type derived from @new_type_id.
*
* 3. This causes the type system to load the type's implementation by
* calling g_type_plugin_use() and g_type_plugin_complete_type_info()
* 3. This causes the type system to load the type's implementation by calling
* [func@GObject.type_plugin_use] and [method@GObject.TypePlugin.complete_type_info]
* on @new_type_plugin.
*
* 4. At some point the type's implementation isn't required anymore,
* e.g. after g_type_class_unref() or g_type_free_instance() (called
* when the reference count of an instance drops to zero).
*
* 4. At some point the type's implementation isn't required anymore, e.g. after
* [func@GObject.type_class_unref] or [func@GObject.type_free_instance]
* (called when the reference count of an instance drops to zero).
*
* 5. This causes the type system to throw away the information retrieved
* from g_type_plugin_complete_type_info() and then it calls
* g_type_plugin_unuse() on @new_type_plugin.
*
* from [method@GObject.TypePlugin.complete_type_info] and then it calls
* [method@GObject.TypePlugin.unuse] on @new_type_plugin.
*
* 6. Things may repeat from the second step.
*
* So basically, you need to implement a #GTypePlugin type that
* So basically, you need to implement a `GTypePlugin` type that
* carries a use_count, once use_count goes from zero to one, you need
* to load the implementation to successfully handle the upcoming
* g_type_plugin_complete_type_info() call. Later, maybe after
* [method@GObject.TypePlugin.complete_type_info] call. Later, maybe after
* succeeding use/unuse calls, once use_count drops to zero, you can
* unload the implementation again. The type system makes sure to call
* g_type_plugin_use() and g_type_plugin_complete_type_info() again
* when the type is needed again.
* [method@GObject.TypePlugin.use] and [method@GObject.TypePlugin.complete_type_info]
* again when the type is needed again.
*
* #GTypeModule is an implementation of #GTypePlugin that already
* implements most of this except for the actual module loading and
* [struct@GObject.TypeModule] is an implementation of `GTypePlugin` that
* already implements most of this except for the actual module loading and
* unloading. It even handles multiple registered types per module.
*/

6
gobject/gtypeplugin.h
View File

@ -80,12 +80,6 @@ typedef void (*GTypePluginCompleteInterfaceInfo) (GTypePlugin *plugin,
GType instance_type,
GType interface_type,
GInterfaceInfo *info);
/**
* GTypePlugin:
*
* The GTypePlugin typedef is used as a placeholder
* for objects that implement the GTypePlugin interface.
*/
/**
* GTypePluginClass:
* @use_plugin: Increases the use count of the plugin.

38
gobject/gvaluearray.c
View File

@ -30,35 +30,35 @@
/**
* SECTION:value_arrays
* @short_description: A container structure to maintain an array of
* generic values
* @see_also: #GValue, #GParamSpecValueArray, g_param_spec_value_array()
* @title: Value arrays
* GValueArray:
* @n_values: number of values contained in the array
* @values: array of values
*
* The prime purpose of a #GValueArray is for it to be used as an
* object property that holds an array of values. A #GValueArray wraps
* an array of #GValue elements in order for it to be used as a boxed
* type through %G_TYPE_VALUE_ARRAY.
* A `GValueArray` is a container structure to hold an array of generic values.
*
* #GValueArray is deprecated in favour of #GArray since GLib 2.32. It
* is possible to create a #GArray that behaves like a #GValueArray by
* using the size of #GValue as the element size, and by setting
* g_value_unset() as the clear function using g_array_set_clear_func(),
* for instance, the following code:
* The prime purpose of a `GValueArray` is for it to be used as an
* object property that holds an array of values. A `GValueArray` wraps
* an array of `GValue` elements in order for it to be used as a boxed
* type through `G_TYPE_VALUE_ARRAY`.
*
* |[<!-- language="C" -->
* `GValueArray` is deprecated in favour of `GArray` since GLib 2.32.
* It is possible to create a `GArray` that behaves like a `GValueArray`
* by using the size of `GValue` as the element size, and by setting
* [func@GObject.value_unset] as the clear function using
* [method@GLib.Array.set_clear_func], for instance, the following code:
*
* ```c
* GValueArray *array = g_value_array_new (10);
* ]|
* ```
*
* can be replaced by:
*
* |[<!-- language="C" -->
* ```c
* GArray *array = g_array_sized_new (FALSE, TRUE, sizeof (GValue), 10);
* g_array_set_clear_func (array, (GDestroyNotify) g_value_unset);
* ]|
* ```
*
* Deprecated: 2.32: Use #GArray instead, if possible for the given use case,
* Deprecated: 2.32: Use `GArray` instead, if possible for the given use case,
* as described above.
*/

7
gobject/gvaluearray.h
View File

@ -41,13 +41,6 @@ G_BEGIN_DECLS
/* --- typedefs & structs --- */
typedef struct _GValueArray GValueArray;
/**
* GValueArray:
* @n_values: number of values contained in the array
* @values: array of values
*
* A #GValueArray contains an array of #GValue elements.
*/
struct _GValueArray
{
guint n_values;