RcStyle

GTK+ provides resource file mechanism for configuring various aspects of the operation of a GTK+ program at runtime.

Warning

In GTK+ 3.0, resource files have been deprecated and replaced by CSS-like style sheets, which are understood by GtkCssProvider.

Default files

An application can cause GTK+ to parse a specific RC file by calling gtk_rc_parse(). In addition to this, certain files will be read at the end of gtk_init(). Unless modified, the files looked for will be <SYSCONFDIR>/gtk-2.0/gtkrc and .gtkrc-3.0 in the users home directory. (<SYSCONFDIR> defaults to /usr/local/etc. It can be changed with the --prefix or --sysconfdir options when configuring GTK+.)

The set of these default files can be retrieved with gtk_rc_get_default_files() and modified with gtk_rc_add_default_file() and gtk_rc_set_default_files(). Additionally, the GTK2_RC_FILES environment variable can be set to a G_SEARCHPATH_SEPARATOR_S-separated list of files in order to overwrite the set of default files at runtime.

For each RC file, in addition to the file itself, GTK+ will look for a locale-specific file that will be parsed after the main file. For instance, if LANG is set to ja_JP.ujis, when loading the default file ~/.gtkrc then GTK+ looks for ~/.gtkrc.ja_JP and ~/.gtkrc.ja, and parses the first of those that exists.

<hr>

Pathnames and patterns

A resource file defines a number of styles and key bindings and attaches them to particular widgets. The attachment is done by the widget, widget_class, and class declarations. As an example of such a statement:

attaches the style "my-entry-class" to all widgets whose widget path matches the pattern "mywindow.*.GtkEntry". That is, all GtkEntry widgets which are part of a GtkWindow named "mywindow".

The patterns here are given in the standard shell glob syntax. The "?" wildcard matches any character, while "*" matches zero or more of any character. The three types of matching are against the widget path, the class path and the class hierarchy. Both the widget path and the class path consist of a "." separated list of all the parents of the widget and the widget itself from outermost to innermost. The difference is that in the widget path, the name assigned by gtk_widget_set_name() is used if present, otherwise the class name of the widget, while for the class path, the class name is always used.

Since GTK+ 2.10, widget_class paths can also contain &lt;classname&gt; substrings, which are matching the class with the given name and any derived classes. For instance,

will match GtkLabel widgets which are contained in any kind of menu item.

So, if you have a GtkEntry named "myentry", inside of a horizontal box in a window named "mywindow", then the widget path is: "mywindow.GtkHBox.myentry" while the class path is: "GtkWindow.GtkHBox.GtkEntry".

Matching against class is a little different. The pattern match is done against all class names in the widgets class hierarchy (not the layout hierarchy) in sequence, so the pattern:

will match not just GtkButton widgets, but also GtkToggleButton and GtkCheckButton widgets, since those classes derive from GtkButton.

Additionally, a priority can be specified for each pattern, and styles override other styles first by priority, then by pattern type and then by order of specification (later overrides earlier). The priorities that can be specified are (highest to lowest):

highest rc theme application gtk lowest

rc is the default for styles read from an RC file, theme is the default for styles read from theme RC files, application should be used for styles an application sets up, and gtk is used for styles that GTK+ creates internally.

<hr>

Theme gtkrc files

Theme RC files are loaded first from under the ~/.themes/, then from the directory from gtk_rc_get_theme_dir(). The files looked at will be gtk-3.0/gtkrc.

When the application prefers dark themes (see the "gtk-application-prefer-dark-theme" property for details), gtk-3.0/gtkrc-dark will be loaded first, and if not present gtk-3.0/gtkrc will be loaded.

<hr>

Optimizing RC Style Matches

Everytime a widget is created and added to the layout hierarchy of a GtkWindow ("anchored" to be exact), a list of matching RC styles out of all RC styles read in so far is composed. For this, every RC style is matched against the widgets class path, the widgets name path and widgets inheritance hierarchy. As a consequence, significant slowdown can be caused by utilization of many RC styles and by using RC style patterns that are slow or complicated to match against a given widget. The following ordered list provides a number of advices (prioritized by effectiveness) to reduce the performance overhead associated with RC style matches:

