CtkBuildable: CTK+ 3 Reference Manual

CtkBuildable

CtkBuildable — Interface for objects that can be built by CtkBuilder

Functions

void	ctk_buildable_set_name ()
const gchar *	ctk_buildable_get_name ()
void	ctk_buildable_add_child ()
void	ctk_buildable_set_buildable_property ()
GObject *	ctk_buildable_construct_child ()
gboolean	ctk_buildable_custom_tag_start ()
void	ctk_buildable_custom_tag_end ()
void	ctk_buildable_custom_finished ()
void	ctk_buildable_parser_finished ()
GObject *	ctk_buildable_get_internal_child ()

Types and Values

	CtkBuildable
struct	CtkBuildableIface

Object Hierarchy

    GInterface
    ╰── CtkBuildable

Prerequisites

CtkBuildable requires GObject.

Known Implementations

CtkBuildable is implemented by CtkAboutDialog, CtkAccelLabel, CtkAction, CtkActionBar, CtkActionGroup, CtkAlignment, CtkAppChooserButton, CtkAppChooserDialog, CtkAppChooserWidget, CtkApplicationWindow, CtkArrow, CtkAspectFrame, CtkAssistant, CtkBin, CtkBox, CtkButton, CtkButtonBox, CtkCalendar, CtkCellArea, CtkCellAreaBox, CtkCellView, CtkCheckButton, CtkCheckMenuItem, CtkColorButton, CtkColorChooserDialog, CtkColorChooserWidget, CtkColorSelection, CtkColorSelectionDialog, CtkComboBox, CtkComboBoxText, CtkContainer, CtkDialog, CtkDrawingArea, CtkEntry, CtkEntryCompletion, CtkEventBox, CtkExpander, CtkFileChooserButton, CtkFileChooserDialog, CtkFileChooserWidget, CtkFileFilter, CtkFixed, CtkFlowBox, CtkFlowBoxChild, CtkFontButton, CtkFontChooserDialog, CtkFontChooserWidget, CtkFontSelection, CtkFontSelectionDialog, CtkFrame, CtkGLArea, CtkGrid, CtkHBox, CtkHButtonBox, CtkHPaned, CtkHSV, CtkHScale, CtkHScrollbar, CtkHSeparator, CtkHandleBox, CtkHeaderBar, CtkIconFactory, CtkIconView, CtkImage, CtkImageMenuItem, CtkInfoBar, CtkInvisible, CtkLabel, CtkLayout, CtkLevelBar, CtkLinkButton, CtkListBox, CtkListBoxRow, CtkListStore, CtkLockButton, CtkMenu, CtkMenuBar, CtkMenuButton, CtkMenuItem, CtkMenuShell, CtkMenuToolButton, CtkMessageDialog, CtkMisc, CtkModelButton, CtkNotebook, CtkOffscreenWindow, CtkOverlay, CtkPageSetupUnixDialog, CtkPaned, CtkPlacesSidebar, CtkPlug, CtkPopover, CtkPopoverMenu, CtkPrintUnixDialog, CtkProgressBar, CtkRadioAction, CtkRadioButton, CtkRadioMenuItem, CtkRadioToolButton, CtkRange, CtkRecentAction, CtkRecentChooserDialog, CtkRecentChooserMenu, CtkRecentChooserWidget, CtkRecentFilter, CtkRevealer, CtkScale, CtkScaleButton, CtkScrollbar, CtkScrolledWindow, CtkSearchBar, CtkSearchEntry, CtkSeparator, CtkSeparatorMenuItem, CtkSeparatorToolItem, CtkShortcutsGroup, CtkShortcutsSection, CtkShortcutsShortcut, CtkShortcutsWindow, CtkSizeGroup, CtkSocket, CtkSpinButton, CtkSpinner, CtkStack, CtkStackSidebar, CtkStackSwitcher, CtkStatusbar, CtkSwitch, CtkTable, CtkTearoffMenuItem, CtkTextTagTable, CtkTextView, CtkToggleAction, CtkToggleButton, CtkToggleToolButton, CtkToolButton, CtkToolItem, CtkToolItemGroup, CtkToolPalette, CtkToolbar, CtkTreeStore, CtkTreeView, CtkTreeViewColumn, CtkUIManager, CtkVBox, CtkVButtonBox, CtkVPaned, CtkVScale, CtkVScrollbar, CtkVSeparator, CtkViewport, CtkVolumeButton, CtkWidget and CtkWindow.

