doc/gtk/defuns-gtkuimanager.xml.texi

@c %start of fragment

@deftp Class <gtk-ui-manager>
Derives from @code{<gtk-buildable>}, @code{<gobject>}.

This class defines the following slots:

@table @code
@item add-tearoffs
Whether tearoff menu items should be added to menus

@item ui
An XML string describing the merged UI

@end table

@end deftp

@defop Signal <gtk-ui-manager> connect-proxy  (arg0@tie{}@code{<gtk-action>}) (arg1@tie{}@code{<gtk-widget>})
The connect_proxy signal is emitted after connecting a proxy to an action in the
group.

This is intended for simple customizations for which a custom action class would
be too clumsy, e.g. showing tooltips for menuitems in the statusbar.

Since 2.4

@end defop

@defop Signal <gtk-ui-manager> disconnect-proxy  (arg0@tie{}@code{<gtk-action>}) (arg1@tie{}@code{<gtk-widget>})
The disconnect_proxy signal is emitted after disconnecting a proxy from an
action in the group.

Since 2.4

@end defop

@defop Signal <gtk-ui-manager> pre-activate  (arg0@tie{}@code{<gtk-action>})
The pre_activate signal is emitted just before the @var{action} is activated.

This is intended for applications to get notification just before any action is
activated.

Since 2.4

@end defop

@defop Signal <gtk-ui-manager> post-activate  (arg0@tie{}@code{<gtk-action>})
The post_activate signal is emitted just after the @var{action} is activated.

This is intended for applications to get notification just after any action is
activated.

Since 2.4

@end defop

@defop Signal <gtk-ui-manager> add-widget  (arg0@tie{}@code{<gtk-widget>})
The add_widget signal is emitted for each generated menubar and toolbar. It is
not emitted for generated popup menus, which can be obtained by
@code{gtk-ui-manager-get-widget}.

Since 2.4

@end defop

@defop Signal <gtk-ui-manager> actions-changed
The "actions-changed" signal is emitted whenever the set of actions changes.

Since 2.4

@end defop

@deffn Function gtk-ui-manager-new  @result{}@tie{} (ret@tie{}@code{<gtk-ui-manager>})
Creates a new ui manager object.

@table @var
@item ret
a new ui manager object.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-set-add-tearoffs  (self@tie{}@code{<gtk-ui-manager>}) (add_tearoffs@tie{}@code{bool})
@deffnx Method set-add-tearoffs
Sets the "add_tearoffs" property, which controls whether menus generated by this
@code{<gtk-ui-manager>} will have tearoff menu items.

Note that this only affects regular menus. Generated popup menus never have
tearoff menu items.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item add-tearoffs
whether tearoff menu items are added

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-add-tearoffs  (self@tie{}@code{<gtk-ui-manager>}) @result{}@tie{} (ret@tie{}@code{bool})
@deffnx Method get-add-tearoffs
Returns whether menus generated by this @code{<gtk-ui-manager>} will have
tearoff menu items.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item ret
whether tearoff menu items are added

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-insert-action-group  (self@tie{}@code{<gtk-ui-manager>}) (action_group@tie{}@code{<gtk-action-group>}) (pos@tie{}@code{int})
@deffnx Method insert-action-group
Inserts an action group into the list of action groups associated with
@var{self}. Actions in earlier groups hide actions with the same name in later
groups.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item action-group
the action group to be inserted

@item pos
the position at which the group will be inserted.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-remove-action-group  (self@tie{}@code{<gtk-ui-manager>}) (action_group@tie{}@code{<gtk-action-group>})
@deffnx Method remove-action-group
Removes an action group from the list of action groups associated with
@var{self}.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item action-group
the action group to be removed

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-action-groups  (self@tie{}@code{<gtk-ui-manager>}) @result{}@tie{} (ret@tie{}@code{glist-of})
@deffnx Method get-action-groups
Returns the list of action groups associated with @var{self}.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item ret
a @code{<g-list>} of action groups. The list is owned by GTK+ and should not be
modified.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-accel-group  (self@tie{}@code{<gtk-ui-manager>}) @result{}@tie{} (ret@tie{}@code{<gtk-accel-group>})
@deffnx Method get-accel-group
Returns the @code{<gtk-accel-group>} associated with @var{self}.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item ret
the @code{<gtk-accel-group>}.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-widget  (self@tie{}@code{<gtk-ui-manager>}) (path@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{<gtk-widget>})
@deffnx Method get-widget
Looks up a widget by following a path. The path consists of the names specified
in the XML description of the UI. separated by '/'. Elements which don't have a
name or action attribute in the XML (e.g. <popup>) can be addressed by their XML
element name (e.g. "popup"). The root element ("/ui") can be omitted in the
path.

Note that the widget found by following a path that ends in a <menu> element is
the menuitem to which the menu is attached, not the menu itself.

Also note that the widgets constructed by a ui manager are not tied to the
lifecycle of the ui manager. If you add the widgets returned by this function to
some container or explicitly ref them, they will survive the destruction of the
ui manager.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item path
a path