Move RC styles for specific applications into RC files dedicated to those applications and parse application specific RC files only from applications that are affected by them. This reduces the overall amount of RC styles that have to be considered for a match across a group of applications.

Merge multiple styles which use the same matching rule, for instance:

is faster to match as:

Use of wildcards should be avoided, this can reduce the individual RC style match to a single integer comparison in most cases.

To avoid complex recursive matching, specification of full class names (for class matches) or full path names (for widget and widget_class matches) is to be preferred over shortened names containing "*" or "?".

If at all necessary, wildcards should only be used at the tail or head of a pattern. This reduces the match complexity to a string comparison per RC style.

When using wildcards, use of "?" should be preferred over "*". This can reduce the matching complexity from O(n^2) to O(n). For example "Gtk*Box" can be turned into "Gtk?Box" and will still match GtkHBox and GtkVBox.

The use of "*" wildcards should be restricted as much as possible, because matching "A*B*C*RestString" can result in matching complexities of O(n^2) worst case.

<hr>

Toplevel declarations

An RC file is a text file which is composed of a sequence of declarations. '#' characters delimit comments and the portion of a line after a '#' is ignored when parsing an RC file.

The possible toplevel declarations are:

binding name { ... }

Declares a binding set.

class pattern binding[ : priority ] name

Specifies a style or binding set for a particular branch of the inheritance hierarchy.

include filename

Parses another file at this point. If filename is not an absolute filename, it is searched in the directories of the currently open RC files.

GTK+ also tries to load a locale-specific variant of the included file.

module_path path

Sets a path (a list of directories separated by colons) that will be searched for theme engines referenced in RC files.

pixmap_path path

Sets a path (a list of directories separated by colons) that will be searched for pixmaps referenced in RC files.

im_module_file pathname

Sets the pathname for the IM modules file. Setting this from RC files is deprecated; you should use the environment variable GTK_IM_MODULE_FILE instead.

style name [ = parent ] { ... }

Declares a style.

widget pattern binding[ : priority ] name

Specifies a style or binding set for a particular group of widgets by matching on the widget pathname.

widget_class pattern binding[ : priority ] name

Specifies a style or binding set for a particular group of widgets by matching on the class pathname.

setting = value

Specifies a value for a setting. Note that settings in RC files are overwritten by system-wide settings (which are managed by an XSettings manager on X11).

<hr>

Styles

A RC style is specified by a style declaration in a RC file, and then bound to widgets with a widget, widget_class, or class declaration. All styles applying to a particular widget are composited together with widget declarations overriding widget_class declarations which, in turn, override class declarations. Within each type of declaration, later declarations override earlier ones.

Within a style declaration, the possible elements are:

bgstate = color

Sets the color used for the background of most widgets.

fgstate = color

Sets the color used for the foreground of most widgets.

basestate = color

Sets the color used for the background of widgets displaying editable text. This color is used for the background of, among others, GtkText, GtkEntry, GtkList, and GtkCList.

textstate = color

Sets the color used for foreground of widgets using base for the background color.

xthickness = number

Sets the xthickness, which is used for various horizontal padding values in GTK+.

ythickness = number

Sets the ythickness, which is used for various vertical padding values in GTK+.

bg_pixmapstate = pixmap

