AuroraMiddleware/gtk
1
0
Fork 1
mirror of https://gitlab.gnome.org/GNOME/gtk.git synced 2025-01-13 14:00:09 +00:00
Code Issues Projects Releases Wiki Activity

documentation updates

Browse Source 
svn path=/trunk/; revision=18303
This commit is contained in:
Matthias Clasen 2007-06-30 06:24:11 +00:00
parent 5e138866c0
commit 3060ce7ddc
7 changed files with 295 additions and 198 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
ChangeLog
View File

@ -1,3 +1,8 @@
2007-06-30 Matthias Clasen <mclasen@redhat.com>
* gtk/gtkbuilder.c:
* gtk/gtkbuildable.c: Documentation updates.
2007-06-29 Matthias Clasen <mclasen@redhat.com>
* gdk/gdk.symbols:

6
docs/reference/ChangeLog
View File

@ -1,3 +1,9 @@
2007-06-29 Matthias Clasen <mclasen@redhat.com>
* gtk/tmpl/gtkbuilder.sgml:
* gtk/tmpl/gtkbuildable.sgml:
* gtk/tmpl/gtkuimanager.sgml: Updates
2007-06-29 Matthias Clasen <mclasen@redhat.com>
* gdk/gdk-sections.txt: Add gdk_keymap_have_bidi_layouts

67
docs/reference/gtk/tmpl/gtkbuildable.sgml
View File

@ -6,14 +6,23 @@ Interface for objects that can be built by GtkBuilder
<!-- ##### SECTION Long_Description ##### -->
<para>
In order to allow construction from a XML UI description,
an object class must implement the #GtkBuildable interface.
The interface includes method for setting names and properties
of objects, parsing custom tags, constructing child objects.
In order to allow construction from a <link linkend="BUILDER-UI">GtkBuilder
UI description</link>, an object class must implement the
GtkBuildable interface. The interface includes methods for setting
names and properties of objects, parsing custom tags, constructing
child objects.
</para>
<para>
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
<function>gtk_buildable_...</function> functions.
</para>
<!-- ##### SECTION See_Also ##### -->
<!-- ##### SECTION Stability_Level ##### -->
@ -25,28 +34,54 @@ of objects, parsing custom tags, constructing child objects.
<!-- ##### STRUCT GtkBuildableIface ##### -->
<para>
The #GtkBuildableIface interface contains method that are
The GtkBuildableIface interface contains method that are
necessary to allow #GtkBuilder to construct an object from
a XML UI description.
a GtkBuilder UI definition.
</para>
@g_iface: the parent class
@set_name: Stores the name attribute given in the XML UI description.
#GtkWidget maps this to the GtkWidget:name property, and
@set_name: Stores the name attribute given in the GtkBuilder UI definition.
#GtkWidget maps this to the #GtkWidget:name property, and
gtk_buildable_set_name() has a fallback implementation that 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:
@set_buildable_property:
@construct_child:
@custom_tag_start:
@custom_tag_end:
@custom_finished:
@parser_finished:
@get_internal_child:
@add_child: Adds a child. The @type parameter can be used to
differentiate the kind of child. #GtkContainer implements this
to add add a child widget to the container, #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 #GtkWidget: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. #GtkUIManager implements
this to reference to a widget created in a &lt;ui&gt; tag which is outside
of the normal GtkBuilder UI definition hierarchy.
@custom_tag_start: Implement this if the buildable needs to parse
content below &lt;child&gt;. To handle an element, the implementation
must fill in the @parser structure and @user_data and return %TRUE.
#GtkWidget implements this to parse keyboard accelerators specified
in &lt;accelerator&gt; elements. #GtkContainer implements it to map
properties defined via &lt;packing&gt; 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. #GtkWindow sets
the #GtkWidget: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.
<!-- ##### FUNCTION gtk_buildable_set_name ##### -->
<para>

89
docs/reference/gtk/tmpl/gtkbuilder.sgml
View File