@item ret
the widget found by following the path, or @samp{@code{#f}} if no widget was
found.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-toplevels  (self@tie{}@code{<gtk-ui-manager>}) (types@tie{}@code{<gtk-ui-manager-item-type>}) @result{}@tie{} (ret@tie{}@code{gslist-of})
@deffnx Method get-toplevels
Obtains a list of all toplevel widgets of the requested types.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item types
specifies the types of toplevel widgets to include. Allowed types are
@code{<gtk-ui-manager-menubar>}, @code{<gtk-ui-manager-toolbar>} and
@code{<gtk-ui-manager-popup>}.

@item ret
a newly-allocated of all toplevel widgets of the requested types.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-action  (self@tie{}@code{<gtk-ui-manager>}) (path@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{<gtk-action>})
@deffnx Method get-action
Looks up an action by following a path. See @code{gtk-ui-manager-get-widget} for
more information about paths.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item path
a path

@item ret
the action whose proxy widget is found by following the path, or
@samp{@code{#f}} if no widget was found.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-add-ui-from-string  (self@tie{}@code{<gtk-ui-manager>}) (buffer@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
@deffnx Method add-ui-from-string
Parses a string containing a UI definition and merges it with the current
contents of @var{self}. An enclosing <ui> element is added if it is missing.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item buffer
the string to parse

@item length
the length of @var{buffer} (may be -1 if @var{buffer} is nul-terminated)

@item error
return location for an error

@item ret
The merge id for the merged UI. The merge id can be used to unmerge the UI with
@code{gtk-ui-manager-remove-ui}. If an error occurred, the return value is 0.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-add-ui-from-file  (self@tie{}@code{<gtk-ui-manager>}) (filename@tie{}@code{mchars}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
@deffnx Method add-ui-from-file
Parses a file containing a UI definition and merges it with the current contents
of @var{self}.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item filename
the name of the file to parse

@item error
return location for an error

@item ret
The merge id for the merged UI. The merge id can be used to unmerge the UI with
@code{gtk-ui-manager-remove-ui}. If an error occurred, the return value is 0.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-new-merge-id  (self@tie{}@code{<gtk-ui-manager>}) @result{}@tie{} (ret@tie{}@code{unsigned-int})
@deffnx Method new-merge-id
Returns an unused merge id, suitable for use with @code{gtk-ui-manager-add-ui}.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item ret
an unused merge id.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-add-ui  (self@tie{}@code{<gtk-ui-manager>}) (merge_id@tie{}@code{unsigned-int}) (path@tie{}@code{mchars}) (name@tie{}@code{mchars}) (action@tie{}@code{mchars}) (type@tie{}@code{<gtk-ui-manager-item-type>}) (top@tie{}@code{bool})
@deffnx Method add-ui
Adds a UI element to the current contents of @var{self}.

If @var{type} is @samp{GTK_UI_MANAGER_AUTO}, GTK+ inserts a menuitem, toolitem
or separator if such an element can be inserted at the place determined by
@var{path}. Otherwise @var{type} must indicate an element that can be inserted
at the place determined by @var{path}.

If @var{path} points to a menuitem or toolitem, the new element will be inserted
before or after this item, depending on @var{top}.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item merge-id
the merge id for the merged UI, see @code{gtk-ui-manager-new-merge-id}

@item path
a path

@item name
the name for the added UI element

@item action
the name of the action to be proxied, or @samp{@code{#f}} to add a separator

@item type
the type of UI element to add.

@item top
if @samp{@code{#t}}, the UI element is added before its siblings, otherwise it
is added after its siblings.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-remove-ui  (self@tie{}@code{<gtk-ui-manager>}) (merge_id@tie{}@code{unsigned-int})
@deffnx Method remove-ui
Unmerges the part of @var{self}s content identified by @var{merge-id}.

@table @var
@item self
a @code{<gtk-ui-manager>} object

@item merge-id
a merge id as returned by @code{gtk-ui-manager-add-ui-from-string}

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-get-ui  (self@tie{}@code{<gtk-ui-manager>}) @result{}@tie{} (ret@tie{}@code{mchars})
@deffnx Method get-ui
Creates a UI definition of the merged UI.

@table @var
@item self
a @code{<gtk-ui-manager>}

@item ret
A newly allocated string containing an XML representation of the merged UI.

@end table

Since 2.4

@end deffn

@deffn Function gtk-ui-manager-ensure-update  (self@tie{}@code{<gtk-ui-manager>})
@deffnx Method ensure-update
Makes sure that all pending updates to the UI have been completed.

This may occasionally be necessary, since @code{<gtk-ui-manager>} updates the UI
in an idle function. A typical example where this function is useful is to
enforce that the menubar and toolbar have been added to the main window before
showing it:

@example

gtk_container_add (GTK_CONTAINER (window), vbox);
g_signal_connect (merge, "add_widget",
                  G_CALLBACK (add_widget), vbox);
gtk_ui_manager_add_ui_from_file (merge, "my-menus");
gtk_ui_manager_add_ui_from_file (merge, "my-toolbars");
gtk_ui_manager_ensure_update (merge);
gtk_widget_show (window);
@end example

@table @var
@item self
a @code{<gtk-ui-manager>}

@end table

Since 2.4

@end deffn


@c %end of fragment