Sets a background pixmap to be used in place of the bg color (or for GtkText, in place of the base color. The special value "&lt;parent&gt;" may be used to indicate that the widget should use the same background pixmap as its parent. The special value "&lt;none&gt;" may be used to indicate no background pixmap.

font = font

Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" declarations instead.

fontset = font

Starting with GTK+ 2.0, the "font" and "fontset" declarations are ignored; use "font_name" declarations instead.

font_name = font

Sets the font for a widget. font must be a Pango font name, e.g. "Sans Italic 10". For details about Pango font names, see pango_font_description_from_string().

stock["stock-id"] = { icon source specifications }

Defines the icon for a stock item.

color["color-name"] = color specification

Since 2.10, this element can be used to defines symbolic colors. See below for the syntax of color specifications.

engine "engine" { engine-specific settings }

Defines the engine to be used when drawing with this style.

class::property = value

Sets a style property for a widget class.

The colors and background pixmaps are specified as a function of the state of the widget. The states are:

NORMAL

A color used for a widget in its normal state.

ACTIVE

A variant of the NORMAL color used when the widget is in the GTK_STATE_ACTIVE state, and also for the trough of a ScrollBar, tabs of a NoteBook other than the current tab and similar areas. Frequently, this should be a darker variant of the NORMAL color.

PRELIGHT

A color used for widgets in the GTK_STATE_PRELIGHT state. This state is the used for Buttons and MenuItems that have the mouse cursor over them, and for their children.

SELECTED

A color used to highlight data selected by the user. for instance, the selected items in a list widget, and the selection in an editable widget.

INSENSITIVE

A color used for the background of widgets that have been set insensitive with gtk_widget_set_sensitive().

Colors can be specified as a string containing a color name (GTK+ knows all names from the X color database /usr/lib/X11/rgb.txt), in one of the hexadecimal forms rrrrggggbbbb, rrrgggbbb, rrggbb, or rgb, where r, g and b are hex digits, or they can be specified as a triplet { r, g, b}, where r, g and b are either integers in the range 0-65535 or floats in the range 0.0-1.0.

Since 2.10, colors can also be specified by refering to a symbolic color, as follows: @color-name, or by using expressions to combine colors. The following expressions are currently supported:

mix (factor, color1, color2)

Computes a new color by mixing color1 and color2. The factor determines how close the new color is to color1. A factor of 1.0 gives pure color1, a factor of 0.0 gives pure color2.

shade (factor, color)

Computes a lighter or darker variant of color. A factor of 1.0 leaves the color unchanged, smaller factors yield darker colors, larger factors yield lighter colors.

lighter (color)

This is an abbreviation for shade (1.3, color).

darker (color)

This is an abbreviation for shade (0.7, color).

Here are some examples of color expressions:

In a stock definition, icon sources are specified as a 4-tuple of image filename or icon name, text direction, widget state, and size, in that order. Each icon source specifies an image filename or icon name to use with a given direction, state, and size. Filenames are specified as a string such as "itemltr.png", while icon names (looked up in the current icon theme), are specified with a leading @, such as @"item-ltr". The * character can be used as a wildcard, and if direction/state/size are omitted they default to *. So for example, the following specifies different icons to use for left-to-right and right-to-left languages:

This could be abbreviated as follows:

You can specify custom icons for specific sizes, as follows:

The sizes that come with GTK+ itself are "gtk-menu", "gtk-small-toolbar", "gtk-large-toolbar", "gtk-button", "gtk-dialog". Applications can define other sizes.

It's also possible to use custom icons for a given state, for example:

When selecting an icon source to use, GTK+ will consider text direction most important, state second, and size third. It will select the best match based on those criteria. If an attribute matches exactly (e.g. you specified PRELIGHT or specified the size), GTK+ won't modify the image; if the attribute matches with a wildcard, GTK+ will scale or modify the image to match the state and size the user requested.

<hr>

Key bindings

Key bindings allow the user to specify actions to be taken on particular key presses. The form of a binding set declaration is:

key is a string consisting of a series of modifiers followed by the name of a key. The modifiers can be:

&lt;alt&gt; &lt;ctl&gt; &lt;control&gt; &lt;meta&gt; &lt;hyper&gt; &lt;super&gt; &lt;mod1&gt; &lt;mod2&gt; &lt;mod3&gt; &lt;mod4&gt; &lt;mod5&gt; &lt;release&gt; &lt;shft&gt; &lt;shift&gt;

&lt;shft&gt; is an alias for &lt;shift&gt;, &lt;ctl&gt; is an alias for &lt;control&gt;, and &lt;alt&gt; is an alias for &lt;mod1&gt;.

The action that is bound to the key is a sequence of signal names (strings) followed by parameters for each signal. The signals must be action signals. (See g_signal_new()). Each parameter can be a float, integer, string, or unquoted string representing an enumeration value. The types of the parameters specified must match the types of the parameters of the signal.

Binding sets are connected to widgets in the same manner as styles, with one difference: Binding sets override other binding sets first by pattern type, then by priority and then by order of specification. The priorities that can be specified and their default values are the same as for styles.

Constructors

this
this(GtkRcStyle* gtkRcStyle)

Sets our main struct and passes it to the parent class

Members

Functions

getRcStyleStruct
GtkRcStyle* getRcStyleStruct()
Undocumented in source. Be warned that the author may not have intended to support it.
getStruct
void* getStruct()

the main Gtk struct as a void*

setStruct
void setStruct(GObject* obj)
Undocumented in source. Be warned that the author may not have intended to support it.
styleCopy
deprecated RcStyle styleCopy()

Warning gtk_rc_style_copy has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Makes a copy of the specified GtkRcStyle. This function will correctly copy an RC style that is a member of a class derived from GtkRcStyle.

Static functions

addDefaultFile
deprecated void addDefaultFile(string filename)

Warning gtk_rc_add_default_file has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkStyleContext with a custom GtkStyleProvider instead Adds a file to the list of files to be parsed at the end of gtk_init().

findModuleInPath
deprecated string findModuleInPath(string moduleFile)

Warning gtk_rc_find_module_in_path has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Searches for a theme engine in the GTK+ search path. This function is not useful for applications and should not be used.

findPixmapInPath
deprecated string findPixmapInPath(Settings settings, ScannerG scanner, string pixmapFile)

Warning gtk_rc_find_pixmap_in_path has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Looks up a file in pixmap path for the specified GtkSettings. If the file is not found, it outputs a warning message using g_warning() and returns NULL.

getDefaultFiles
deprecated string[] getDefaultFiles()

Warning gtk_rc_get_default_files has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkStyleContext instead Retrieves the current list of RC files that will be parsed at the end of gtk_init().

getImModuleFile
deprecated string getImModuleFile()

Warning gtk_rc_get_im_module_file has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Obtains the path to the IM modules file. See the documentation of the GTK_IM_MODULE_FILE environment variable for more details.

getImModulePath
deprecated string getImModulePath()

Warning gtk_rc_get_im_module_path has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Obtains the path in which to look for IM modules. See the documentation of the GTK_PATH environment variable for more details about looking up modules. This function is useful solely for utilities supplied with GTK+ and should not be used by applications under normal circumstances.

getModuleDir
deprecated string getModuleDir()

Warning gtk_rc_get_module_dir has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Returns a directory in which GTK+ looks for theme engines. For full information about the search for theme engines, see the docs for GTK_PATH in Running GTK+ Applications(3).

getStyle
deprecated Style getStyle(Widget widget)

Warning gtk_rc_get_style has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkStyleContext instead Finds all matching RC styles for a given widget, composites them together, and then creates a GtkStyle representing the composite appearance. (GTK+ actually keeps a cache of previously created styles, so a new style may not be created.)

getStyleByPaths
deprecated Style getStyleByPaths(Settings settings, string widgetPath, string classPath, GType type)

Warning gtk_rc_get_style_by_paths has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkStyleContext instead Creates up a GtkStyle from styles defined in a RC file by providing the raw components used in matching. This function may be useful when creating pseudo-widgets that should be themed like widgets but don't actually have corresponding GTK+ widgets. An example of this would be items inside a GNOME canvas widget.

getThemeDir
deprecated string getThemeDir()

Warning gtk_rc_get_theme_dir has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Returns the standard directory in which themes should be installed. (GTK+ does not actually use this directory itself.)

parse
deprecated void parse(string filename)

Warning gtk_rc_parse has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Parses a given resource file.

parseColor
deprecated uint parseColor(ScannerG scanner, Color color)

Warning gtk_rc_parse_color has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead Parses a color in the format expected in a RC file. Note that theme engines should use gtk_rc_parse_color_full() in order to support symbolic colors.

parseColorFull
deprecated uint parseColorFull(ScannerG scanner, RcStyle style, Color color)

Warning gtk_rc_parse_color_full has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead Parses a color in the format expected in a RC file. If style is not NULL, it will be consulted to resolve references to symbolic colors. Since 2.12

parsePriority
deprecated uint parsePriority(ScannerG scanner, GtkPathPriorityType priority)

Warning gtk_rc_parse_priority has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead Parses a GtkPathPriorityType variable from the format expected in a RC file.

parseState
deprecated uint parseState(ScannerG scanner, GtkStateType state)

Warning gtk_rc_parse_state has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead Parses a GtkStateType variable from the format expected in a RC file.

parseString
deprecated void parseString(string rcString)

Warning gtk_rc_parse_string has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Parses resource information directly from a string.

reparseAll
deprecated int reparseAll()

Warning gtk_rc_reparse_all has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. If the modification time on any previously read file for the default GtkSettings has changed, discard all style information and then reread all previously read RC files.

reparseAllForSettings
deprecated int reparseAllForSettings(Settings settings, int forceLoad)

Warning gtk_rc_reparse_all_for_settings has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. If the modification time on any previously read file for the given GtkSettings has changed, discard all style information and then reread all previously read RC files.

resetStyles
deprecated void resetStyles(Settings settings)

Warning gtk_rc_reset_styles has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. This function recomputes the styles for all widgets that use a particular GtkSettings object. (There is one GtkSettings object per GdkScreen, see gtk_settings_get_for_screen()); It is useful when some global parameter has changed that affects the appearance of all widgets, because when a widget gets a new style, it will both redraw and recompute any cached information about its appearance. As an example, it is used when the default font size set by the operating system changes. Note that this function doesn't affect widgets that have a style set explicitely on them with gtk_widget_set_style(). Since 2.4

scannerNew
deprecated ScannerG scannerNew()

Warning gtk_rc_scanner_new has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead

setDefaultFiles
deprecated void setDefaultFiles(string[] filenames)

Warning gtk_rc_set_default_files has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkStyleContext with a custom GtkStyleProvider instead Sets the list of files that GTK+ will read at the end of gtk_init().

styleNew
deprecated RcStyle styleNew()

Warning gtk_rc_style_new has been deprecated since version 3.0 and should not be used in newly-written code. Use GtkCssProvider instead. Creates a new GtkRcStyle with no fields set and a reference count of 1.

Variables

gtkRcStyle
GtkRcStyle* gtkRcStyle;

the main Gtk struct

Inherited Members

From ObjectG

gObject
GObject* gObject;

the main Gtk struct

getObjectGStruct
GObject* getObjectGStruct()
Undocumented in source. Be warned that the author may not have intended to support it.
getStruct
void* getStruct()

the main Gtk struct as a void*

isGcRoot
bool isGcRoot;
Undocumented in source.
destroyNotify
void destroyNotify(ObjectG obj)
Undocumented in source. Be warned that the author may not have intended to support it.
toggleNotify
void toggleNotify(ObjectG obj, GObject* object, int isLastRef)
Undocumented in source. Be warned that the author may not have intended to support it.
~this
~this()
Undocumented in source.
getDObject
RT getDObject(U obj)

Gets a D Object from the objects table of associations.

setStruct
void setStruct(GObject* obj)
Undocumented in source. Be warned that the author may not have intended to support it.
setProperty
void setProperty(string propertyName, int value)
setProperty
void setProperty(string propertyName, string value)
setProperty
void setProperty(string propertyName, long value)
setProperty
void setProperty(string propertyName, ulong value)
unref
void unref()
Undocumented in source. Be warned that the author may not have intended to support it.
doref
ObjectG doref()
Undocumented in source. Be warned that the author may not have intended to support it.
connectedSignals
int[string] connectedSignals;
Undocumented in source.
onNotifyListeners
void delegate(ParamSpec, ObjectG)[] onNotifyListeners;
Undocumented in source.
addOnNotify
void addOnNotify(void delegate(ParamSpec, ObjectG) dlg, string property, ConnectFlags connectFlags)

The notify signal is emitted on an object when one of its properties has been changed. Note that getting this signal doesn't guarantee that the value of the property has actually changed, it may also be emitted when the setter for the property is called to reinstate the previous value.

callBackNotify
void callBackNotify(GObject* gobjectStruct, GParamSpec* pspec, ObjectG _objectG)
Undocumented in source. Be warned that the author may not have intended to support it.
classInstallProperty
void classInstallProperty(GObjectClass* oclass, uint propertyId, ParamSpec pspec)

Installs a new property. This is usually done in the class initializer. Note that it is possible to redefine a property in a derived class, by installing a property with the same name. This can be useful at times, e.g. to change the range of allowed values or the default value.

classInstallProperties
void classInstallProperties(GObjectClass* oclass, ParamSpec[] pspecs)

Installs new properties from an array of GParamSpecs. This is usually done in the class initializer. The property id of each property is the index of each GParamSpec in the pspecs array. The property id of 0 is treated specially by GObject and it should not be used to store a GParamSpec. This function should be used if you plan to use a static array of GParamSpecs and g_object_notify_by_pspec(). For instance, this Since 2.26

classFindProperty
ParamSpec classFindProperty(GObjectClass* oclass, string propertyName)

Looks up the GParamSpec for a property of a class.

classListProperties
ParamSpec[] classListProperties(GObjectClass* oclass)

Get an array of GParamSpec* for all properties of a class.

classOverrideProperty
void classOverrideProperty(GObjectClass* oclass, uint propertyId, string name)

Registers property_id as referring to a property with the name name in a parent class or in an interface implemented by oclass. This allows this class to override a property implementation in a parent class or to provide the implementation of a property from an interface. Note Internally, overriding is implemented by creating a property of type GParamSpecOverride; generally operations that query the properties of the object class, such as g_object_class_find_property() or g_object_class_list_properties() will return the overridden property. However, in one case, the construct_properties argument of the constructor virtual function, the GParamSpecOverride is passed instead, so that the param_id field of the GParamSpec will be correct. For virtually all uses, this makes no difference. If you need to get the overridden property, you can call g_param_spec_get_redirect_target(). Since 2.4

interfaceInstallProperty
void interfaceInstallProperty(void* iface, ParamSpec pspec)

Add a property to an interface; this is only useful for interfaces that are added to GObject-derived types. Adding a property to an interface forces all objects classes with that interface to have a compatible property. The compatible property could be a newly created GParamSpec, but normally g_object_class_override_property() will be used so that the object class only needs to provide an implementation and inherits the property description, default value, bounds, and so forth from the interface property. This function is meant to be called from the interface's default vtable initialization function (the class_init member of GTypeInfo.) It must not be called after after class_init has been called for any object types implementing this interface. Since 2.4

interfaceFindProperty
ParamSpec interfaceFindProperty(void* iface, string propertyName)

Find the GParamSpec with the given name for an interface. Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). Since 2.4

