GtkBuildable

GtkBuildable — Interface for objects that can be built by GtkBuilder

Types and Values

Object Hierarchy

    GInterface
    ╰── GtkBuildable

Prerequisites

GtkBuildable requires GObject.

Known Implementations

GtkBuildable is implemented by GtkAboutDialog, GtkActionBar, GtkAnyFilter, GtkAppChooserButton, GtkAppChooserDialog, GtkAppChooserWidget, GtkApplicationWindow, GtkAspectFrame, GtkAssistant, GtkBox, GtkButton, GtkCalendar, GtkCellArea, GtkCellAreaBox, GtkCellView, GtkCenterBox, GtkCheckButton, GtkColorButton, GtkColorChooserDialog, GtkColorChooserWidget, GtkColumnView, GtkComboBox, GtkComboBoxText, GtkConstraintLayout, GtkDialog, GtkDragIcon, GtkDrawingArea, GtkDropDown, GtkEditableLabel, GtkEmojiChooser, GtkEntry, GtkEntryCompletion, GtkEveryFilter, GtkExpander, GtkFileChooserDialog, GtkFileChooserWidget, GtkFileFilter, GtkFixed, GtkFlowBox, GtkFlowBoxChild, GtkFontButton, GtkFontChooserDialog, GtkFontChooserWidget, GtkFrame, GtkGLArea, GtkGrid, GtkGridView, GtkHeaderBar, GtkIconView, GtkImage, GtkInfoBar, GtkLabel, GtkLevelBar, GtkLinkButton, GtkListBox, GtkListBoxRow, GtkListStore, GtkListView, GtkLockButton, GtkMediaControls, GtkMenuButton, GtkMessageDialog, GtkMultiFilter, GtkMultiSorter, GtkNotebook, GtkOverlay, GtkPageSetupUnixDialog, GtkPaned, GtkPasswordEntry, GtkPicture, GtkPopover, GtkPopoverMenu, GtkPopoverMenuBar, GtkPrintUnixDialog, GtkProgressBar, GtkRange, GtkRevealer, GtkScale, GtkScaleButton, GtkScrollbar, GtkScrolledWindow, GtkSearchBar, GtkSearchEntry, GtkSeparator, GtkShortcutController, GtkShortcutLabel, GtkShortcutsGroup, GtkShortcutsSection, GtkShortcutsShortcut, GtkShortcutsWindow, GtkSizeGroup, GtkSpinButton, GtkSpinner, GtkStack, GtkStackSidebar, GtkStackSwitcher, GtkStatusbar, GtkStringList, GtkSwitch, GtkText, GtkTextTagTable, GtkTextView, GtkToggleButton, GtkTreeExpander, GtkTreeStore, GtkTreeView, GtkTreeViewColumn, GtkVideo, GtkViewport, GtkVolumeButton, GtkWidget, GtkWindow, GtkWindowControls and GtkWindowHandle.

Includes

#include <gtk/gtk.h>

Description

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

The GtkBuildable interface is implemented by all widgets and many of the non-widget objects that are provided by GTK. The main user of this interface is GtkBuilder. 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 GtkBuilder format or run any extra routines at deserialization time.

Functions

gtk_buildable_get_buildable_id ()

const char *
gtk_buildable_get_buildable_id (GtkBuildable *buildable);

Gets the ID of the buildable object.

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

Parameters

buildable

a GtkBuildable

 

Returns

the ID set with gtk_buildable_set_buildable_id()


gtk_buildable_parse_context_get_element ()

const char *
gtk_buildable_parse_context_get_element
                               (GtkBuildableParseContext *context);

Retrieves the name of the currently open element.

If called from the start_element or end_element handlers this will give the element_name as passed to those functions. For the parent elements, see gtk_buildable_parse_context_get_element_stack().

Parameters

context

a GtkBuildablParseContext

 

Returns

the name of the currently open element, or NULL.

[nullable]


gtk_buildable_parse_context_get_element_stack ()