@ -2,26 +2,70 @@
GtkBuilder
<!-- ##### SECTION Short_Description ##### -->
Build an interface from a UI definition description.
Build an interface from an XML UI definition
<!-- ##### SECTION Long_Description ##### -->
<para>
This object represents an `instantiation' of an UI definition description.
When one of these objects is created, the XML file is read, and the
interface is created. The GtkBuilder object then provides an interface
for accessing the widgets in the interface by the names assigned to
them inside the UI description.
The GtkBuilder object can also be used to connect handlers to the named
signals in the description. GtkBuilder also provides an interface by
which it can look up the signal handler names in the program's symbol
table and automatically connect as many handlers up as it can that way.
A GtkBuilder is an auxiliary object that reads textual descriptions
of a user interface and instantiates the described objects.
The functions gtk_builder_get_object() and gtk_builder_get_objects()
can be used to access the widgets in the interface by the names assigned
to them inside the UI description. The function gtk_builder_connect_signals()
and variants thereof can be used to connect handlers to the named signals
in the description.
</para>
<para>
A GtkBuilder holds a reference to all objects that it has constructed
and drops these references when it is finalized. To keep objects beyond
the lifespan of the builder, they must be fetched with gtk_builder_get_object()
and reffed with g_object_ref(). It is the responsibility of the user
to destroy all toplevel windows that have been constructed by a builder
(these are not automatically cleaned up when the builder is finalized,
since GTK+ itself holds a reference to each toplevel window).
</para>
<refsect2 id="BUILDER-UI"><title>GtkBuilder UI Definitions</title>
<para>
GtkBuilder parses textual descriptions of user interfaces which
are specified in an XML format which can be roughly described
by the following DTD.
</para>
<para>
Do not confuse GtkBuilder UI Definitions with
<link linkend="XML-UI">GtkUIManager UI Definitions</link>,
which are more limited in scope.
</para>
<para>
<programlisting><![CDATA[
<!ELEMENT interface object* >
<!ELEMENT object (property|signal|child|ANY)* >
<!ELEMENT property PCDATA >
<!ELEMENT signal EMPTY >
<!ELEMENT child (object|ANY*) >
<!ATTLIST interface domain #IMPLIED >
<!ATTLIST object class #REQUIRED
id #IMPLIED
constructor #IMPLIED >
<!ATTLIST property name #REQUIRED
translatable #IMPLIED >
<!ATTLIST signal name #REQUIRED
handler #REQUIRED
after #IMPLIED
object #IMPLIED >
<!ATTLIST child type #IMPLIED
internal-child #IMPLIED
type-func #IMPLIED >
]]></programlisting>
</para>
<para>
Beyond this general structure, several object classes define
their own XML DTD fragments for filling in the ANY placeholders.
</para>
</refsect2>
<!-- ##### SECTION See_Also ##### -->
<para>
SEE ALSO
</para>
<!-- ##### SECTION Stability_Level ##### -->
@ -37,6 +81,19 @@ SEE ALSO
</para>
<!-- ##### STRUCT GtkBuilderClass ##### -->
<para>
</para>
@get_type_from_name: Looks up a type by name. The default
implementation applies heuristics to map type names to
<function>_get_type</function> function names, e.g.
GtkHBox to gtk_hbox_get_type(). This virtual function
is provided to allow language bindings to intercept the
type resolution process.
<!-- ##### USER_FUNCTION GtkBuilderConnectFunc ##### -->
<para>
@ -153,9 +210,11 @@ SEE ALSO
</para>
@builder:
@pspec:
@string:
@value:
@error:
@Returns:
@ -164,9 +223,11 @@ SEE ALSO
</para>
@builder:
@type:
@string:
@value:
@error:
@Returns:

69
docs/reference/gtk/tmpl/gtkuimanager.sgml
View File

@ -14,40 +14,47 @@ action groups.
<para>
The UI definitions are specified in an XML format which can be
roughly described by the following DTD.
<programlisting>
&lt;!ELEMENT ui (menubar|toolbar|popup|accelerator)* &gt;
&lt;!ELEMENT menubar (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT menu (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT popup (menuitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT toolbar (toolitem|separator|placeholder)* &gt;
&lt;!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* &gt;
&lt;!ELEMENT menuitem EMPTY &gt;
&lt;!ELEMENT toolitem (menu?) &gt;
&lt;!ELEMENT separator EMPTY &gt;
&lt;!ELEMENT accelerator EMPTY &gt;
&lt;!ATTLIST menubar name &num;IMPLIED
action &num;IMPLIED &gt;
&lt;!ATTLIST toolbar name &num;IMPLIED
action &num;IMPLIED &gt;
&lt;!ATTLIST popup name &num;IMPLIED
action &num;IMPLIED &gt;
&lt;!ATTLIST placeholder name &num;IMPLIED
action &num;IMPLIED &gt;
&lt;!ATTLIST separator name &num;IMPLIED
</para>
<para>
Do not confuse the GtkUIManager UI Definitions described here with
the similarly named <link linkend="BUILDER-UI">GtkBuilder UI
Definitions</link>.
</para>
<para>
<programlisting><![CDATA[
<!ELEMENT ui (menubar|toolbar|popup|accelerator)* >
<!ELEMENT menubar (menuitem|separator|placeholder|menu)* >
<!ELEMENT menu (menuitem|separator|placeholder|menu)* >
<!ELEMENT popup (menuitem|separator|placeholder|menu)* >
<!ELEMENT toolbar (toolitem|separator|placeholder)* >
<!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
<!ELEMENT menuitem EMPTY >
<!ELEMENT toolitem (menu?) >
<!ELEMENT separator EMPTY >
<!ELEMENT accelerator EMPTY >
<!ATTLIST menubar name &num;IMPLIED
action &num;IMPLIED >
<!ATTLIST toolbar name &num;IMPLIED
action &num;IMPLIED >
<!ATTLIST popup name &num;IMPLIED
action &num;IMPLIED >
<!ATTLIST placeholder name &num;IMPLIED
action &num;IMPLIED >
<!ATTLIST separator name &num;IMPLIED
action &num;IMPLIED
expand (true|false) &num;IMPLIED &gt;
&lt;!ATTLIST menu name &num;IMPLIED
expand (true|false) &num;IMPLIED >
<!ATTLIST menu name &num;IMPLIED
action &num;REQUIRED
position (top|bot) &num;IMPLIED &gt;
&lt;!ATTLIST menuitem name &num;IMPLIED
position (top|bot) &num;IMPLIED >
<!ATTLIST menuitem name &num;IMPLIED
action &num;REQUIRED
position (top|bot) &num;IMPLIED &gt;
&lt;!ATTLIST toolitem name &num;IMPLIED
position (top|bot) &num;IMPLIED >
<!ATTLIST toolitem name &num;IMPLIED
action &num;REQUIRED
position (top|bot) &num;IMPLIED &gt;
&lt;!ATTLIST accelerator name &num;IMPLIED
action &num;REQUIRED &gt;
</programlisting>
position (top|bot) &num;IMPLIED >
<!ATTLIST accelerator name &num;IMPLIED
action &num;REQUIRED >
]]></programlisting>
There are some additional restrictions beyond those specified in the
DTD, e.g. every toolitem must have a toolbar in its anchestry and
every menuitem must have a menubar or popup in its anchestry. Since
@ -194,7 +201,7 @@ to which the submenu is associated.
<!-- ##### SECTION See_Also ##### -->
<para>
#GtkBuilder
</para>
<!-- ##### SECTION Stability_Level ##### -->

82
gtk/gtkbuildable.c
View File

@ -44,10 +44,7 @@ gtk_buildable_get_type (void)
* @buildable: a #GtkBuildable
* @name: name to set
*
* Sets the name of the buildable object, it's used to synchronize the name
* if the object already has it's own concept of name.
*
* #GtkWidget implements this to map the buildable name to the widget name
* Sets the name of the @buildable object.
*
* Since: 2.12
**/
@ -75,12 +72,11 @@ gtk_buildable_set_name (GtkBuildable *buildable,
* gtk_buildable_get_name:
* @buildable: a #GtkBuildable
*
*
* Returns the buildable name. #GtkBuilder sets the name based on the
* the <link linkend="BUILDER-UI">GtkBuilder UI definition</link> used
* to construct the @buildable.
*
* #GtkWidget implements this to map the buildable name to the widget name
* Gets the name of the @buildable object.
*
* #GtkBuilder sets the name based on the the
* <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
* used to construct the @buildable.
*
* Returns: the name set with gtk_buildable_set_name()
*
@ -109,13 +105,9 @@ gtk_buildable_get_name (GtkBuildable *buildable)
* @child: child to add
* @type: kind of child or %NULL
*
* Add a child to a buildable. type is an optional string
* Adds a child to @buildable. @type is an optional string
* describing how the child should be added.
*
* #GtkContainer implements this to be able to add a child widget
* to the container. #GtkNotebook uses the @type to distinguish between
* page labels (@type = "page-label") and normal children.
*
* Since: 2.12
**/
void
@ -142,14 +134,7 @@ gtk_buildable_add_child (GtkBuildable *buildable,
* @name: name of property
* @value: value of property
*
* Sets the property name @name to @value on the buildable object @buildable
* which is created by the @builder.
*
* This is optional to implement and is normally not needed.
* g_object_set_property() is used as a fallback.
*
* #GtkWindow implements this to delay showing (::visible) itself until
* the whole interface is fully created.
* Sets the property name @name to @value on the @buildable object.
*
* Since: 2.12
**/
@ -178,12 +163,11 @@ gtk_buildable_set_buildable_property (GtkBuildable *buildable,
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
*
* Finish the parsing of a <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
* snippet. Note that this will be called once for each time gtk_builder_add_from_file or
* gtk_builder_add_from_string is called on a builder.
*
* #GtkWindow implements this to delay showing (::visible) itself until
* the whole interface is fully created.
* Called when the builder finishes the parsing of a
* <link linkend="BUILDER-UI">GtkBuilder UI definition</link>.
* Note that this will be called once for each time
* gtk_builder_add_from_file() or gtk_builder_add_from_string()
* is called on a builder.
*
* Since: 2.12
**/
@ -202,19 +186,17 @@ gtk_buildable_parser_finished (GtkBuildable *buildable,
}
/**
* gtk_buildable_construct_child
* gtk_buildable_construct_child:
* @buildable: A #GtkBuildable
* @builder: #GtkBuilder used to construct this object
* @name: name of child to construct
*
* Construct a child of @buildable with the name @name.
* Constructs a child of @buildable with the name @name.
*
* #GtkUIManager implements this to reference to a widget created in a
* &lt;ui&gt; tag which is outside of the normal
* <link linkend="BUILDER-UI">GtkBuilder UI definition</link>
* hierarchy.
* #GtkBuilder calls this function if a "constructor" has been
* specified in the UI definition.
*
* Returns: the child with name @name
* Returns: the constructed child
*
* Since: 2.12
**/
@ -236,27 +218,17 @@ gtk_buildable_construct_child (GtkBuildable *buildable,
}
/**
* gtk_buildable_custom_tag_start
* gtk_buildable_custom_tag_start:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder used to construct this object
* @child: child object or %NULL for non-child tags
* @tagname: name of tag
* @parser: a #GMarkupParser structure
* @data: user data that will be passed in to parser functions
* @parser: a #GMarkupParser structure to fill in
* @data: return location for user data that will be passed in
* to parser functions
*
* This is called when an unknown tag under &lt;child&gt; tag is found.
* This is called for each unknown element under &lt;child&gt;.
*
* Called when an unknown tag is present under a &lt;child&gt; tag.
* If the buildable implementation wishes to handle the tag it should
* return %TRUE and fill in the @parser structure. Remember to either
* implement custom_tag_end or custom_tag_finish to free
* the user data allocated here.
*
* #GtkWidget implements this and parsers all &lt;accelerator&gt; tags to
* keyboard accelerators.
* #GtkContainer implements this to map properties defined under
* &lt;packing&gt; tag to child properties.
*
* Returns: %TRUE if a object has a custom implementation, %FALSE
* if it doesn't.
*
@ -284,15 +256,15 @@ gtk_buildable_custom_tag_start (GtkBuildable *buildable,
}
/**
* gtk_buildable_custom_tag_end
* gtk_buildable_custom_tag_end:
* @buildable: A #GtkBuildable
* @builder: #GtkBuilder used to construct this object
* @child: child object or %NULL for non-child tags
* @tagname: name of tag
* @data: user data that will be passed in to parser functions
*
* This is called for each custom tag handled by the buildable.
* It will be called when the end of the tag is reached.
* This is called at the end of each custom element handled by
* the buildable.
*
* Since: 2.12
**/
@ -345,7 +317,7 @@ gtk_buildable_custom_finished (GtkBuildable *buildable,
}
/**
* gtk_buildable_get_internal_child
* gtk_buildable_get_internal_child:
* @buildable: a #GtkBuildable
* @builder: a #GtkBuilder
* @childname: name of child

175
gtk/gtkbuilder.c
View File

@ -47,9 +47,10 @@ static void gtk_builder_get_property (GObject *object,
guint prop_id,
GValue *value,
GParamSpec *pspec);
static GType gtk_builder_real_get_type_from_name (GtkBuilder *builder,
const char *type_name);
static gint _gtk_builder_enum_from_string (GType type, const char *string);
static GType gtk_builder_real_get_type_from_name (GtkBuilder *builder,
const gchar *type_name);
static gint _gtk_builder_enum_from_string (GType type,
const gchar *string);
enum {
@ -82,6 +83,16 @@ gtk_builder_class_init (GtkBuilderClass *klass)
klass->get_type_from_name = gtk_builder_real_get_type_from_name;
/**
* GtkBuilder:translation-domain:
*
* The translation domain used when translating property values that
* have been marked as translatable in interface descriptions.
* If the translation domain is %NULL, #GtkBuilder uses gettext(),
* otherwise dgettext().
*
* Since: 2.12
*/
g_object_class_install_property (gobject_class,
PROP_TRANSLATION_DOMAIN,
g_param_spec_string ("translation-domain",
@ -218,7 +229,8 @@ _gtk_builder_resolve_type_lazily (const gchar *name)
*/
static GType
gtk_builder_real_get_type_from_name (GtkBuilder *builder, const char *type_name)
gtk_builder_real_get_type_from_name (GtkBuilder *builder,
const gchar *type_name)
{
GType gtype;
@ -280,8 +292,8 @@ gtk_builder_get_parameters (GtkBuilder *builder,
object = gtk_builder_get_object (builder, prop->data);
if (!object)
{
g_warning ("failed to get constuct only property %s of %s "
"with value `%s'",
g_warning ("Failed to get constuct only property "
"%s of %s with value `%s'",
prop->name, object_name, prop->data);
continue;
}
@ -308,7 +320,7 @@ gtk_builder_get_parameters (GtkBuilder *builder,
else if (!gtk_builder_value_from_string (builder, pspec,
prop->data, &parameter.value, &error))
{
g_warning ("failed to set property %s.%s to %s: %s",
g_warning ("Failed to set property %s.%s to %s: %s",
g_type_name (object_type), prop->name, prop->data,
error->message);
g_error_free (error);
@ -590,7 +602,7 @@ _gtk_builder_finish (GtkBuilder *builder)
*
* Creates a new builder object.
*
* Return value: a new builder object.
* Return value: a new #GtkBuilder object
*
* Since: 2.12
**/
@ -604,10 +616,10 @@ gtk_builder_new (void)
* gtk_builder_add_from_file:
* @builder: a #GtkBuilder
* @filename: the name of the file to parse
* @error: return location for an error
* @error: return location for an error, or %NULL
*
* Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link> and
* merges it with the current contents of @builder.
* Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder
* UI definition</link> and merges it with the current contents of @builder.
*
* Returns: A positive value on success, 0 if an error occurred
*
@ -618,7 +630,7 @@ gtk_builder_add_from_file (GtkBuilder *builder,
const gchar *filename,
GError **error)
{
char *buffer;
gchar *buffer;
gsize length;
GError *tmp_error;
@ -653,10 +665,10 @@ gtk_builder_add_from_file (GtkBuilder *builder,
* @builder: a #GtkBuilder
* @buffer: the string to parse
* @length: the length of @buffer (may be -1 if @buffer is nul-terminated)
* @error: return location for an error
* @error: return location for an error, or %NULL
*
* Parses a file containing a <link linkend="BUILDER-UI">GtkBuilder UI definition</link> and
* merges it with the current contents of @builder.
* Parses a string containing a <link linkend="BUILDER-UI">GtkBuilder
* UI definition</link> and merges it with the current contents of @builder.
*
* Returns: A positive value on success, 0 if an error occurred
*
@ -692,10 +704,11 @@ gtk_builder_add_from_string (GtkBuilder *builder,
* @builder: a #GtkBuilder
* @name: name of object to get
*
* Gets the object named @name.
* Gets the object named @name. Note that this function does not
* increment the reference count of the returned object.
*
* Return value: the object named @name or %NULL if it could not be
* found in the object tree
* found in the object tree.
*
* Since: 2.12
**/
@ -710,9 +723,9 @@ gtk_builder_get_object (GtkBuilder *builder,
}
static void
object_add_to_list (gchar *object_id,
GObject *object,
GSList **list)
object_add_to_list (gchar *object_id,
GObject *object,
GSList **list)
{
*list = g_slist_prepend (*list, object);
}
@ -721,10 +734,13 @@ object_add_to_list (gchar *object_id,
* gtk_builder_get_objects:
* @builder: a #GtkBuilder
*
* Gets all objects that have been constructed by @builder.
* Gets all objects that have been constructed by @builder. Note that
* this function does not increment the reference counts of the returned
* objects.
*
* Return value: a newly-allocated #GSList containing all the objects
* constructed by the #GtkBuilder instance
* constructed by the #GtkBuilder instance. It should be freed by
* g_slist_free()
*
* Since: 2.12
**/
@ -745,10 +761,8 @@ gtk_builder_get_objects (GtkBuilder *builder)
* @builder: a #GtkBuilder
* @domain: the translation domain or %NULL
*
* Sets the translation domain and uses dgettext() for translating the
* property values marked as translatable from an interface description.
* You can also pass in %NULL to this method to use gettext() instead of
* dgettext().
* Sets the translation domain of @builder.
* See #GtkBuilder:translation-domain.
*
* Since: 2.12
**/
@ -771,7 +785,7 @@ gtk_builder_set_translation_domain (GtkBuilder *builder,
* gtk_builder_get_translation_domain:
* @builder: a #GtkBuilder
*
* Gets the translation domain.
* Gets the translation domain of @builder.
*
* Return value: the translation domain. This string is owned
* by the builder object and must not be modified or freed.
@ -805,7 +819,7 @@ gtk_builder_connect_signals_default (GtkBuilder *builder,
if (!g_module_symbol (args->module, handler_name, (gpointer)&func))
{
g_warning ("could not find signal handler '%s'", handler_name);
g_warning ("Could not find signal handler '%s'", handler_name);
return;
}
@ -822,8 +836,8 @@ gtk_builder_connect_signals_default (GtkBuilder *builder,
* @user_data: a pointer to a structure sent in as user data to all signals
*
* This method is a simpler variation of gtk_builder_connect_signals_full().
* It uses #GModule's introspective features (by opening the module %NULL) to
* look at the application's symbol table. From here it tries to match
* It uses #GModule's introspective features (by opening the module %NULL)
* to look at the application's symbol table. From here it tries to match
* the signal handler names given in the interface description with
* symbols in the application and connects the signals.
*
@ -841,7 +855,7 @@ gtk_builder_connect_signals (GtkBuilder *builder,
g_return_if_fail (GTK_IS_BUILDER (builder));
if (!g_module_supported ())
g_error ("gtk_builder_connect_signals requires working GModule");
g_error ("gtk_builder_connect_signals() requires working GModule");
args = g_slice_new0 (connect_args);
args->module = g_module_open (NULL, G_MODULE_BIND_LAZY);
@ -858,10 +872,10 @@ gtk_builder_connect_signals (GtkBuilder *builder,
/**
* GtkBuilderConnectFunc:
* @builder: a #GtkBuilder
* @object: a GObject subclass to connect a signal to
* @object: object to connect a signal to
* @signal_name: name of the signal
* @handler_name: name of the handler
* @connect_object: GObject, if non-%NULL, use g_signal_connect_object.
* @connect_object: a #GObject, if non-%NULL, use g_signal_connect_object()
* @flags: #GConnectFlags to use
* @user_data: user data
*
@ -877,12 +891,12 @@ gtk_builder_connect_signals (GtkBuilder *builder,
/**
* gtk_builder_connect_signals_full:
* @builder: a #GtkBuilder
* @func: the function used to connect the signals.
* @user_data: arbitrary data that will be passed to the connection function.
* @func: the function used to connect the signals
* @user_data: arbitrary data that will be passed to the connection function
*
* This function can be thought of the interpreted language binding
* version of gtk_builder_signal_autoconnect(), except that it does not
* require gmodule to function correctly.
* version of gtk_builder_connect_signals(), except that it does not
* require GModule to function correctly.
*
* Since: 2.12
*/
@ -920,7 +934,7 @@ gtk_builder_connect_signals_full (GtkBuilder *builder,
connect_object = g_hash_table_lookup (builder->priv->objects,
signal->connect_object_name);
if (!connect_object)
g_warning ("could not lookup object %s on signal %s of object %s",
g_warning ("Could not lookup object %s on signal %s of object %s",
signal->connect_object_name, signal->name,
signal->object_name);
}
@ -935,23 +949,23 @@ gtk_builder_connect_signals_full (GtkBuilder *builder,
}
/**
* gtk_builder_value_from_string
* gtk_builder_value_from_string:
* @builder: a #GtkBuilder
* @pspec: the GParamSpec for the property
* @string: the string representation of the value.
* @value: the GValue to store the result in.
* @error: return location for an error
* @pspec: the #GParamSpec for the property
* @string: the string representation of the value
* @value: the #GValue to store the result in
* @error: return location for an error, or %NULL
*
* This function demarshals a value from a string. This function
* This function demarshals a value from a string. This function
* calls g_value_init() on the @value argument, so it need not be
* initialised beforehand.
*
* This function can handle char, uchar, boolean, int, uint, long,
* ulong, enum, flags, float, double, string, GdkColor and
* GtkAdjustment type values. Support for GtkWidget type values is
* ulong, enum, flags, float, double, string, #GdkColor and
* #GtkAdjustment type values. Support for #GtkWidget type values is
* still to come.
*
* Returns: %TRUE on success.
* Returns: %TRUE on success
*
* Since: 2.12
*/
@ -982,16 +996,19 @@ gtk_builder_value_from_string (GtkBuilder *builder,
}
/**
* gtk_builder_value_from_string_type
* gtk_builder_value_from_string_type:
* @builder: a #GtkBuilder
* @type: the GType of the value
* @string: the string representation of the value.
* @value: the GValue to store the result in.
* @error: return location for an error
* @type: the #GType of the value
* @string: the string representation of the value
* @value: the #GValue to store the result in
* @error: return location for an error, or %NULL
*
* Like gtk_builder_value_from_string(), but takes a #GType instead of #GParamSpec.
* Like gtk_builder_value_from_string(), this function demarshals
* a value from a string, but takes a #GType instead of #GParamSpec.
* This function calls g_value_init() on the @value argument, so it
* need not be initialised beforehand.
*
* Returns: %TRUE on success.
* Returns: %TRUE on success
*
* Since: 2.12
*/
@ -1041,7 +1058,7 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"could not parse int `%s'",
"Could not parse boolean `%s'",
string);
ret = FALSE;
break;
@ -1064,7 +1081,7 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"could not parse long `%s'",
"Could not parse integer `%s'",
string);
ret = FALSE;
break;
@ -1087,7 +1104,7 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"could not parse ulong `%s'",
"Could not parse unsigned integer `%s'",
string);
ret = FALSE;
break;
@ -1107,7 +1124,7 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
case G_TYPE_FLOAT:
case G_TYPE_DOUBLE:
{
double d;
gdouble d;
gchar *endptr;
errno = 0;
d = g_ascii_strtod (string, &endptr);
@ -1116,7 +1133,7 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"could not parse double `%s'",
"Could not parse double `%s'",
string);
ret = FALSE;
break;
@ -1144,14 +1161,14 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"could not parse color `%s'",
"Could not parse color `%s'",
string);
ret = FALSE;
}
}
else if (G_VALUE_HOLDS (value, G_TYPE_STRV))
{
char **vector = g_strsplit (string, "\n", 0);
gchar **vector = g_strsplit (string, "\n", 0);
g_value_take_boxed (value, vector);
}
else
@ -1186,13 +1203,13 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
}
else
#endif
ret = FALSE;
ret = FALSE;
break;
default:
g_set_error (error,
GTK_BUILDER_ERROR,
GTK_BUILDER_ERROR_INVALID_VALUE,
"unsupported GType `%s'",
"Unsupported GType `%s'",
g_type_name (type));
ret = FALSE;
break;
@ -1202,7 +1219,8 @@ gtk_builder_value_from_string_type (GtkBuilder *builder,
}
static gint
_gtk_builder_enum_from_string (GType type, const char *string)
_gtk_builder_enum_from_string (GType type,
const gchar *string)
{
GEnumClass *eclass;
GEnumValue *ev;
@ -1230,14 +1248,15 @@ _gtk_builder_enum_from_string (GType type, const char *string)
}
guint
_gtk_builder_flags_from_string (GType type, const char *string)
_gtk_builder_flags_from_string (GType type,
const gchar *string)
{
GFlagsClass *fclass;
gchar *endptr, *prevptr;
guint i, j, ret;
char *flagstr;
gchar *flagstr;
GFlagsValue *fv;
const char *flag;
const gchar *flag;
gunichar ch;
gboolean eos;
@ -1314,18 +1333,19 @@ _gtk_builder_flags_from_string (GType type, const char *string)
/**
* gtk_builder_get_type_from_name:
* @builder: a #GtkBuilder
* @type_name: Type name to lookup
* @type_name: type name to lookup
*
* This method is used to lookup a type. It can be implemented in a
* subclass to override the #GType of an object created by the builder.
* Looks up a type by name, using the virtual function that
* #GtkBuilder has for that purpose.
*
* Returns: the #GType found for @type_name or #G_TYPE_INVALID if no
* type was found
* Returns: the #GType found for @type_name or #G_TYPE_INVALID
* if no type was found
*
* Since 2.12
*/
GType
gtk_builder_get_type_from_name (GtkBuilder *builder, const gchar *type_name)
gtk_builder_get_type_from_name (GtkBuilder *builder,
const gchar *type_name)
{
g_return_val_if_fail (GTK_IS_BUILDER (builder), G_TYPE_INVALID);
g_return_val_if_fail (type_name != NULL, G_TYPE_INVALID);
@ -1333,15 +1353,6 @@ gtk_builder_get_type_from_name (GtkBuilder *builder, const gchar *type_name)
return GTK_BUILDER_GET_CLASS (builder)->get_type_from_name (builder, type_name);
}
/**
* gtk_builder_error_quark:
*
* Registers an error quark for #GtkBuilder if necessary.
*
* Return value: The error quark used for #GtkBuilder errors.
*
* Since: 2.12
**/
GQuark
gtk_builder_error_quark (void)
{