interfaceListProperties
ParamSpec[] interfaceListProperties(void* iface)

Lists the properties of an interface.Generally, the interface vtable passed in as g_iface will be the default vtable from g_type_default_interface_ref(), or, if you know the interface has already been loaded, g_type_default_interface_peek(). Since 2.4

doref
void* doref(void* object)

Increases the reference count of object.

unref
void unref(void* object)

Decreases the reference count of object. When its reference count drops to 0, the object is finalized (i.e. its memory is freed).

refSink
void* refSink(void* object)

Increase the reference count of object, and possibly remove the floating reference, if object has a floating reference. In other words, if the object is floating, then this call "assumes ownership" of the floating reference, converting it to a normal reference by clearing the floating flag while leaving the reference count unchanged. If the object is not floating, then this call adds a new normal reference increasing the reference count by one. Since 2.10

clearObject
void clearObject(ObjectG objectPtr)

Clears a reference to a GObject. object_ptr must not be NULL. If the reference is NULL then this function does nothing. Otherwise, the reference count of the object is decreased and the pointer is set to NULL. This function is threadsafe and modifies the pointer atomically, using memory barriers where needed. A macro is also included that allows this function to be used without pointer casts. Since 2.28

isFloating
int isFloating(void* object)

Checks whether object has a floating reference. Since 2.10