Includes

#include <ctk/ctk.h>

Description

CtkBuildable allows objects to extend and customize their deserialization from CtkBuilder UI descriptions. The interface includes methods for setting names and properties of objects, parsing custom tags and constructing child objects.

The CtkBuildable interface is implemented by all widgets and many of the non-widget objects that are provided by CTK+. The main user of this interface is CtkBuilder. There should be very little need for applications to call any of these functions directly.

An object only needs to implement this interface if it needs to extend the CtkBuilder format or run any extra routines at deserialization time.

Functions

ctk_buildable_set_name ()

void
ctk_buildable_set_name (CtkBuildable *buildable,
                        const gchar *name);

Sets the name of the buildable object.

Parameters

buildable	a CtkBuildable
name	name to set

Since: 2.12

ctk_buildable_get_name ()

const gchar *
ctk_buildable_get_name (CtkBuildable *buildable);

Gets the name of the buildable object.

CtkBuilder sets the name based on the CtkBuilder UI definition used to construct the buildable .

Parameters

buildable

a CtkBuildable

Returns

the name set with ctk_buildable_set_name()

Since: 2.12

ctk_buildable_add_child ()

void
ctk_buildable_add_child (CtkBuildable *buildable,
                         CtkBuilder *builder,
                         GObject *child,
                         const gchar *type);

Adds a child to buildable . type is an optional string describing how the child should be added.

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder
child	child to add
type	kind of child or `NULL`.	[allow-none]

Since: 2.12

ctk_buildable_set_buildable_property ()

void
ctk_buildable_set_buildable_property (CtkBuildable *buildable,
                                      CtkBuilder *builder,
                                      const gchar *name,
                                      const GValue *value);

Sets the property name name to value on the buildable object.

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder
name	name of property
value	value of property

Since: 2.12

ctk_buildable_construct_child ()

GObject *
ctk_buildable_construct_child (CtkBuildable *buildable,
                               CtkBuilder *builder,
                               const gchar *name);

Constructs a child of buildable with the name name .

CtkBuilder calls this function if a “constructor” has been specified in the UI definition.

Parameters

buildable	A CtkBuildable
builder	CtkBuilder used to construct this object
name	name of child to construct

Returns

the constructed child.

[transfer full]

Since: 2.12

ctk_buildable_custom_tag_start ()

gboolean
ctk_buildable_custom_tag_start (CtkBuildable *buildable,
                                CtkBuilder *builder,
                                GObject *child,
                                const gchar *tagname,
                                GMarkupParser *parser,
                                gpointer *data);

This is called for each unknown element under <child>.

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder used to construct this object
child	child object or `NULL` for non-child tags.	[allow-none]
tagname	name of tag
parser	a GMarkupParser to fill in.	[out]
data	return location for user data that will be passed in to parser functions.	[out]

Returns

TRUE if a object has a custom implementation, FALSE if it doesn't.

Since: 2.12

ctk_buildable_custom_tag_end ()

void
ctk_buildable_custom_tag_end (CtkBuildable *buildable,
                              CtkBuilder *builder,
                              GObject *child,
                              const gchar *tagname,
                              gpointer *data);

This is called at the end of each custom element handled by the buildable.

Parameters

buildable	A CtkBuildable
builder	CtkBuilder used to construct this object
child	child object or `NULL` for non-child tags.	[allow-none]
tagname	name of tag
data	user data that will be passed in to parser functions.	[type gpointer]

Since: 2.12

ctk_buildable_custom_finished ()

void
ctk_buildable_custom_finished (CtkBuildable *buildable,
                               CtkBuilder *builder,
                               GObject *child,
                               const gchar *tagname,
                               gpointer data);

This is similar to ctk_buildable_parser_finished() but is called once for each custom tag handled by the buildable .

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder
child	child object or `NULL` for non-child tags.	[allow-none]
tagname	the name of the tag
data	user data created in custom_tag_start

Since: 2.12

ctk_buildable_parser_finished ()