GPtrArray *
gtk_buildable_parse_context_get_element_stack
                               (GtkBuildableParseContext *context);

Retrieves the element stack from the internal state of the parser.

The returned GPtrArray is an array of strings where the last item is the currently open tag (as would be returned by gtk_buildable_parse_context_get_element()) and the previous item is its immediate parent.

This function is intended to be used in the start_element and end_element handlers where gtk_buildable_parse_context_get_element() would merely return the name of the element that is being processed.

Parameters

context

a GtkBuildableParseContext

 

Returns

the element stack, which must not be modified.

[transfer none][element-type utf8]


gtk_buildable_parse_context_get_position ()

void
gtk_buildable_parse_context_get_position
                               (GtkBuildableParseContext *context,
                                int *line_number,
                                int *char_number);

Retrieves the current line number and the number of the character on that line. Intended for use in error messages; there are no strict semantics for what constitutes the "current" line number other than "the best number we could come up with for error messages."

Parameters

context

a GtkBuildableParseContext

 

line_number

return location for a line number, or NULL.

[out][optional]

char_number

return location for a char-on-line number, or NULL.

[out][optional]

gtk_buildable_parse_context_pop ()

gpointer
gtk_buildable_parse_context_pop (GtkBuildableParseContext *context);

Completes the process of a temporary sub-parser redirection.

This function exists to collect the user_data allocated by a matching call to gtk_buildable_parse_context_push(). It must be called in the end_element handler corresponding to the start_element handler during which gtk_buildable_parse_context_push() was called. You must not call this function from the error callback -- the user_data is provided directly to the callback in that case.

This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface.

Parameters

context

a GtkBuildableParseContext

 

Returns

the user data passed to gtk_buildable_parse_context_push()


gtk_buildable_parse_context_push ()

void
gtk_buildable_parse_context_push (GtkBuildableParseContext *context,
                                  const GtkBuildableParser *parser,
                                  gpointer user_data);

Temporarily redirects markup data to a sub-parser.

This function may only be called from the start_element handler of a GtkBuildableParser. It must be matched with a corresponding call to gtk_buildable_parse_context_pop() in the matching end_element handler (except in the case that the parser aborts due to an error).

All tags, text and other data between the matching tags is redirected to the subparser given by parser . user_data is used as the user_data for that parser. user_data is also passed to the error callback in the event that an error occurs. This includes errors that occur in subparsers of the subparser.

The end tag matching the start tag for which this call was made is handled by the previous parser (which is given its own user_data) which is why gtk_buildable_parse_context_pop() is provided to allow "one last access" to the user_data provided to this function. In the case of error, the user_data provided here is passed directly to the error callback of the subparser and gtk_buildable_parse_context_pop() should not be called. In either case, if user_data was allocated then it ought to be freed from both of these locations.

This function is not intended to be directly called by users interested in invoking subparsers. Instead, it is intended to be used by the subparsers themselves to implement a higher-level interface.

For an example of how to use this, see g_markup_parse_context_push() which has the same kind of API.

Parameters

context

a GtkBuildableParseContext

 

parser

a GtkBuildableParser

 

user_data

user data to pass to GtkBuildableParser functions

 

Types and Values

GtkBuildable

typedef struct _GtkBuildable GtkBuildable;

struct GtkBuildableIface

struct GtkBuildableIface {
  GTypeInterface g_iface;

  /* virtual table */
  void          (* set_id)                 (GtkBuildable       *buildable,
                                            const char         *id);
  const char *  (* get_id)                 (GtkBuildable       *buildable);