forceFloating
void forceFloating()

This function is intended for GObject implementations to re-enforce a floating object reference. Doing this is seldom required: all GInitiallyUnowneds are created with a floating reference which usually just needs to be sunken by calling g_object_ref_sink(). Since 2.10

weakRef
void weakRef(GWeakNotify notify, void* data)

Adds a weak reference callback to an object. Weak references are used for notification when an object is finalized. They are called "weak references" because they allow you to safely hold a pointer to an object without calling g_object_ref() (g_object_ref() adds a strong reference, that is, forces the object to stay alive). Note that the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use GWeakRef if thread-safety is required.

weakUnref
void weakUnref(GWeakNotify notify, void* data)

Removes a weak reference callback to an object.

addWeakPointer
void addWeakPointer(void** weakPointerLocation)

Adds a weak reference from weak_pointer to object to indicate that the pointer located at weak_pointer_location is only valid during the lifetime of object. When the object is finalized, weak_pointer will be set to NULL. Note that as with g_object_weak_ref(), the weak references created by this method are not thread-safe: they cannot safely be used in one thread if the object's last g_object_unref() might happen in another thread. Use GWeakRef if thread-safety is required.

removeWeakPointer
void removeWeakPointer(void** weakPointerLocation)

Removes a weak reference from object that was previously added using g_object_add_weak_pointer(). The weak_pointer_location has to match the one used with g_object_add_weak_pointer().