void
ctk_buildable_parser_finished (CtkBuildable *buildable,
                               CtkBuilder *builder);

Called when the builder finishes the parsing of a CtkBuilder UI definition. Note that this will be called once for each time ctk_builder_add_from_file() or ctk_builder_add_from_string() is called on a builder.

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder

Since: 2.12

ctk_buildable_get_internal_child ()

GObject *
ctk_buildable_get_internal_child (CtkBuildable *buildable,
                                  CtkBuilder *builder,
                                  const gchar *childname);

Get the internal child called childname of the buildable object.

Parameters

buildable	a CtkBuildable
builder	a CtkBuilder
childname	name of child

Returns

the internal child of the buildable object.

[transfer none]

Since: 2.12

Types and Values

CtkBuildable

typedef struct _CtkBuildable CtkBuildable;

struct CtkBuildableIface

struct CtkBuildableIface {
  GTypeInterface g_iface;

  /* virtual table */
  void          (* set_name)               (CtkBuildable  *buildable,
                                            const gchar   *name);
  const gchar * (* get_name)               (CtkBuildable  *buildable);
  void          (* add_child)              (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    GObject       *child,
					    const gchar   *type);
  void          (* set_buildable_property) (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    const gchar   *name,
					    const GValue  *value);
  GObject *     (* construct_child)        (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    const gchar   *name);
  gboolean      (* custom_tag_start)       (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    GObject       *child,
					    const gchar   *tagname,
					    GMarkupParser *parser,
					    gpointer      *data);
  void          (* custom_tag_end)         (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    GObject       *child,
					    const gchar   *tagname,
					    gpointer      *data);
  void          (* custom_finished)        (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    GObject       *child,
					    const gchar   *tagname,
					    gpointer       data);
  void          (* parser_finished)        (CtkBuildable  *buildable,
					    CtkBuilder    *builder);

  GObject *     (* get_internal_child)     (CtkBuildable  *buildable,
					    CtkBuilder    *builder,
					    const gchar   *childname);
};

The CtkBuildableIface interface contains method that are necessary to allow CtkBuilder to construct an object from a CtkBuilder UI definition.

Members

`set_name` ()	Stores the name attribute given in the CtkBuilder UI definition. CtkWidget stores the name as object data. Implement this method if your object has some notion of “name” and it makes sense to map the XML name attribute to it.
`get_name` ()	The getter corresponding to `set_name` . Implement this if you implement `set_name` .
`add_child` ()	Adds a child. The `type` parameter can be used to differentiate the kind of child. CtkContainer implements this to add add a child widget to the container, CtkNotebook uses the `type` to distinguish between page labels (of type "page-label") and normal children.
`set_buildable_property` ()	Sets a property of a buildable object. It is normally not necessary to implement this, `g_object_set_property()` is used by default. CtkWindow implements this to delay showing itself (i.e. setting the “visible” property) until the whole interface is created.
`construct_child` ()	Constructs a child of a buildable that has been specified as “constructor” in the UI definition. CtkUIManager implements this to reference to a widget created in a <ui> tag which is outside of the normal CtkBuilder UI definition hierarchy. A reference to the constructed object is returned and becomes owned by the caller.
`custom_tag_start` ()	Implement this if the buildable needs to parse content below <child>. To handle an element, the implementation must fill in the `parser` and `user_data` and return `TRUE`. CtkWidget implements this to parse keyboard accelerators specified in <accelerator> elements. CtkContainer implements it to map properties defined via <packing> elements to child properties. Note that `user_data` must be freed in `custom_tag_end` or `custom_finished` .
`custom_tag_end` ()	Called for the end tag of each custom element that is handled by the buildable (see `custom_tag_start` ).
`custom_finished` ()	Called for each custom tag handled by the buildable when the builder finishes parsing (see `custom_tag_start` )
`parser_finished` ()	Called when a builder finishes the parsing of a UI definition. It is normally not necessary to implement this, unless you need to perform special cleanup actions. CtkWindow sets the “visible” property here.
`get_internal_child` ()	Returns an internal child of a buildable. CtkDialog implements this to give access to its `vbox` , making it possible to add children to the vbox in a UI definition. Implement this if the buildable has internal children that may need to be accessed from a UI definition.