libs/gtkmm2/gtk/gtkmm/uimanager.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_UIMANAGER_H
   4 #define _GTKMM_UIMANAGER_H
   5
   6 #include <glibmm.h>
   7
   8 /* $Id$ */
   9
  10 /* Copyright (C) 2003 The gtkmm Development Team
  11  *
  12  * This library is free software; you can redistribute it and/or
  13  * modify it under the terms of the GNU Library General Public
  14  * License as published by the Free Software Foundation; either
  15  * version 2 of the License, or (at your option) any later version.
  16  *
  17  * This library is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  20  * Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with this library; if not, write to the Free
  24  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  25  */
  26
  27 #include <gtkmm/widget.h>
  28 #include <gtkmm/action.h>
  29 #include <gtkmm/actiongroup.h>
  30 #include <gtkmm/uimanager.h>
  31
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 typedef struct _GtkUIManager GtkUIManager;
  35 typedef struct _GtkUIManagerClass GtkUIManagerClass;
  36 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  37
  38
  39 namespace Gtk
  40 { class UIManager_Class; } // namespace Gtk
  41 namespace Gtk
  42 {
  43
  44 /** @addtogroup gtkmmEnums Enums and Flags */
  45
  46 /**
  47  * @ingroup gtkmmEnums
  48  * @par Bitwise operators:
  49  * <tt>%UIManagerItemType operator|(UIManagerItemType, UIManagerItemType)</tt><br>
  50  * <tt>%UIManagerItemType operator&(UIManagerItemType, UIManagerItemType)</tt><br>
  51  * <tt>%UIManagerItemType operator^(UIManagerItemType, UIManagerItemType)</tt><br>
  52  * <tt>%UIManagerItemType operator~(UIManagerItemType)</tt><br>
  53  * <tt>%UIManagerItemType& operator|=(UIManagerItemType&, UIManagerItemType)</tt><br>
  54  * <tt>%UIManagerItemType& operator&=(UIManagerItemType&, UIManagerItemType)</tt><br>
  55  * <tt>%UIManagerItemType& operator^=(UIManagerItemType&, UIManagerItemType)</tt><br>
  56  */
  57 enum UIManagerItemType
  58 {
  59   UI_MANAGER_AUTO = 0,
  60   UI_MANAGER_MENUBAR = 1 << 0,
  61   UI_MANAGER_MENU = 1 << 1,
  62   UI_MANAGER_TOOLBAR = 1 << 2,
  63   UI_MANAGER_PLACEHOLDER = 1 << 3,
  64   UI_MANAGER_POPUP = 1 << 4,
  65   UI_MANAGER_MENUITEM = 1 << 5,
  66   UI_MANAGER_TOOLITEM = 1 << 6,
  67   UI_MANAGER_SEPARATOR = 1 << 7,
  68   UI_MANAGER_ACCELERATOR = 1 << 8
  69 };
  70
  71 /** @ingroup gtkmmEnums */
  72 inline UIManagerItemType operator|(UIManagerItemType lhs, UIManagerItemType rhs)
  73   { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs)); }
  74
  75 /** @ingroup gtkmmEnums */
  76 inline UIManagerItemType operator&(UIManagerItemType lhs, UIManagerItemType rhs)
  77   { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs)); }
  78
  79 /** @ingroup gtkmmEnums */
  80 inline UIManagerItemType operator^(UIManagerItemType lhs, UIManagerItemType rhs)
  81   { return static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs)); }
  82
  83 /** @ingroup gtkmmEnums */
  84 inline UIManagerItemType operator~(UIManagerItemType flags)
  85   { return static_cast<UIManagerItemType>(~static_cast<unsigned>(flags)); }
  86
  87 /** @ingroup gtkmmEnums */
  88 inline UIManagerItemType& operator|=(UIManagerItemType& lhs, UIManagerItemType rhs)
  89   { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) | static_cast<unsigned>(rhs))); }
  90
  91 /** @ingroup gtkmmEnums */
  92 inline UIManagerItemType& operator&=(UIManagerItemType& lhs, UIManagerItemType rhs)
  93   { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) & static_cast<unsigned>(rhs))); }
  94
  95 /** @ingroup gtkmmEnums */
  96 inline UIManagerItemType& operator^=(UIManagerItemType& lhs, UIManagerItemType rhs)
  97   { return (lhs = static_cast<UIManagerItemType>(static_cast<unsigned>(lhs) ^ static_cast<unsigned>(rhs))); }
  98
  99 } // namespace Gtk
 100
 101
 102 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 103 namespace Glib
 104 {
 105
 106 template <>
 107 class Value<Gtk::UIManagerItemType> : public Glib::Value_Flags<Gtk::UIManagerItemType>
 108 {
 109 public:
 110   static GType value_type() G_GNUC_CONST;
 111 };
 112
 113 } // namespace Glib
 114 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 115
 116
 117 namespace Gtk
 118 {
 119
 120
 121 class UIManager : public Glib::Object
 122 {
 123
 124 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 125
 126 public:
 127   typedef UIManager CppObjectType;
 128   typedef UIManager_Class CppClassType;
 129   typedef GtkUIManager BaseObjectType;
 130   typedef GtkUIManagerClass BaseClassType;
 131
 132 private:  friend class UIManager_Class;
 133   static CppClassType uimanager_class_;
 134
 135 private:
 136   // noncopyable
 137   UIManager(const UIManager&);
 138   UIManager& operator=(const UIManager&);
 139
 140 protected:
 141   explicit UIManager(const Glib::ConstructParams& construct_params);
 142   explicit UIManager(GtkUIManager* castitem);
 143
 144 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
 145
 146 public:
 147   virtual ~UIManager();
 148
 149 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 150   static GType get_type()      G_GNUC_CONST;
 151   static GType get_base_type() G_GNUC_CONST;
 152 #endif
 153
 154   ///Provides access to the underlying C GObject.
 155   GtkUIManager*       gobj()       { return reinterpret_cast<GtkUIManager*>(gobject_); }
 156
 157   ///Provides access to the underlying C GObject.
 158   const GtkUIManager* gobj() const { return reinterpret_cast<GtkUIManager*>(gobject_); }
 159
 160   ///Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
 161   GtkUIManager* gobj_copy();
 162
 163 private:
 164
 165 protected:
 166   UIManager();
 167
 168 public:
 169
 170   static Glib::RefPtr<UIManager> create();
 171
 172
 173   /** Sets the "add_tearoffs" property, which controls whether menus
 174    * generated by this Gtk::UIManager will have tearoff menu items.
 175    *
 176    * Note that this only affects regular menus. Generated popup
 177    * menus never have tearoff menu items.
 178    *
 179    * Since: 2.4
 180    * @param add_tearoffs Whether tearoff menu items are added.
 181    */
 182   void set_add_tearoffs(bool add_tearoffs = true);
 183
 184   /** Returns whether menus generated by this Gtk::UIManager
 185    * will have tearoff menu items.
 186    * @return Whether tearoff menu items are added
 187    *
 188    * Since: 2.4.
 189    */
 190   bool get_add_tearoffs() const;
 191
 192   /** Inserts an action group into the list of action groups associated
 193    * with @a self . Actions in earlier groups hide actions with the same
 194    * name in later groups.
 195    *
 196    * Since: 2.4
 197    * @param action_group The action group to be inserted.
 198    * @param pos The position at which the group will be inserted.
 199    */
 200   void insert_action_group(const Glib::RefPtr<ActionGroup>& action_group, int pos = 0);
 201
 202   /** Removes an action group from the list of action groups associated
 203    * with @a self .
 204    *
 205    * Since: 2.4
 206    * @param action_group The action group to be removed.
 207    */
 208   void remove_action_group(const Glib::RefPtr<ActionGroup>& action_group);
 209
 210
 211   /** Returns the list of action groups associated with @a self .
 212    * @return A G::List of action groups. The list is owned by GTK+
 213    * and should not be modified.
 214    *
 215    * Since: 2.4.
 216    */
 217   Glib::ListHandle< Glib::RefPtr<ActionGroup> > get_action_groups();
 218
 219   /** Returns the list of action groups associated with @a self .
 220    * @return A G::List of action groups. The list is owned by GTK+
 221    * and should not be modified.
 222    *
 223    * Since: 2.4.
 224    */
 225   Glib::ListHandle< Glib::RefPtr<const ActionGroup> > get_action_groups() const;
 226
 227
 228   /** Returns the Gtk::AccelGroup associated with @a self .
 229    * @return The Gtk::AccelGroup.
 230    *
 231    * Since: 2.4.
 232    */
 233   Glib::RefPtr<AccelGroup> get_accel_group();
 234
 235   /** Returns the Gtk::AccelGroup associated with @a self .
 236    * @return The Gtk::AccelGroup.
 237    *
 238    * Since: 2.4.
 239    */
 240   Glib::RefPtr<const AccelGroup> get_accel_group() const;
 241
 242   /** Looks up a widget by following a path.
 243    * The path consists of the names specified in the XML description of the UI.
 244    * separated by '/'. Elements which don't have a name or action attribute in
 245    * the XML (e.g. &lt;popup&gt;) can be addressed by their XML element name
 246    * (e.g. "popup"). The root element ("/ui") can be omitted in the path.
 247    *
 248    * Note that the widget found by following a path that ends in a &lt;menu&gt;
 249    * element is the menuitem to which the menu is attached, not the menu itself.
 250    * @param path A path.
 251    * @return The widget found by following the path, or <tt>0</tt> if no widget
 252    * was found.
 253    *
 254    * Since: 2.4.
 255    */
 256   Widget* get_widget(const Glib::ustring& path);
 257
 258   /** Looks up a widget by following a path.
 259    * The path consists of the names specified in the XML description of the UI.
 260    * separated by '/'. Elements which don't have a name or action attribute in
 261    * the XML (e.g. &lt;popup&gt;) can be addressed by their XML element name
 262    * (e.g. "popup"). The root element ("/ui") can be omitted in the path.
 263    *
 264    * Note that the widget found by following a path that ends in a &lt;menu&gt;
 265    * element is the menuitem to which the menu is attached, not the menu itself.
 266    * @param path A path.
 267    * @return The widget found by following the path, or <tt>0</tt> if no widget
 268    * was found.
 269    *
 270    * Since: 2.4.
 271    */
 272   const Widget* get_widget(const Glib::ustring& path) const;
 273
 274
 275   /** Obtains a list of all toplevel widgets of the requested types.
 276    * @param types Specifies the types of toplevel widgets to include. Allowed
 277    * types are Gtk::UI_MANAGER_MENUBAR, Gtk::UI_MANAGER_TOOLBAR and
 278    * Gtk::UI_MANAGER_POPUP.
 279    * @return A newly-allocated of all toplevel widgets of the requested
 280    * types.
 281    *
 282    * Since: 2.4.
 283    */
 284   Glib::SListHandle<Widget*> get_toplevels(UIManagerItemType types);
 285
 286   /** Obtains a list of all toplevel widgets of the requested types.
 287    * @param types Specifies the types of toplevel widgets to include. Allowed
 288    * types are Gtk::UI_MANAGER_MENUBAR, Gtk::UI_MANAGER_TOOLBAR and
 289    * Gtk::UI_MANAGER_POPUP.
 290    * @return A newly-allocated of all toplevel widgets of the requested
 291    * types.
 292    *
 293    * Since: 2.4.
 294    */
 295   Glib::SListHandle<const Widget*> get_toplevels(UIManagerItemType types) const;
 296
 297
 298   /** Looks up an action by following a path. See gtk_ui_manager_get_widget()
 299    * for more information about paths.
 300    * @param path A path.
 301    * @return The action whose proxy widget is found by following the path,
 302    * or <tt>0</tt> if no widget was found.
 303    *
 304    * Since: 2.4.
 305    */
 306   Glib::RefPtr<Action> get_action(const Glib::ustring& path);
 307
 308   /** Looks up an action by following a path. See gtk_ui_manager_get_widget()
 309    * for more information about paths.
 310    * @param path A path.
 311    * @return The action whose proxy widget is found by following the path,
 312    * or <tt>0</tt> if no widget was found.
 313    *
 314    * Since: 2.4.
 315    */
 316   Glib::RefPtr<const Action> get_action(const Glib::ustring& path) const;
 317
 318   typedef guint ui_merge_id;
 319
 320   /** Parses a string containing a UI definition and
 321    * merges it with the current contents. An enclosing &lt;ui&gt;
 322    * element is added if it is missing.
 323    *
 324    * @param buffer the string to parse
 325    * @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.
 326    * @throws exception
 327    * Since: 2.4
 328    */
 329   ui_merge_id add_ui_from_string(const Glib::ustring& buffer);
 330
 331
 332   /** Parses a file containing a UI definition and
 333    * merges it with the current contents of @a self .
 334    * @param filename The name of the file to parse.
 335    * @return The merge id for the merged UI. The merge id can be used
 336    * to unmerge the UI with gtk_ui_manager_remove_ui(). If an error occurred,
 337    * the return value is 0.
 338    *
 339    * Since: 2.4.
 340    */
 341   ui_merge_id add_ui_from_file(const Glib::ustring& filename);
 342
 343 //TODO: Is top=true a good default?
 344
 345
 346   /** Adds a UI element to the current contents of @a self .
 347    *
 348    * If @a type  is Gtk::UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or
 349    * separator if such an element can be inserted at the place determined by
 350    *  @a path . Otherwise @a type  must indicate an element that can be inserted at
 351    * the place determined by @a path .
 352    *
 353    *  @a see  add_ui_separator().
 354    *
 355    * Since: 2.4
 356    * @param merge_id The merge id for the merged UI, see gtk_ui_manager_new_merge_id().
 357    * @param path A path.
 358    * @param name The name for the added UI element.
 359    * @param action The name of the action to be proxied, if this is not a separator.
 360    * @param type The type of UI element to add.
 361    * @param top If <tt>true</tt>, the UI element is added before its siblings, otherwise it
 362    * is added after its siblings.
 363    */
 364   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);
 365
 366   /** Adds a separator UI element to the current contents.
 367    *
 368    * If @a type  is Gtk::UI_MANAGER_AUTO, GTK+ inserts a menuitem, toolitem or
 369    * separator if such an element can be inserted at the place determined by
 370    *  @a path . Otherwise @a type  must indicate an element that can be inserted at
 371    * the place determined by @a path.
 372    *
 373    * @see add_ui().
 374    *
 375    * Since: 2.4
 376    * @param merge_id The merge id for the merged UI, see gtk_ui_manager_new_merge_id().
 377    * @param path A path.
 378    * @param name The name for the added UI element.
 379    * @param type The type of UI element to add.
 380    * @param top If <tt>true</tt>, the UI element is added before its siblings, otherwise it
 381    * is added after its siblings.
 382    */
 383   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);
 384
 385
 386   /** Unmerges the part of @a self &lt;!-- --&gt;s content identified by @a merge_id .
 387    *
 388    * Since: 2.4
 389    * @param merge_id A merge id as returned by gtk_ui_manager_add_ui_from_string().
 390    */
 391   void remove_ui(ui_merge_id merge_id);
 392
 393   /** Creates a UI definition of the merged UI.
 394    * @return A newly allocated string containing an XML representation of
 395    * the merged UI.
 396    *
 397    * Since: 2.4.
 398    */
 399   Glib::ustring get_ui() const;
 400
 401   /** Makes sure that all pending updates to the UI have been completed.
 402    *
 403    * This may occasionally be necessary, since Gtk::UIManager updates the
 404    * UI in an idle function. A typical example where this function is
 405    * useful is to enforce that the menubar and toolbar have been added to
 406    * the main window before showing it:
 407    * @code
 408    *
 409    * gtk_container_add (GTK_CONTAINER (window), vbox);
 410    * g_signal_connect (merge, "add_widget",
 411    * G_CALLBACK (add_widget), vbox);
 412    * gtk_ui_manager_add_ui_from_file (merge, "my-menus");
 413    * gtk_ui_manager_add_ui_from_file (merge, "my-toolbars");
 414    * gtk_ui_manager_ensure_update (merge);
 415    * gtk_widget_show (window);
 416    *
 417    * @endcode
 418    *
 419    * Since: 2.4
 420    */
 421   void ensure_update();
 422
 423   /** Returns an unused merge id, suitable for use with
 424    * gtk_ui_manager_add_ui().
 425    * @return An unused merge id.
 426    *
 427    * Since: 2.4.
 428    */
 429   ui_merge_id new_merge_id();
 430
 431
 432   Glib::SignalProxy1< void,Widget* > signal_add_widget();
 433
 434
 435   Glib::SignalProxy0< void > signal_actions_changed();
 436
 437
 438   Glib::SignalProxy2< void,const Glib::RefPtr<Action>&,Widget* > signal_connect_proxy();
 439
 440
 441   Glib::SignalProxy2< void,const Glib::RefPtr<Action>&,Widget* > signal_disconnect_proxy();
 442
 443
 444   Glib::SignalProxy1< void,const Glib::RefPtr<Action>& > signal_pre_activate();
 445
 446
 447   Glib::SignalProxy1< void,const Glib::RefPtr<Action>& > signal_post_activate();
 448
 449
 450   /** Whether tearoff menu items should be added to menus.
 451    *
 452    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 453    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 454    * the value of the property changes.
 455    */
 456   Glib::PropertyProxy<bool> property_add_tearoffs() ;
 457
 458 /** Whether tearoff menu items should be added to menus.
 459    *
 460    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 461    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 462    * the value of the property changes.
 463    */
 464   Glib::PropertyProxy_ReadOnly<bool> property_add_tearoffs() const;
 465
 466   /** An XML string describing the merged UI.
 467    *
 468    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 469    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 470    * the value of the property changes.
 471    */
 472   Glib::PropertyProxy_ReadOnly<Glib::ustring> property_ui() const;
 473
 474
 475 public:
 476
 477 public:
 478   //C++ methods used to invoke GTK+ virtual functions:
 479
 480 protected:
 481   //GTK+ Virtual Functions (override these to change behaviour):
 482
 483   //Default Signal Handlers::
 484   virtual void on_add_widget(Widget* widget);
 485   virtual void on_actions_changed();
 486
 487
 488 };
 489
 490 } // namespace Gtk
 491
 492
 493 namespace Glib
 494 {
 495   /** @relates Gtk::UIManager
 496    * @param object The C instance
 497    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 498    * @result A C++ instance that wraps this C instance.
 499    */
 500   Glib::RefPtr<Gtk::UIManager> wrap(GtkUIManager* object, bool take_copy = false);
 501 }
 502
 503
 504 #endif /* _GTKMM_UIMANAGER_H */
 505