addToggleRef
void addToggleRef(GToggleNotify notify, void* data)

Increases the reference count of the object by one and sets a callback to be called when all other references to the object are dropped, or when this is already the last reference to the object and another reference is established. This functionality is intended for binding object to a proxy object managed by another memory manager. This is done with two paired references: the strong reference added by g_object_add_toggle_ref() and a reverse reference to the proxy object which is either a strong reference or weak reference. The setup is that when there are no other references to object, only a weak reference is held in the reverse direction from object to the proxy object, but when there are other references held to object, a strong reference is held. The notify callback is called when the reference from object to the proxy object should be toggled from strong to weak (is_last_ref true) or weak to strong (is_last_ref false). Since a (normal) reference must be held to the object before calling g_object_add_toggle_ref(), the initial state of the reverse link is always strong. Multiple toggle references may be added to the same gobject, however if there are multiple toggle references to an object, none of them will ever be notified until all but one are removed. For this reason, you should only ever use a toggle reference if there is important state in the proxy object. Since 2.8

removeToggleRef
void removeToggleRef(GToggleNotify notify, void* data)

Removes a reference added with g_object_add_toggle_ref(). The reference count of the object is decreased by one. Since 2.8

notify
void notify(string propertyName)

Emits a "notify" signal for the property property_name on object. When possible, eg. when signaling a property change from within the class that registered the property, you should use g_object_notify_by_pspec() instead.