  /**
   * GtkBuildableIface::add_child:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder
   * @child: child to add
   * @type: (nullable): kind of child or %NULL
   *
   * Adds a child to @buildable. @type is an optional string
   * describing how the child should be added.
   */
  void          (* add_child)              (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *type);
  void          (* set_buildable_property) (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *name,
                                            const GValue       *value);
  GObject *     (* construct_child)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *name);

  /**
   * GtkBuildableIface::custom_tag_start:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder used to construct this object
   * @child: (nullable): child object or %NULL for non-child tags
   * @tagname: name of tag
   * @parser: (out): a #GtkBuildableParser to fill in
   * @data: (out): return location for user data that will be passed in
   *   to parser functions
   *
   * Called for each unknown element under `<child>`.
   *
   * Returns: %TRUE if an object has a custom implementation, %FALSE
   *   if it doesn't.
   */
  gboolean      (* custom_tag_start)       (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            GtkBuildableParser *parser,
                                            gpointer           *data);
  /**
   * GtkBuildableIface::custom_tag_end:
   * @buildable: A #GtkBuildable
   * @builder: #GtkBuilder used to construct this object
   * @child: (nullable): child object or %NULL for non-child tags
   * @tagname: name of tag
   * @data: user data that will be passed in to parser functions
   *
   * Called at the end of each custom element handled by
   * the buildable.
   */
  void          (* custom_tag_end)         (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            gpointer            data);
   /**
    * GtkBuildableIface::custom_finished:
    * @buildable: a #GtkBuildable
    * @builder: a #GtkBuilder
    * @child: (nullable): child object or %NULL for non-child tags
    * @tagname: the name of the tag
    * @data: user data created in custom_tag_start
    *
    * Similar to gtk_buildable_parser_finished() but is
    * called once for each custom tag handled by the @buildable.
    */
  void          (* custom_finished)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            GObject            *child,
                                            const char         *tagname,
                                            gpointer            data);
  void          (* parser_finished)        (GtkBuildable       *buildable,
                                            GtkBuilder         *builder);

  /**
   * GtkBuildableIface::get_internal_child:
   * @buildable: a #GtkBuildable
   * @builder: a #GtkBuilder
   * @childname: name of child
   *
   * Retrieves the internal child called @childname of the @buildable object.
   *
   * Returns: (transfer none): the internal child of the buildable object
   */
  GObject *     (* get_internal_child)     (GtkBuildable       *buildable,
                                            GtkBuilder         *builder,
                                            const char         *childname);
};

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

Members

set_id ()

Stores the id attribute given in the GtkBuilder UI definition. GtkWidget stores the name as object data. Implement this method if your object has some notion of “ID” and it makes sense to map the XML id attribute to it.

 

get_id ()

The getter corresponding to set_id . Implement this if you implement set_id .

 

add_child ()

Adds a child. The type parameter can be used to differentiate the kind of child. GtkWidget implements this to add event controllers to the widget, GtkNotebook 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. GtkWindow 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. This can be used to reference a widget created in a <ui> tag which is outside of the normal GtkBuilder 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. GtkWidget implements this to parse accessible attributes specified in <accessibility> elements. 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. GtkWindow sets the “visible” property here.

 

get_internal_child ()

Returns an internal child of a buildable. GtkDialog 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.

 

struct GtkBuildableParser

struct GtkBuildableParser {
  /* Called for open tags <foo bar="baz"> */
  void (*start_element)  (GtkBuildableParseContext *context,
                          const char               *element_name,
                          const char              **attribute_names,
                          const char              **attribute_values,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called for close tags </foo> */
  void (*end_element)    (GtkBuildableParseContext *context,
                          const char               *element_name,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called for character data */
  /* text is not nul-terminated */
  void (*text)           (GtkBuildableParseContext *context,
                          const char               *text,
                          gsize                     text_len,
                          gpointer                  user_data,
                          GError                  **error);

  /* Called on error, including one set by other
   * methods in the vtable. The GError should not be freed.
   */
  void (*error)          (GtkBuildableParseContext *context,
                          GError                   *error,
                          gpointer                 user_data);
};

A sub-parser for GtkBuildable implementations.

Members

start_element ()

function called for open elements

 

end_element ()

function called for close elements

 

text ()

function called for character data

 

error ()

function called on error