Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | Safe-Inferred |
Language | Haskell2010 |
GI.Gtk.Objects.Builder
Contents
- Exported types
- Methods
- addFromFile
- addFromResource
- addFromString
- addObjectsFromFile
- addObjectsFromResource
- addObjectsFromString
- createClosure
- exposeObject
- extendWithTemplate
- getCurrentObject
- getObject
- getObjects
- getScope
- getTranslationDomain
- getTypeFromName
- new
- newFromFile
- newFromResource
- newFromString
- setCurrentObject
- setScope
- setTranslationDomain
- valueFromString
- valueFromStringType
- Properties
Description
A GtkBuilder
reads XML descriptions of a user interface and
instantiates the described objects.
To create a GtkBuilder
from a user interface description, call
builderNewFromFile
, builderNewFromResource
or builderNewFromString
.
In the (unusual) case that you want to add user interface
descriptions from multiple sources to the same GtkBuilder
you can
call builderNew
to get an empty builder and populate it by
(multiple) calls to builderAddFromFile
,
builderAddFromResource
or
builderAddFromString
.
A GtkBuilder
holds a reference to all objects that it has constructed
and drops these references when it is finalized. This finalization can
cause the destruction of non-widget objects or widgets which are not
contained in a toplevel window. For toplevel windows constructed by a
builder, it is the responsibility of the user to call
windowDestroy
to get rid of them and all the widgets
they contain.
The functions builderGetObject
and
builderGetObjects
can be used to access the widgets in
the interface by the names assigned to them inside the UI description.
Toplevel windows returned by these functions will stay around until the
user explicitly destroys them with windowDestroy
. Other
widgets will either be part of a larger hierarchy constructed by the
builder (in which case you should not have to worry about their lifecycle),
or without a parent, in which case they have to be added to some container
to make use of them. Non-widget objects need to be reffed with
objectRef
to keep them beyond the lifespan of the builder.
GtkBuilder UI Definitions
GtkBuilder
parses textual descriptions of user interfaces which are
specified in XML format. We refer to these descriptions as “GtkBuilder
UI definitions” or just “UI definitions” if the context is clear.
Structure of UI definitions
UI definition files are always encoded in UTF-8.
The toplevel element is <interface>
. It optionally takes a “domain”
attribute, which will make the builder look for translated strings
using dgettext()
in the domain specified. This can also be done by
calling builderSetTranslationDomain
on the builder.
For example:
xml code
<?xml version="1.0" encoding="UTF-8"> <interface domain="your-app"> ... </interface>
Requirements
The target toolkit version(s) are described by <requires>
elements,
the “lib” attribute specifies the widget library in question (currently
the only supported value is “gtk”) and the “version” attribute specifies
the target version in the form “<major>
.<minor>
”. GtkBuilder
will
error out if the version requirements are not met. For example:
xml code
<?xml version="1.0" encoding="UTF-8"> <interface domain="your-app"> <requires lib="gtk" version="4.0" /> </interface>
Objects
Objects are defined as children of the <interface>
element.
Objects are described by <object>
elements, which can contain
<property>
elements to set properties, <signal>
elements which
connect signals to handlers, and <child>
elements, which describe
child objects.
Typically, the specific kind of object represented by an <object>
element is specified by the “class” attribute. If the type has not
been loaded yet, GTK tries to find the get_type()
function from the
class name by applying heuristics. This works in most cases, but if
necessary, it is possible to specify the name of the get_type()
function explicitly with the "type-func" attribute. If your UI definition
is referencing internal types, you should make sure to call
g_type_ensure()
for each object type before parsing the UI definition.
Objects may be given a name with the “id” attribute, which allows the
application to retrieve them from the builder with
builderGetObject
. An id is also necessary to use the
object as property value in other parts of the UI definition. GTK
reserves ids starting and ending with ___
(three consecutive
underscores) for its own purposes.
Properties
Setting properties of objects is pretty straightforward with the
<property>
element: the “name” attribute specifies the name of the
property, and the content of the element specifies the value:
xml code
<object class="GtkButton"> <property name="label">Hello, world</property> </object>
If the “translatable” attribute is set to a true value, GTK uses
gettext()
(or dgettext()
if the builder has a translation domain set)
to find a translation for the value. This happens before the value
is parsed, so it can be used for properties of any type, but it is
probably most useful for string properties. It is also possible to
specify a context to disambiguate short strings, and comments which
may help the translators:
xml code
<object class="GtkButton"> <property name="label" translatable="yes" context="button">Hello, world</property> </object>
GtkBuilder
can parse textual representations for the most common
property types:
- characters
- strings
- integers
- floating-point numbers
- booleans (strings like “TRUE”, “t”, “yes”, “y”, “1” are interpreted as true values, strings like “FALSE”, “f”, “no”, “n”, “0” are interpreted as false values)
- enumeration types (can be specified by their full C identifier their short name used when registering the enumeration type, or their integer value)
- flag types (can be specified by their C identifier, short name, integer value, and optionally combined with “|” for bitwise OR, e.g. “GTK_INPUT_HINT_EMOJI|GTK_INPUT_HINT_LOWERCASE”, or “emoji|lowercase”)
- colors (in a format understood by
rGBAParse
) GVariant
(can be specified in the format understood by [funcgLib
.Variant.parse])- pixbufs (can be specified as a filename of an image file to load)
Objects can be referred to by their name and by default refer to
objects declared in the local XML fragment and objects exposed via
builderExposeObject
. In general, GtkBuilder
allows
forward references to objects declared in the local XML; an object
doesn’t have to be constructed before it can be referred to. The
exception to this rule is that an object has to be constructed before
it can be used as the value of a construct-only property.
Child objects
Many widgets have properties for child widgets, such as Expander:child. In this case, the preferred way to specify the child widget in a ui file is to simply set the property:
xml code
<object class="GtkExpander"> <property name="child"> <object class="GtkLabel"> ... </object> </property> </object>
Generic containers that can contain an arbitrary number of children,
such as Box
instead use the <child>
element. A <child>
element contains an <object>
element which describes the child object.
Most often, child objects are widgets inside a container, but they can
also be, e.g., actions in an action group, or columns in a tree model.
Any object type that implements the Buildable
interface can
specify how children may be added to it. Since many objects and widgets that
are included with GTK already implement the GtkBuildable
interface,
typically child objects can be added using the <child>
element without
having to be concerned about the underlying implementation.
See the `GtkWidget` documentation
for many examples of using GtkBuilder
with widgets, including setting
child objects using the <child>
element.
A noteworthy special case to the general rule that only objects implementing
GtkBuildable
may specify how to handle the <child>
element is that
GtkBuilder
provides special support for adding objects to a
ListStore
by using the <child>
element. For instance:
xml code
<object class="GListStore"> <property name="item-type">MyObject</property> <child> <object class="MyObject" /> </child> ... </object>
Property bindings
It is also possible to bind a property value to another object's
property value using the attributes "bind-source" to specify the
source object of the binding, and optionally, "bind-property" and
"bind-flags" to specify the source property and source binding flags
respectively. Internally, GtkBuilder
implements this using
Binding
objects.
For instance, in the example below the “label” property of the
bottom_label
widget is bound to the “label” property of the
top_button
widget:
xml code
<object class="GtkBox"> <property name="orientation">vertical</property> <child> <object class="GtkButton" id="top_button"> <property name="label">Hello, world</property> </object> </child> <child> <object class="GtkLabel" id="bottom_label"> <property name="label" bind-source="top_button" bind-property="label" bind-flags="sync-create" /> </object> </child> </object>
For more information, see the documentation of the
objectBindProperty
method.
Please note that another way to set up bindings between objects in .ui files
is to use the GtkExpression
methodology. See the
`GtkExpression` documentation
for more information.
Internal children
Sometimes it is necessary to refer to widgets which have implicitly
been constructed by GTK as part of a composite widget, to set
properties on them or to add further children (e.g. the content area
of a GtkDialog
). This can be achieved by setting the “internal-child”
property of the <child>
element to a true value. Note that GtkBuilder
still requires an <object>
element for the internal child, even if it
has already been constructed.
Specialized children
A number of widgets have different places where a child can be added
(e.g. tabs vs. page content in notebooks). This can be reflected in
a UI definition by specifying the “type” attribute on a <child>
The possible values for the “type” attribute are described in the
sections describing the widget-specific portions of UI definitions.
Signal handlers and function pointers
Signal handlers are set up with the <signal>
element. The “name”
attribute specifies the name of the signal, and the “handler” attribute
specifies the function to connect to the signal.
xml code
<object class="GtkButton" id="hello_button"> <signal name="clicked" handler="hello_button__clicked" /> </object>
The remaining attributes, “after”, “swapped” and “object”, have the
same meaning as the corresponding parameters of the
GObject.signal_connect_object
or GObject.signal_connect_data
functions:
- “after” matches the
G_CONNECT_AFTER
flag, and will ensure that the handler is called after the default class closure for the signal - “swapped” matches the
G_CONNECT_SWAPPED
flag, and will swap the instance and closure arguments when invoking the signal handler - “object” will bind the signal handler to the lifetime of the object referenced by the attribute
By default "swapped" will be set to "yes" if not specified otherwise, in the case where "object" is set, for convenience. A “last_modification_time” attribute is also allowed, but it does not have a meaning to the builder.
When compiling applications for Windows, you must declare signal callbacks
with the G_MODULE_EXPORT
decorator, or they will not be put in the symbol
table:
c code
G_MODULE_EXPORT void hello_button__clicked (GtkButton *button, gpointer data) { // ... }
On Linux and Unix, this is not necessary; applications should instead
be compiled with the -Wl,--export-dynamic
argument inside their compiler
flags, and linked against gmodule-export-2.0
.
Example UI Definition
xml code
<interface> <object class="GtkDialog" id="dialog1"> <child internal-child="content_area"> <object class="GtkBox"> <child internal-child="action_area"> <object class="GtkBox"> <child> <object class="GtkButton" id="ok_button"> <property name="label" translatable="yes">_Ok</property> <property name="use-underline">True</property> <signal name="clicked" handler="ok_button_clicked"/> </object> </child> </object> </child> </object> </child> </object> </interface>
Using GtkBuildable for extending UI definitions
Objects can implement the Buildable
interface to add custom
elements and attributes to the XML. Typically, any extension will be
documented in each type that implements the interface.
Templates
When describing a Widget
, you can use the <template>
tag to
describe a UI bound to a specific widget type. GTK will automatically load
the UI definition when instantiating the type, and bind children and
signal handlers to instance fields and function symbols.
For more information, see the `GtkWidget` documentation for details.
Synopsis
- newtype Builder = Builder (ManagedPtr Builder)
- class (GObject o, IsDescendantOf Builder o) => IsBuilder o
- toBuilder :: (MonadIO m, IsBuilder o) => o -> m Builder
- builderAddFromFile :: (HasCallStack, MonadIO m, IsBuilder a) => a -> [Char] -> m ()
- builderAddFromResource :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> m ()
- builderAddFromString :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> Int64 -> m ()
- builderAddObjectsFromFile :: (HasCallStack, MonadIO m, IsBuilder a) => a -> [Char] -> [Text] -> m ()
- builderAddObjectsFromResource :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> [Text] -> m ()
- builderAddObjectsFromString :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> Int64 -> [Text] -> m ()
- builderCreateClosure :: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) => a -> Text -> [BuilderClosureFlags] -> Maybe b -> m (Maybe (GClosure c))
- builderExposeObject :: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) => a -> Text -> b -> m ()
- builderExtendWithTemplate :: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) => a -> b -> GType -> Text -> Int64 -> m ()
- builderGetCurrentObject :: (HasCallStack, MonadIO m, IsBuilder a) => a -> m (Maybe Object)
- builderGetObject :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> m (Maybe Object)
- builderGetObjects :: (HasCallStack, MonadIO m, IsBuilder a) => a -> m [Object]
- builderGetScope :: (HasCallStack, MonadIO m, IsBuilder a) => a -> m BuilderScope
- builderGetTranslationDomain :: (HasCallStack, MonadIO m, IsBuilder a) => a -> m (Maybe Text)
- builderGetTypeFromName :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Text -> m GType
- builderNew :: (HasCallStack, MonadIO m) => m Builder
- builderNewFromFile :: (HasCallStack, MonadIO m) => [Char] -> m Builder
- builderNewFromResource :: (HasCallStack, MonadIO m) => Text -> m Builder
- builderNewFromString :: (HasCallStack, MonadIO m) => Text -> Int64 -> m Builder
- builderSetCurrentObject :: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) => a -> Maybe b -> m ()
- builderSetScope :: (HasCallStack, MonadIO m, IsBuilder a, IsBuilderScope b) => a -> Maybe b -> m ()
- builderSetTranslationDomain :: (HasCallStack, MonadIO m, IsBuilder a) => a -> Maybe Text -> m ()
- builderValueFromString :: (HasCallStack, MonadIO m, IsBuilder a) => a -> GParamSpec -> Text -> m GValue
- builderValueFromStringType :: (HasCallStack, MonadIO m, IsBuilder a) => a -> GType -> Text -> m GValue
- clearBuilderCurrentObject :: (MonadIO m, IsBuilder o) => o -> m ()
- constructBuilderCurrentObject :: (IsBuilder o, MonadIO m, IsObject a) => a -> m (GValueConstruct o)
- getBuilderCurrentObject :: (MonadIO m, IsBuilder o) => o -> m (Maybe Object)
- setBuilderCurrentObject :: (MonadIO m, IsBuilder o, IsObject a) => o -> a -> m ()
- clearBuilderScope :: (MonadIO m, IsBuilder o) => o -> m ()
- constructBuilderScope :: (IsBuilder o, MonadIO m, IsBuilderScope a) => a -> m (GValueConstruct o)
- getBuilderScope :: (MonadIO m, IsBuilder o) => o -> m BuilderScope
- setBuilderScope :: (MonadIO m, IsBuilder o, IsBuilderScope a) => o -> a -> m ()
- clearBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> m ()
- constructBuilderTranslationDomain :: (IsBuilder o, MonadIO m) => Text -> m (GValueConstruct o)
- getBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> m (Maybe Text)
- setBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> Text -> m ()
Exported types
Memory-managed wrapper type.
Instances
Eq Builder Source # | |
GObject Builder Source # | |
Defined in GI.Gtk.Objects.Builder | |
ManagedPtrNewtype Builder Source # | |
Defined in GI.Gtk.Objects.Builder Methods toManagedPtr :: Builder -> ManagedPtr Builder | |
TypedObject Builder Source # | |
Defined in GI.Gtk.Objects.Builder | |
HasParentTypes Builder Source # | |
Defined in GI.Gtk.Objects.Builder | |
IsGValue (Maybe Builder) Source # | Convert |
Defined in GI.Gtk.Objects.Builder Methods gvalueGType_ :: IO GType gvalueSet_ :: Ptr GValue -> Maybe Builder -> IO () gvalueGet_ :: Ptr GValue -> IO (Maybe Builder) | |
type ParentTypes Builder Source # | |
Defined in GI.Gtk.Objects.Builder type ParentTypes Builder = '[Object] |
class (GObject o, IsDescendantOf Builder o) => IsBuilder o Source #
Instances
(GObject o, IsDescendantOf Builder o) => IsBuilder o Source # | |
Defined in GI.Gtk.Objects.Builder |
Methods
Click to display all available methods, including inherited ones
Methods
addFromFile, addFromResource, addFromString, addObjectsFromFile, addObjectsFromResource, addObjectsFromString, bindProperty, bindPropertyFull, createClosure, exposeObject, extendWithTemplate, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, valueFromString, valueFromStringType, watchClosure.
Getters
getCurrentObject, getData, getObject, getObjects, getProperty, getQdata, getScope, getTranslationDomain, getTypeFromName.
Setters
setCurrentObject, setData, setDataFull, setProperty, setScope, setTranslationDomain.
addFromFile
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> [Char] |
|
-> m () | (Can throw |
Parses a file containing a UI definition and merges it with
the current contents of builder
.
This function is useful if you need to call
builderSetCurrentObject
) to add user data to
callbacks before loading GtkBuilder UI. Otherwise, you probably
want builderNewFromFile
instead.
If an error occurs, 0 will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
, G_MARKUP_ERROR
or G_FILE_ERROR
domains.
It’s not really reasonable to attempt to handle failures of this
call. You should not use this function with untrusted files (ie:
files that are not part of your application). Broken GtkBuilder
files can easily crash your program, and it’s possible that memory
was leaked leading up to the reported failure. The only reasonable
thing to do when an error is detected is to call g_error()
.
addFromResource
builderAddFromResource Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> m () | (Can throw |
Parses a resource file containing a UI definition
and merges it with the current contents of builder
.
This function is useful if you need to call
builderSetCurrentObject
to add user data to
callbacks before loading GtkBuilder UI. Otherwise, you probably
want builderNewFromResource
instead.
If an error occurs, 0 will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
, G_MARKUP_ERROR
or G_RESOURCE_ERROR
domain.
It’s not really reasonable to attempt to handle failures of this
call. The only reasonable thing to do when an error is detected is
to call g_error()
.
addFromString
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> Int64 |
|
-> m () | (Can throw |
Parses a string containing a UI definition and merges it
with the current contents of builder
.
This function is useful if you need to call
builderSetCurrentObject
to add user data to
callbacks before loading GtkBuilder
UI. Otherwise, you probably
want builderNewFromString
instead.
Upon errors False
will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
, G_MARKUP_ERROR
or
G_VARIANT_PARSE_ERROR
domain.
It’s not really reasonable to attempt to handle failures of this
call. The only reasonable thing to do when an error is detected is
to call g_error()
.
addObjectsFromFile
builderAddObjectsFromFile Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> [Char] |
|
-> [Text] |
|
-> m () | (Can throw |
Parses a file containing a UI definition building only the
requested objects and merges them with the current contents
of builder
.
Upon errors, 0 will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
, G_MARKUP_ERROR
or G_FILE_ERROR
domain.
If you are adding an object that depends on an object that is not
its child (for instance a GtkTreeView
that depends on its
GtkTreeModel
), you have to explicitly list all of them in objectIds
.
addObjectsFromResource
builderAddObjectsFromResource Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> [Text] |
|
-> m () | (Can throw |
Parses a resource file containing a UI definition, building
only the requested objects and merges them with the current
contents of builder
.
Upon errors, 0 will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
, G_MARKUP_ERROR
or G_RESOURCE_ERROR
domain.
If you are adding an object that depends on an object that is not
its child (for instance a GtkTreeView
that depends on its
GtkTreeModel
), you have to explicitly list all of them in objectIds
.
addObjectsFromString
builderAddObjectsFromString Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> Int64 |
|
-> [Text] |
|
-> m () | (Can throw |
Parses a string containing a UI definition, building only the
requested objects and merges them with the current contents of
builder
.
Upon errors False
will be returned and error
will be assigned a
GError
from the GTK_BUILDER_ERROR
or G_MARKUP_ERROR
domain.
If you are adding an object that depends on an object that is not
its child (for instance a GtkTreeView
that depends on its
GtkTreeModel
), you have to explicitly list all of them in objectIds
.
createClosure
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) | |
=> a |
|
-> Text |
|
-> [BuilderClosureFlags] |
|
-> Maybe b |
|
-> m (Maybe (GClosure c)) | Returns: A new closure for invoking |
Creates a closure to invoke the function called functionName
.
This is using the create_closure()
implementation of builder
's
BuilderScope
.
If no closure could be created, Nothing
will be returned and error
will be set.
exposeObject
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) | |
=> a |
|
-> Text |
|
-> b |
|
-> m () |
Add object
to the builder
object pool so it can be
referenced just like any other object built by builder.
Only a single object may be added using name
. However,
it is not an error to expose the same object under multiple
names. gtk_builder_get_object()
may be used to determine
if an object has already been added with name
.
extendWithTemplate
builderExtendWithTemplate Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) | |
=> a |
|
-> b |
|
-> GType |
|
-> Text |
|
-> Int64 |
|
-> m () | (Can throw |
Main private entry point for building composite components from template XML.
Most likely you do not need to call this function in applications as
templates are handled by GtkWidget
.
getCurrentObject
builderGetCurrentObject Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> m (Maybe Object) | Returns: the current object |
Gets the current object set via builderSetCurrentObject
.
getObject
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> m (Maybe Object) | Returns: the object named |
Gets the object named name
.
Note that this function does not increment the reference count of the returned object.
getObjects
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> m [Object] | Returns: a
newly-allocated |
Gets all objects that have been constructed by builder
.
Note that this function does not increment the reference counts of the returned objects.
getScope
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> m BuilderScope | Returns: the current scope |
Gets the scope in use that was set via builderSetScope
.
getTranslationDomain
builderGetTranslationDomain Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> m (Maybe Text) | Returns: the translation domain |
Gets the translation domain of builder
.
getTypeFromName
builderGetTypeFromName Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Text |
|
-> m GType | Returns: the |
Looks up a type by name.
This is using the virtual function that GtkBuilder
has
for that purpose. This is mainly used when implementing
the GtkBuildable
interface on a type.
new
Arguments
:: (HasCallStack, MonadIO m) | |
=> m Builder | Returns: a new (empty) |
Creates a new empty builder object.
This function is only useful if you intend to make multiple calls
to builderAddFromFile
, builderAddFromResource
or builderAddFromString
in order to merge multiple UI
descriptions into a single builder.
newFromFile
Arguments
:: (HasCallStack, MonadIO m) | |
=> [Char] |
|
-> m Builder | Returns: a |
Parses the UI definition in the file filename
.
If there is an error opening the file or parsing the description then the program will be aborted. You should only ever attempt to parse user interface descriptions that are shipped as part of your program.
newFromResource
builderNewFromResource Source #
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> m Builder | Returns: a |
Parses the UI definition at resourcePath
.
If there is an error locating the resource or parsing the description, then the program will be aborted.
newFromString
Arguments
:: (HasCallStack, MonadIO m) | |
=> Text |
|
-> Int64 |
|
-> m Builder | Returns: a |
Parses the UI definition in string
.
If string
is Nothing
-terminated, then length
should be -1.
If length
is not -1, then it is the length of string
.
If there is an error parsing string
then the program will be
aborted. You should not attempt to parse user interface description
from untrusted sources.
setCurrentObject
builderSetCurrentObject Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a, IsObject b) | |
=> a |
|
-> Maybe b |
|
-> m () |
Sets the current object for the builder
.
The current object can be thought of as the this
object that the
builder is working for and will often be used as the default object
when an object is optional.
widgetInitTemplate
for example will set the current
object to the widget the template is inited for. For functions like
builderNewFromResource
, the current object will be Nothing
.
setScope
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a, IsBuilderScope b) | |
=> a |
|
-> Maybe b |
|
-> m () |
Sets the scope the builder should operate in.
If scope
is Nothing
, a new BuilderCScope
will be created.
setTranslationDomain
builderSetTranslationDomain Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> Maybe Text |
|
-> m () |
Sets the translation domain of builder
.
valueFromString
builderValueFromString Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> GParamSpec |
|
-> Text |
|
-> m GValue | (Can throw |
Demarshals a value from a string.
This function calls valueInit
on the value
argument,
so it need not be initialised beforehand.
Can handle char, uchar, boolean, int, uint, long,
ulong, enum, flags, float, double, string, GdkRGBA
and
GtkAdjustment
type values.
Upon errors False
will be returned and error
will be
assigned a GError
from the GTK_BUILDER_ERROR
domain.
valueFromStringType
builderValueFromStringType Source #
Arguments
:: (HasCallStack, MonadIO m, IsBuilder a) | |
=> a |
|
-> GType |
|
-> Text |
|
-> m GValue | (Can throw |
Demarshals a value from a string.
Unlike builderValueFromString
, this function
takes a GType
instead of GParamSpec
.
Calls valueInit
on the value
argument, so it
need not be initialised beforehand.
Upon errors False
will be returned and error
will be
assigned a GError
from the GTK_BUILDER_ERROR
domain.
Properties
currentObject
The object the builder is evaluating for.
clearBuilderCurrentObject :: (MonadIO m, IsBuilder o) => o -> m () Source #
Set the value of the “current-object
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#currentObject
constructBuilderCurrentObject :: (IsBuilder o, MonadIO m, IsObject a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “current-object
” property. This is rarely needed directly, but it is used by new
.
getBuilderCurrentObject :: (MonadIO m, IsBuilder o) => o -> m (Maybe Object) Source #
Get the value of the “current-object
” property.
When overloading is enabled, this is equivalent to
get
builder #currentObject
setBuilderCurrentObject :: (MonadIO m, IsBuilder o, IsObject a) => o -> a -> m () Source #
Set the value of the “current-object
” property.
When overloading is enabled, this is equivalent to
set
builder [ #currentObject:=
value ]
scope
The scope the builder is operating in
clearBuilderScope :: (MonadIO m, IsBuilder o) => o -> m () Source #
Set the value of the “scope
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#scope
constructBuilderScope :: (IsBuilder o, MonadIO m, IsBuilderScope a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “scope
” property. This is rarely needed directly, but it is used by new
.
getBuilderScope :: (MonadIO m, IsBuilder o) => o -> m BuilderScope Source #
Get the value of the “scope
” property.
When overloading is enabled, this is equivalent to
get
builder #scope
setBuilderScope :: (MonadIO m, IsBuilder o, IsBuilderScope a) => o -> a -> m () Source #
Set the value of the “scope
” property.
When overloading is enabled, this is equivalent to
set
builder [ #scope:=
value ]
translationDomain
The translation domain used when translating property values that have been marked as translatable.
If the translation domain is Nothing
, GtkBuilder
uses gettext()
,
otherwise dgettext
.
clearBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> m () Source #
Set the value of the “translation-domain
” property to Nothing
.
When overloading is enabled, this is equivalent to
clear
#translationDomain
constructBuilderTranslationDomain :: (IsBuilder o, MonadIO m) => Text -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “translation-domain
” property. This is rarely needed directly, but it is used by new
.
getBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> m (Maybe Text) Source #
Get the value of the “translation-domain
” property.
When overloading is enabled, this is equivalent to
get
builder #translationDomain
setBuilderTranslationDomain :: (MonadIO m, IsBuilder o) => o -> Text -> m () Source #
Set the value of the “translation-domain
” property.
When overloading is enabled, this is equivalent to
set
builder [ #translationDomain:=
value ]