notifyByPspec
void notifyByPspec(ParamSpec pspec)

Emits a "notify" signal for the property specified by pspec on object. This function omits the property name lookup, hence it is faster than g_object_notify(). One way to avoid using g_object_notify() from within the class that registered the properties, and using g_object_notify_by_pspec() instead, is to store the GParamSpec used with Since 2.26

freezeNotify
void freezeNotify()

Increases the freeze count on object. If the freeze count is non-zero, the emission of "notify" signals on object is stopped. The signals are queued until the freeze count is decreased to zero. Duplicate notifications are squashed so that at most one "notify" signal is emitted for each property modified while the object is frozen. This is necessary for accessors that modify multiple properties to prevent premature notification while the object is still being modified.

thawNotify
void thawNotify()

Reverts the effect of a previous call to g_object_freeze_notify(). The freeze count is decreased on object and when it reaches zero, queued "notify" signals are emitted. Duplicate notifications for each property are squashed so that at most one "notify" signal is emitted for each property. It is an error to call this function when the freeze count is zero.

getData
void* getData(string key)

Gets a named field from the objects table of associations (see g_object_set_data()).

setData
void setData(string key, void* data)

Each object carries around a table of associations from strings to pointers. This function lets you set an association. If the object already had an association with that name, the old association will be destroyed.

setDataFull
void setDataFull(string key, void* data, GDestroyNotify destroy)

Like g_object_set_data() except it adds notification for when the association is destroyed, either by setting it to a different value or when the object is destroyed. Note that the destroy callback is not called if data is NULL.

stealData
void* stealData(string key)

Remove a specified datum from the object's data associations, without invoking the association's destroy handler.

