~ubuntu-branches/ubuntu/precise/gtkmm3.0/precise

« back to all changes in this revision

Viewing changes to gtk/gtkmm/uimanager.h

  • Committer: Bazaar Package Importer
  • Author(s): Michael Biebl
  • Date: 2011-06-17 00:12:44 UTC
  • Revision ID: james.westby@ubuntu.com-20110617001244-9hl5an15hiaaahi6
Tags: upstream-3.0.1
ImportĀ upstreamĀ versionĀ 3.0.1

Show diffs side-by-side

added added

removed removed

Lines of Context:
 
1
// -*- c++ -*-
 
2
// Generated by gtkmmproc -- DO NOT MODIFY!
 
3
#ifndef _GTKMM_UIMANAGER_H
 
4
#define _GTKMM_UIMANAGER_H
 
5
 
 
6
 
 
7
#include <glibmm.h>
 
8
 
 
9
/* $Id: uimanager.hg,v 1.17 2006/05/11 11:40:24 murrayc Exp $ */
 
10
 
 
11
/* Copyright (C) 2003 The gtkmm Development Team
 
12
 *
 
13
 * This library is free software; you can redistribute it and/or
 
14
 * modify it under the terms of the GNU Lesser General Public
 
15
 * License as published by the Free Software Foundation; either
 
16
 * version 2.1 of the License, or (at your option) any later version.
 
17
 *
 
18
 * This library is distributed in the hope that it will be useful,
 
19
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 
20
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 
21
 * Lesser General Public License for more details.
 
22
 *
 
23
 * You should have received a copy of the GNU Lesser General Public
 
24
 * License along with this library; if not, write to the Free
 
25
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 
26
 */
 
27
 
 
28
#include <vector>
 
29
 
 
30
#include <gtkmm/widget.h>
 
31
#include <gtkmm/action.h>
 
32
#include <gtkmm/actiongroup.h>
 
33
 
 
34
 
 
35
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
36
typedef struct _GtkUIManager GtkUIManager;
 
37
typedef struct _GtkUIManagerClass GtkUIManagerClass;
 
38
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
39
 
 
40
 
 
41
namespace Gtk
 
42
{ class UIManager_Class; } // namespace Gtk
 
43
namespace Gtk
 