dupData
void* dupData(string key, GDuplicateFunc dupFunc, void* userData)

This is a variant of g_object_get_data() which returns a 'duplicate' of the value. dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the key is not set on the object then dup_func will be called with a NULL argument. Note that dup_func is called while user data of object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. Since 2.34

replaceData
int replaceData(string key, void* oldval, void* newval, GDestroyNotify destroy, GDestroyNotify* oldDestroy)

Compares the user data for the key key on object with oldval, and if they are the same, replaces oldval with newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way. Return: TRUE if the existing value for key was replaced by newval, FALSE otherwise. Since 2.34

getQdata
void* getQdata(GQuark quark)

This function gets back user data pointers stored via g_object_set_qdata().

setQdata
void setQdata(GQuark quark, void* data)

This sets an opaque, named pointer on an object. The name is specified through a GQuark (retrived e.g. via g_quark_from_static_string()), and the pointer can be gotten back from the object with g_object_get_qdata() until the object is finalized. Setting a previously set user data pointer, overrides (frees) the old pointer set, using NULL as pointer essentially removes the data stored.

setQdataFull
void setQdataFull(GQuark quark, void* data, GDestroyNotify destroy)

This function works like g_object_set_qdata(), but in addition, a void (*destroy) (gpointer) function may be specified which is called with data as argument when the object is finalized, or the data is being overwritten by a call to g_object_set_qdata() with the same quark.

stealQdata
void* stealQdata(GQuark quark)

This function gets back user data pointers stored via g_object_set_qdata() and removes the data from object without invoking its destroy() function (if any was set). Usually, calling this function is only required to update

dupQdata
void* dupQdata(GQuark quark, GDuplicateFunc dupFunc, void* userData)

This is a variant of g_object_get_qdata() which returns a 'duplicate' of the value. dup_func defines the meaning of 'duplicate' in this context, it could e.g. take a reference on a ref-counted object. If the quark is not set on the object then dup_func will be called with a NULL argument. Note that dup_func is called while user data of object is locked. This function can be useful to avoid races when multiple threads are using object data on the same key on the same object. Since 2.34

replaceQdata
int replaceQdata(GQuark quark, void* oldval, void* newval, GDestroyNotify destroy, GDestroyNotify* oldDestroy)

Compares the user data for the key quark on object with oldval, and if they are the same, replaces oldval with newval. This is like a typical atomic compare-and-exchange operation, for user data on an object. If the previous value was replaced then ownership of the old value (oldval) is passed to the caller, including the registered destroy notify for it (passed out in old_destroy). Its up to the caller to free this as he wishes, which may or may not include using old_destroy as sometimes replacement should not destroy the object in the normal way. Return: TRUE if the existing value for quark was replaced by newval, FALSE otherwise. Since 2.34

setProperty
void setProperty(string propertyName, Value value)

Sets a property on an object.

getProperty
void getProperty(string propertyName, Value value)

Gets a property of an object. value must have been initialized to the expected type of the property (or a type to which the expected type can be transformed) using g_value_init(). In general, a copy is made of the property contents and the caller is responsible for freeing the memory by calling g_value_unset(). Note that g_object_get_property() is really intended for language bindings, g_object_get() is much more convenient for C programming.

setValist
void setValist(string firstPropertyName, void* varArgs)

Sets properties on an object.

getValist
void getValist(string firstPropertyName, void* varArgs)

Gets properties of an object. In general, a copy is made of the property contents and the caller is responsible for freeing the memory in the appropriate manner for the type, for instance by calling g_free() or g_object_unref(). See g_object_get().

watchClosure
void watchClosure(Closure closure)

This function essentially limits the life time of the closure to the life time of the object. That is, when the object is finalized, the closure is invalidated by calling g_closure_invalidate() on it, in order to prevent invocations of the closure with a finalized (nonexisting) object. Also, g_object_ref() and g_object_unref() are added as marshal guards to the closure, to ensure that an extra reference count is held on object during invocation of the closure. Usually, this function will be called on closures that use this object as closure data.

runDispose
void runDispose()

Releases all references to other objects. This can be used to break reference cycles. This functions should only be called from object system implementations.

Meta