44
{
 
45
        
 
46
/** @addtogroup gtkmmEnums gtkmm Enums and Flags */
 
47
 
 
48
/**
 
49
 * @ingroup gtkmmEnums
 
50
 * @par Bitwise operators:
 
51
 * <tt>%UIManagerItemType operator|(UIManagerItemType, UIManagerItemType)</tt><br>
 
52
 * <tt>%UIManagerItemType operator&(UIManagerItemType, UIManagerItemType)</tt><br>
 
53
 * <tt>%UIManagerItemType operator^(UIManagerItemType, UIManagerItemType)</tt><br>
 
54
 * <tt>%UIManagerItemType operator~(UIManagerItemType)</tt><br>
 
55
 * <tt>%UIManagerItemType& operator|=(UIManagerItemType&, UIManagerItemType)</tt><br>
 
56
 * <tt>%UIManagerItemType& operator&=(UIManagerItemType&, UIManagerItemType)</tt><br>
 
57
 * <tt>%UIManagerItemType& operator^=(UIManagerItemType&, UIManagerItemType)</tt><br>
 
58
 */
 
59
enum UIManagerItemType
 
60
{
 
61
  UI_MANAGER_AUTO = 0x0,
 
62
  UI_MANAGER_MENUBAR = 1 << 0,
 
63
  UI_MANAGER_MENU = 1 << 1,
 
64
  UI_MANAGER_TOOLBAR = 1 << 2,
 
65
  UI_MANAGER_PLACEHOLDER = 1 << 3,
 
66
  UI_MANAGER_POPUP = 1 << 4,
 
67
  UI_MANAGER_MENUITEM = 1 << 5,
 
68
  UI_MANAGER_TOOLITEM = 1 << 6,
 
69
  UI_MANAGER_SEPARATOR = 1 << 7,
 
70
  UI_MANAGER_ACCELERATOR = 1 << 8,
 
71
  UI_MANAGER_POPUP_WITH_ACCELS = 1 << 9
 
72
};
 
73
 
 
74
/** @ingroup gtkmmEnums */
 
75
inline UIManagerItemType operator|(UIManagerItemType lhs, UIManagerItemType rhs)
 
76
  { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
 
77
 
 
78
/** @ingroup gtkmmEnums */
 
79
inline UIManagerItemType operator&(UIManagerItemType lhs, UIManagerItemType rhs)
 
80
  { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
 
81
 
 
82
/** @ingroup gtkmmEnums */
 
83
inline UIManagerItemType operator^(UIManagerItemType lhs, UIManagerItemType rhs)
 
84
  { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
 
85
 
 
86
/** @ingroup gtkmmEnums */
 
87
inline UIManagerItemType operator~(UIManagerItemType flags)
 
88
  { return static_cast<UIManagerItemType>(~static_cast<unsigned>(flags)); }
 
89
 
 
90
/** @ingroup gtkmmEnums */
 
91
inline UIManagerItemType& operator|=(UIManagerItemType& lhs, UIManagerItemType rhs)
 
92
  { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
 
93
 
 
94
/** @ingroup gtkmmEnums */
 
95
inline UIManagerItemType& operator&=(UIManagerItemType& lhs, UIManagerItemType rhs)
 
96
  { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
 
97
 
 
98
/** @ingroup gtkmmEnums */
 
99
inline UIManagerItemType& operator^=(UIManagerItemType& lhs, UIManagerItemType rhs)
 
100
  { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
 
101
 
 
102
} // namespace Gtk
 
103
 
 
104
 
 
105
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
106
namespace Glib
 
107
{
 
108
 
 
109
template <>
 
110
class Value<Gtk::UIManagerItemType> : public Glib::Value_Flags<Gtk::UIManagerItemType>
 
111
{
 
112
public:
 
113
  static GType value_type() G_GNUC_CONST;
 
114
};
 
115
 
 
116
} // namespace Glib
 
117
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
118
 
 
119
 
 
120
namespace Gtk
 
121
{
 
122
 
 
123
 
 
124
/** Constructing menus and toolbars from an XML description.
 
125
 *
 
126
 * A Gtk::UIManager constructs a user interface (menus and toolbars) from one or more UI definitions,
 
127
 * which reference actions from one or more action groups.
 
128
 *
 
129
 * \par UI Definitions
 
130
 *
 
131
 * The UI definitions are specified in an XML format which can be roughly described by the following DTD.
 
132
 * \code
 
133
 * <!ELEMENT ui          (menubar|toolbar|popup|accelerator)* >
 
134
 * <!ELEMENT menubar     (menuitem|separator|placeholder|menu)* >
 
135
 * <!ELEMENT menu        (menuitem|separator|placeholder|menu)* >
 
136
 * <!ELEMENT popup       (menuitem|separator|placeholder|menu)* >
 
137
 * <!ELEMENT toolbar     (toolitem|separator|placeholder)* >
 
138
 * <!ELEMENT placeholder (menuitem|toolitem|separator|placeholder|menu)* >
 
139
 * <!ELEMENT menuitem     EMPTY >
 
140
 * <!ELEMENT toolitem     (menu?) >
 
141
 * <!ELEMENT separator    EMPTY >
 
142
 * <!ELEMENT accelerator  EMPTY >
 
143
 * <!ATTLIST menubar      name                  #IMPLIED 
 
144
 *                      action                #IMPLIED >
 
145
 * <!ATTLIST toolbar      name                  #IMPLIED 
 
146
 *                      action                #IMPLIED >
 
147
 * <!ATTLIST popup        name                  #IMPLIED 
 
148
 *                      action                #IMPLIED >
 
149
 * <!ATTLIST placeholder  name                  #IMPLIED
 
150
 *                       action                #IMPLIED >
 
151
 * <!ATTLIST separator    name                  #IMPLIED
 
152
 *                       action                #IMPLIED
 
153
 *                       expand   (true|false) #IMPLIED >
 
154
 * <!ATTLIST menu         name                  #IMPLIED
 
155
 *                       action                #REQUIRED
 
156
 *                       position (top|bot)    #IMPLIED >
 
157
 * <!ATTLIST menuitem     name                  #IMPLIED
 
158
 *                      action                #REQUIRED
 
159
 *                      position (top|bot)    #IMPLIED >
 
160
 * <!ATTLIST toolitem     name                  #IMPLIED
 
161
 *                      action                #REQUIRED
 
162
 *                      position (top|bot)    #IMPLIED >
 
163
 * <!ATTLIST accelerator  name                  #IMPLIED
 
164
 *                       action                #REQUIRED >
 
165
 * \endcode
 
166
 *
 
167
 * There are some additional restrictions beyond those specified in the DTD, e.g. 
 
168
 * every toolitem must have a toolbar in its anchestry and every menuitem must have a +
 
169
 * menubar or popup in its anchestry. Since a GMarkup parser is used to parse the UI description, 
 
170
 * it must not only be valid XML, but valid GMarkup.
 
171
 *
 
172
 * If a name is not specified, it defaults to the action. If an action is not specified either,
 
173
 * the element name is used. The name and action attributes must not contain '/' characters after 
 
174
 * parsing (since that would mess up path lookup) and must be usable as XML attributes when 
 
175
 * enclosed in doublequotes, thus they must not '"' characters or references to the &quot; entity.
 
176
 *
 
177
 * \par Example: UI Definition
 
178
 * \code
 
179
 * <ui>
 
180
 * <menubar>
 
181
 *   <menu name="FileMenu" action="FileMenuAction">
 
182
 *     <menuitem name="New" action="New2Action" />
 
183
 *     <placeholder name="FileMenuAdditions" />
 
184
 *   </menu>
 
185
 *   <menu name="JustifyMenu" action="JustifyMenuAction">
 
186
 *     <menuitem name="Left" action="justify-left"/>
 
187
 *     <menuitem name="Centre" action="justify-center"/>
 
188
 *     <menuitem name="Right" action="justify-right"/>
 
189
 *     <menuitem name="Fill" action="justify-fill"/>
 
190
 *   </menu>
 
191
 * </menubar>
 
192
 * <toolbar action="toolbar1">
 
193
 *   <placeholder name="JustifyToolItems">
 
194
 *     <separator/>
 
195
 *     <toolitem name="Left" action="justify-left"/>
 
196
 *     <toolitem name="Centre" action="justify-center"/>
 
197
 *     <toolitem name="Right" action="justify-right"/>
 
198
 *     <toolitem name="Fill" action="justify-fill"/>
 
199
 *     <separator/>
 
200
 *   </placeholder>
 
201
 * </toolbar>
 
202
 * </ui>
 
203
 * \endcode
 
204
 * 
 
205
 * The constructed widget hierarchy is very similar to the element tree of the XML,
 
206
 * with the exception that placeholders are merged into their parents. The correspondence
 
207
 * of XML elements to widgets should be almost obvious:
 
208
 * - menubar    a Gtk::MenuBar
 
209
 * - toolbar    a Gtk::Toolbar
 
210
 * - popup  a toplevel Gtk::Menu
 
211
 * - menu  a Gtk::Menu attached to a menuitem
 
212
 * - menuitem  a Gtk::MenuItem subclass, the exact type depends on the action
 
213
 * - toolitem  a Gtk::ToolItem subclass, the exact type depends on the action. 
 
214
 * Note that toolitem elements may contain a menu element, but only if their 
 
215
 * associated action specifies a Gtk::MenuToolButton as proxy.
 
216
 * - separator  a Gtk::SeparatorMenuItem or Gtk::SeparatorToolItem
 
217
 * - accelerator        a keyboard accelerator
 
218
 * 
 
219
 * The "position" attribute determines where a constructed widget is positioned wrt. 
 
220
 * to its siblings in the partially constructed tree. If it is "top", the widget is 
 
221
 * prepended, otherwise it is appended. 
 
222
 *
 
223
 * \par UI Merging
 
224
 *
 
225
 * The most remarkable feature of Gtk::UIManager is that it can overlay a set of menuitems 
 
226
 * and toolitems over another one, and demerge them later.
 
227
 *
 
228
 * Merging is done based on the names of the XML elements. Each element is identified by
 
229
 * a path which consists of the names of its anchestors, separated by slashes. For example, 
 
230
 * the menuitem named "Left" in the example above has the path /ui/menubar/JustifyMenu/Left 
 
231
 * and the toolitem with the same name has path /ui/toolbar1/JustifyToolItems/Left.
 
232
 *
 
233
 * \par Accelerators
 
234
 *
 
235
 * Every action has an accelerator path. Accelerators are installed together with menuitem 
 
236
 * proxies, but they can also be explicitly added with <accelerator> elements in the 
 
237
 * UI definition. This makes it possible to have accelerators for actions even 
 
238
 * if they have no visible proxies.
 
239
 * 
 
240
 * \par Smart Separators
 
241
 *
 
242
 * The separators created by Gtk::UIManager are "smart", i.e. they do not show up in 
 
243
 * the UI unless they end up between two visible menu or tool items. Separators which are 
 
244
 * located at the very beginning or end of the menu or toolbar containing them, or multiple 
 
245
 * separators next to each other, are hidden. This is a useful feature, since the merging 
 
246
 * of UI elements from multiple sources can make it hard or impossible to determine in 
 
247
 * advance whether a separator will end up in such an unfortunate position.
 
248
 *
 
249
 * For separators in toolbars, you can set expand="true" to turn them from a small,
 
250
 * visible separator to an expanding, invisible one. Toolitems following an expanding 
 
251
 * separator are effectively right-aligned.
 
252
 *
 
253
 * \par Empty Menus
 
254
 *
 
255
 * Submenus pose similar problems to separators inconnection with merging. It is impossible 
 
256
 * to know in advance whether they will end up empty after merging. Gtk::UIManager offers 
 
257
 * two ways to treat empty submenus:
 
258
 *
 
259
 * - make them disappear by hiding the menu item they're attached to
 
260
 * - add an insensitive "Empty" item
 
261
 *
 
262
 * The behaviour is chosen based on the "hide_if_empty" property of the action to which the submenu is associated.
 
263
 *
 
264
 * @newin{2,4}
 
265
 */
 
266
 
 
267
class UIManager : public Glib::Object
 
268
{
 
269
  
 
270
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
271
 
 
272
public:
 
273
  typedef UIManager CppObjectType;
 
274
  typedef UIManager_Class CppClassType;
 
275
  typedef GtkUIManager BaseObjectType;
 
276
  typedef GtkUIManagerClass BaseClassType;
 
277
 
 
278
private:  friend class UIManager_Class;
 
279
  static CppClassType uimanager_class_;
 
280
 
 
281
private:
 
282
  // noncopyable
 
283
  UIManager(const UIManager&);
 
284
  UIManager& operator=(const UIManager&);
 
285
 
 
286
protected:
 
287
  explicit UIManager(const Glib::ConstructParams& construct_params);
 
288
  explicit UIManager(GtkUIManager* castitem);
 
289
 
 
290
#endif /* DOXYGEN_SHOULD_SKIP_THIS */
 
291
 
 
292
public:
 
293
  virtual ~UIManager();
 
294
 
 
295
#ifndef DOXYGEN_SHOULD_SKIP_THIS
 
296
  static GType get_type()      G_GNUC_CONST;
 
297
 
 
298
 
 
299
  static GType get_base_type() G_GNUC_CONST;
 
300
#endif
 
301
 
 
302
  ///Provides access to the underlying C GObject.
 
303
  GtkUIManager*       gobj()       { return reinterpret_cast<GtkUIManager*>(gobject_); }
 
304
 
 
305
  ///Provides access to the underlying C GObject.
 
306
  const GtkUIManager* gobj() const { return reinterpret_cast<GtkUIManager*>(gobject_); }
 
307
 
 
308
  ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 
309
  GtkUIManager* gobj_copy();
 
310
 
 
311
private:
 
312
 
 
313
protected:
 
314
  UIManager();
 
315
 
 
316
public:
 
317
  
 
318
  static Glib::RefPtr<UIManager> create();
 
319
 
 
320
 
 
321
  /** Sets the "add_tearoffs" property, which controls whether menus 
 
322
   * generated by this Gtk::UIManager will have tearoff menu items. 
 
323
   * 
 
324
   * Note that this only affects regular menus. Generated popup 
 
325
   * menus never have tearoff menu items.
 
326
   * 
 
327
   * @newin{2,4}
 
328
   * @param add_tearoffs Whether tearoff menu items are added.
 
329
   */
 
330
  void set_add_tearoffs(bool add_tearoffs = true);
 
331
  
 
332
  /** Returns whether menus generated by this Gtk::UIManager
 
333
   * will have tearoff menu items. 
 
334
   * 
 
335
   * @newin{2,4}
 
336
   * @return Whether tearoff menu items are added.
 
337
   */
 
338
  bool get_add_tearoffs() const;
 
339
  
 
340
  /** Inserts an action group into the list of action groups associated 
 
341
   * with @a self. Actions in earlier groups hide actions with the same 
 
342
   * name in later groups. 
 
343
   * 
 
344
   * @newin{2,4}
 
345
   * @param action_group The action group to be inserted.
 
346
   * @param pos The position at which the group will be inserted.
 
347
   */
 
348
  void insert_action_group(const Glib::RefPtr<ActionGroup>& action_group, int pos = 0);
 
349
  
 
350
  /** Removes an action group from the list of action groups associated 
 
351
   * with @a self.
 
352
   * 
 
353
   * @newin{2,4}
 
354
   * @param action_group The action group to be removed.
 
355
   */
 
356
  void remove_action_group(const Glib::RefPtr<ActionGroup>& action_group);
 
357
 
 
358
  
 
359
  /** Returns the list of action groups associated with @a self.
 
360
   * 
 
361
   * @newin{2,4}
 
362
   * @return A List of
 
363
   * action groups. The list is owned by GTK+
 
364
   * and should not be modified.
 
365
   */
 
366
  std::vector< Glib::RefPtr<ActionGroup> > get_action_groups();
 
367
 
 
368
 
 
369
  /** Returns the list of action groups associated with @a self.
 
370
   * 
 
371
   * @newin{2,4}
 
372
   * @return A List of
 
373
   * action groups. The list is owned by GTK+
 
374
   * and should not be modified.
 
375
   */
 
376
  std::vector< Glib::RefPtr<const ActionGroup> > get_action_groups() const;
 
377
  
 
378
  
 
379
  /** Returns the Gtk::AccelGroup associated with @a self.
 
380
   * 
 
381
   * @newin{2,4}
 
382
   * @return The Gtk::AccelGroup.
 
383
   */
 
384
  Glib::RefPtr<AccelGroup> get_accel_group();
 
385
  
 
386
  /** Returns the Gtk::AccelGroup associated with @a self.
 
387
   * 
 
388
   * @newin{2,4}
 
389
   * @return The Gtk::AccelGroup.
 
390
   */
 
391
  Glib::RefPtr<const AccelGroup> get_accel_group() const;
 
392
  
 
393
  /** Looks up a widget by following a path. 
 
394
   * The path consists of the names specified in the XML description of the UI. 
 
395
   * separated by '/'. Elements which don't have a name or action attribute in 
 
396
   * the XML (e.g. <popup>) can be addressed by their XML element name 
 
397
   * (e.g. "popup"). The root element ("/ui") can be omitted in the path.
 
398
   * 
 
399
   * Note that the widget found by following a path that ends in a <menu>
 
400
   * element is the menuitem to which the menu is attached, not the menu itself.
 
401
   * 
 
402
   * Also note that the widgets constructed by a ui manager are not tied to 
 
403
   * the lifecycle of the ui manager. If you add the widgets returned by this 
 
404
   * function to some container or explicitly ref them, they will survive the
 
405
   * destruction of the ui manager.
 
406
   * 
 
407
   * @newin{2,4}
 
408
   * @param path A path.
 
409
   * @return The widget found by following the path, or <tt>0</tt> if no widget
 
410
   * was found.
 
411
   */
 
412
  Widget* get_widget(const Glib::ustring& path);
 
413
  
 
414
  /** Looks up a widget by following a path. 
 
415
   * The path consists of the names specified in the XML description of the UI. 
 
416
   * separated by '/'. Elements which don't have a name or action attribute in 
 
417
   * the XML (e.g. <popup>) can be addressed by their XML element name 
 
418
   * (e.g. "popup"). The root element ("/ui") can be omitted in the path.
 
419
   * 
 
420
   * Note that the widget found by following a path that ends in a <menu>
 
421
   * element is the menuitem to which the menu is attached, not the menu itself.
 
422
   * 
 
423
   * Also note that the widgets constructed by a ui manager are not tied to 
 
424
   * the lifecycle of the ui manager. If you add the widgets returned by this 
 
425
   * function to some container or explicitly ref them, they will survive the
 
426
   * destruction of the ui manager.
 
427
   * 
 
428
   * @newin{2,4}
 
429
   * @param path A path.
 
430
   * @return The widget found by following the path, or <tt>0</tt> if no widget
 
431
   * was found.
 
432
   */
 
433
  const Widget* get_widget(const Glib::ustring& path) const;
 
434
 
 
435
 
 
436
  /** Obtains a list of all toplevel widgets of the requested types.
 
437
   * 
 
438
   * @newin{2,4}
 
439
   * @param types Specifies the types of toplevel widgets to include. Allowed
 
440
   * types are Gtk::UI_MANAGER_MENUBAR, Gtk::UI_MANAGER_TOOLBAR and
 
441
   * Gtk::UI_MANAGER_POPUP.
 
442
   * @return A newly-allocated SList of
 
443
   * all toplevel widgets of the requested types.  Free the returned list with Glib::slist_free().
 
444
   */
 
445
  std::vector<Widget*> get_toplevels(UIManagerItemType types);
 
446
 
 
447
 
 
448
  /** Obtains a list of all toplevel widgets of the requested types.
 
449
   * 
 
450
   * @newin{2,4}
 
451
   * @param types Specifies the types of toplevel widgets to include. Allowed
 
452
   * types are Gtk::UI_MANAGER_MENUBAR, Gtk::UI_MANAGER_TOOLBAR and
 
453
   * Gtk::UI_MANAGER_POPUP.
 
454
   * @return A newly-allocated SList of
 
455
   * all toplevel widgets of the requested types.  Free the returned list with Glib::slist_free().
 
456
   */
 
457
  std::vector<const Widget*> get_toplevels(UIManagerItemType types) const;
 
458
                 
 
459
  
 
460
  /** Looks up an action by following a path. See gtk_ui_manager_get_widget()
 
461
   * for more information about paths.
 
462
   * 
 
463
   * @newin{2,4}
 
464
   * @param path A path.
 
465
   * @return The action whose proxy widget is found by following the path, 
 
466
   * or <tt>0</tt> if no widget was found.
 
467
   */
 
468
  Glib::RefPtr<Action> get_action(const Glib::ustring& path);
 
469
  
 
470
  /** Looks up an action by following a path. See gtk_ui_manager_get_widget()
 
471
   * for more information about paths.
 
472
   * 
 
473
   * @newin{2,4}
 
474
   * @param path A path.
 
475
   * @return The action whose proxy widget is found by following the path, 
 
476
   * or <tt>0</tt> if no widget was found.
 
477
   */
 
478
  Glib::RefPtr<const Action> get_action(const Glib::ustring& path) const;
 
479
 
 
480
  typedef guint ui_merge_id;
 
481
    
 
482
  /** Parses a string containing a UI definition and
 
483
   * merges it with the current contents. An enclosing &lt;ui&gt;
 
484
   * element is added if it is missing.
 
485
   *
 
486
   * @param buffer the string to parse
 
487
   * @result  The merge id for the merged UI. The merge id can be used to unmerge the UI with remove_ui(). If an error occurred, the return value is 0.
 
488
   * @throws exception
 
489
   * @newin{2,4}
 
490
   */ 
 
491
  ui_merge_id add_ui_from_string(const Glib::ustring& buffer);
 
492
  
 
493
  
 
494
  /** Parses a file containing a  and 
 
495
   * merges it with the current contents of @a self. 
 
496
   * 
 
497
   * @newin{2,4}
 
498
   * @param filename The name of the file to parse.
 
499
   * @return The merge id for the merged UI. The merge id can be used
 
500
   * to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred,
 
501
   * the return value is 0.
 
502
   */
 
503
  ui_merge_id add_ui_from_file(const Glib::ustring& filename);
 
504
 
 
505
//TODO: Is top=true a good default?
 
506
 
 
507
  
 
508
  /** Adds a UI element to the current contents of @a self.
 
509
   * 
 
510
   * If @a type is Gtk::UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or
 
511
   * separator if such an element can be inserted at the place determined by
 
512
   *  @a path. Otherwise @a type must indicate an element that can be inserted at
 
513
   * the place determined by @a path.
 
514
   * 
 
515
   *  @a see add_ui_separator().
 
516
   * 
 
517
   * @newin{2,4}
 
518
   * @param merge_id The merge id for the merged UI, see gtk_ui_manager_new_merge_id().
 
519
   * @param path A path.
 
520
   * @param name The name for the added UI element.
 
521
   * @param action The name of the action to be proxied, if this is not a separator.
 
522
   * @param type The type of UI element to add.
 
523
   * @param top If <tt>true</tt>, the UI element is added before its siblings, otherwise it
 
524
   * is added after its siblings.
 
525
   */
 
526
  void add_ui(ui_merge_id merge_id, const Glib::ustring& path, const Glib::ustring& name, const Glib::ustring& action, UIManagerItemType type = Gtk::UI_MANAGER_AUTO, bool top = true);
 
527
 
 
528
  /** Adds a separator UI element to the current contents.
 
529
   *
 
530
   * If @a type  is Gtk::UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or
 
531
   * separator if such an element can be inserted at the place determined by
 
532
   *  @a path . Otherwise @a type  must indicate an element that can be inserted at
 
533
   * the place determined by @a path.
 
534
   *
 
535
   * @see add_ui().
 
536
   *
 
537
   * @newin{2,4}
 
538
   * @param merge_id The merge id for the merged UI, see gtk_ui_manager_new_merge_id().
 
539
   * @param path A path.
 
540
   * @param name The name for the added UI element.
 
541
   * @param type The type of UI element to add.
 
542
   * @param top If <tt>true</tt>, the UI element is added before its siblings, otherwise it
 
543
   * is added after its siblings.
 
544
   */
 
545
  void add_ui_separator(ui_merge_id merge_id, const Glib::ustring& path, const Glib::ustring& name = "", UIManagerItemType type = Gtk::UI_MANAGER_AUTO, bool top = true);
 
546
  
 
547
  
 
548
  /** Unmerges the part of @a self<!-- -->s content identified by @a merge_id.
 
549
   * 
 
550
   * @newin{2,4}
 
551
   * @param merge_id A merge id as returned by gtk_ui_manager_add_ui_from_string().
 
552
   */
 
553
  void remove_ui(ui_merge_id merge_id);
 
554
  
 
555
  /** Creates a  of the merged UI.
 
556
   * 
 
557
   * @newin{2,4}
 
558
   * @return A newly allocated string containing an XML representation of 
 
559
   * the merged UI.
 
560
   */
 
561
  Glib::ustring get_ui() const;
 
562
  
 
563
  /** Makes sure that all pending updates to the UI have been completed.
 
564
   * 
 
565
   * This may occasionally be necessary, since Gtk::UIManager updates the 
 
566
   * UI in an idle function. A typical example where this function is
 
567
   * useful is to enforce that the menubar and toolbar have been added to 
 
568
   * the main window before showing it:
 
569
   * |[
 
570
   * gtk_container_add (GTK_CONTAINER (window), vbox); 
 
571
   * g_signal_connect (merge, "add-widget", 
 
572
   * G_CALLBACK (add_widget), vbox);
 
573
   * gtk_ui_manager_add_ui_from_file (merge, "my-menus");
 
574
   * gtk_ui_manager_add_ui_from_file (merge, "my-toolbars");
 
575
   * gtk_ui_manager_ensure_update (merge);  
 
576
   * gtk_widget_show (window);
 
577
   * ]|
 
578
   * 
 
579
   * @newin{2,4}
 
580
   */
 
581
  void ensure_update();
 
582
  
 
583
  /** Returns an unused merge id, suitable for use with 
 
584
   * gtk_ui_manager_add_ui().
 
585
   * 
 
586
   * @newin{2,4}
 
587
   * @return An unused merge id.
 
588
   */
 
589
  ui_merge_id new_merge_id();
 
590
 
 
591
  /** The add_widget signal is emitted for each generated menubar and toolbar.
 
592
   * It is not emitted for generated popup menus, which can be obtained by 
 
593
   * get_widget().
 
594
   * 
 
595
   * @param widget the added widget
 
596
   *
 
597
   * @par Prototype:
 
598
   * <tt>void on_my_%add_widget(Widget* widget)</tt>
 
599
   */
 
600
 
 
601
  Glib::SignalProxy1< void,Widget* > signal_add_widget();
 
602
 
 
603
  
 
604
  /** The "actions-changed" signal is emitted whenever the set of actions
 
605
   * changes.
 
606
   *
 
607
   * @par Prototype:
 
608
   * <tt>void on_my_%actions_changed()</tt>
 
609
   */
 
610
 
 
611
  Glib::SignalProxy0< void > signal_actions_changed();
 
612
 
 
613
  
 
614
  /** The connect_proxy signal is emitted after connecting a proxy to 
 
615
   * an action in the group. 
 
616
   *
 
617
   * This is intended for simple customizations for which a custom action
 
618
   * class would be too clumsy, e.g. showing tooltips for menuitems in the
 
619
   * statusbar.
 
620
   *
 
621
   * @param action the action
 
622
   * @param widget the proxy
 
623
   *
 
624
   * @par Prototype:
 
625
   * <tt>void on_my_%connect_proxy(const Glib::RefPtr<Action>& action, Widget* widget)</tt>
 
626
   */
 
627
 
 
628
  Glib::SignalProxy2< void,const Glib::RefPtr<Action>&,Widget* > signal_connect_proxy();
 
629
 
 
630
  
 
631
  /** The disconnect_proxy signal is emitted after disconnecting a proxy 
 
632
   * from an action in the group. 
 
633
   *
 
634
   * @param action the action
 
635
   * @param widget the proxy
 
636
   *
 
637
   * @par Prototype:
 
638
   * <tt>void on_my_%disconnect_proxy(const Glib::RefPtr<Action>& action, Widget* widget)</tt>
 
639
   */
 
640
 
 
641
  Glib::SignalProxy2< void,const Glib::RefPtr<Action>&,Widget* > signal_disconnect_proxy();
 
642
 
 
643
  
 
644
  /** The pre_activate signal is emitted just before the @a action
 
645
   * is activated.
 
646
   *
 
647
   * This is intended for applications to get notification
 
648
   * just before any action is activated.
 
649
   *
 
650
   * @param action the action
 
651
   *
 
652
   * @par Prototype:
 
653
   * <tt>void on_my_%pre_activate(const Glib::RefPtr<Action>& action)</tt>
 
654
   */
 
655
 
 
656
  Glib::SignalProxy1< void,const Glib::RefPtr<Action>& > signal_pre_activate();
 
657
 
 
658
  
 
659
  /** The post_activate signal is emitted just after the @a action
 
660
   * is activated.
 
661
   *
 
662
   * This is intended for applications to get notification
 
663
   * just after any action is activated.
 
664
   *
 
665
   * @param action the action
 
666
   *
 
667
   * @par Prototype:
 
668
   * <tt>void on_my_%post_activate(const Glib::RefPtr<Action>& action)</tt>
 
669
   */
 
670
 
 
671
  Glib::SignalProxy1< void,const Glib::RefPtr<Action>& > signal_post_activate();
 
672
 
 
673
 
 
674
  #ifdef GLIBMM_PROPERTIES_ENABLED
 
675
/** Whether tearoff menu items should be added to menus.
 
676
   *
 
677
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 
678
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 
679
   * the value of the property changes.
 
680
   */
 
681
  Glib::PropertyProxy<bool> property_add_tearoffs() ;
 
682
#endif //#GLIBMM_PROPERTIES_ENABLED
 
683
 
 
684
#ifdef GLIBMM_PROPERTIES_ENABLED
 
685
/** Whether tearoff menu items should be added to menus.
 
686
   *
 
687
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 
688
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 
689
   * the value of the property changes.
 
690
   */
 
691
  Glib::PropertyProxy_ReadOnly<bool> property_add_tearoffs() const;
 
692
#endif //#GLIBMM_PROPERTIES_ENABLED
 
693
 
 
694
  #ifdef GLIBMM_PROPERTIES_ENABLED
 
695
/** An XML string describing the merged UI.
 
696
   *
 
697
   * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 
698
   * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 
699
   * the value of the property changes.
 
700
   */
 
701
  Glib::PropertyProxy_ReadOnly<Glib::ustring> property_ui() const;
 
702
#endif //#GLIBMM_PROPERTIES_ENABLED
 
703
 
 
704
 
 
705
public:
 
706
 
 
707
public:
 
708
  //C++ methods used to invoke GTK+ virtual functions:
 
709
 
 
710
protected:
 
711
  //GTK+ Virtual Functions (override these to change behaviour):
 
712
 
 
713
  //Default Signal Handlers::
 
714
  virtual void on_add_widget(Widget* widget);
 
715
  virtual void on_actions_changed();
 
716
  virtual void on_connect_proxy(const Glib::RefPtr<Action>& action, Widget* widget);
 
717
  virtual void on_disconnect_proxy(const Glib::RefPtr<Action>& action, Widget* widget);
 
718
  virtual void on_pre_activate(const Glib::RefPtr<Action>& action);
 
719
  virtual void on_post_activate(const Glib::RefPtr<Action>& action);
 
720
 
 
721
 
 
722
};
 
723
 
 
724
} // namespace Gtk
 
725
 
 
726
 
 
727
namespace Glib
 
728
{
 
729
  /** A Glib::wrap() method for this object.
 
730
   * 
 
731
   * @param object The C instance.
 
732
   * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 
733
   * @result A C++ instance that wraps this C instance.
 
734
   *
 
735
   * @relates Gtk::UIManager
 
736
   */
 
737
  Glib::RefPtr<Gtk::UIManager> wrap(GtkUIManager* object, bool take_copy = false);
 
738
}
 
739
 
 
740
 
 
741
#endif /* _GTKMM_UIMANAGER_H */
 
742