libs/gtkmm2/gtk/gtkmm/menu.h

   1 // -*- c++ -*-
   2 // Generated by gtkmmproc -- DO NOT MODIFY!
   3 #ifndef _GTKMM_MENU_H
   4 #define _GTKMM_MENU_H
   5
   6
   7 #include <glibmm.h>
   8
   9 /* $Id$ */
  10
  11 /* Copyright (C) 1998-2002 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 Library General Public
  15  * License as published by the Free Software Foundation; either
  16  * version 2 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  * Library General Public License for more details.
  22  *
  23  * You should have received a copy of the GNU Library 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
  29 //#include <gtk/gtkmenu.h>
  30 #include <gtkmm/menushell.h>
  31 #include <gtkmm/menuitem.h>
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 typedef struct _GtkMenu GtkMenu;
  35 typedef struct _GtkMenuClass GtkMenuClass;
  36 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  37
  38
  39 namespace Gtk
  40 { class Menu_Class; } // namespace Gtk
  41 namespace Gtk
  42 {
  43
  44 class AccelGroup;
  45
  46 /** @defgroup Menus Menu classes
  47  */
  48
  49 /** A drop-down menu consisting of Gtk::MenuItem objects which can be navigated and activated by the user to perform application functions.
  50  * Menus are normally placed inside a Gtk::MenuBar or another MenuItem as a sub menu.
  51  * A Menu can also be popped up, for instance as a right-click context menu, by calling the popup() method.
  52  * See also Gtk::OptionMenu.
  53  * @ingroup Widgets
  54  * @ingroup Menus
  55  */
  56
  57 class Menu : public MenuShell
  58 {
  59   public:
  60 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  61   typedef Menu CppObjectType;
  62   typedef Menu_Class CppClassType;
  63   typedef GtkMenu BaseObjectType;
  64   typedef GtkMenuClass BaseClassType;
  65 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  66
  67   virtual ~Menu();
  68
  69 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  70
  71 private:
  72   friend class Menu_Class;
  73   static CppClassType menu_class_;
  74
  75   // noncopyable
  76   Menu(const Menu&);
  77   Menu& operator=(const Menu&);
  78
  79 protected:
  80   explicit Menu(const Glib::ConstructParams& construct_params);
  81   explicit Menu(GtkMenu* castitem);
  82
  83 #endif /* DOXYGEN_SHOULD_SKIP_THIS */
  84
  85 public:
  86 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  87   static GType get_type()      G_GNUC_CONST;
  88   static GType get_base_type() G_GNUC_CONST;
  89 #endif
  90
  91   ///Provides access to the underlying C GtkObject.
  92   GtkMenu*       gobj()       { return reinterpret_cast<GtkMenu*>(gobject_); }
  93
  94   ///Provides access to the underlying C GtkObject.
  95   const GtkMenu* gobj() const { return reinterpret_cast<GtkMenu*>(gobject_); }
  96
  97
  98 public:
  99   //C++ methods used to invoke GTK+ virtual functions:
 100 #ifdef GLIBMM_VFUNCS_ENABLED
 101 #endif //GLIBMM_VFUNCS_ENABLED
 102
 103 protected:
 104   //GTK+ Virtual Functions (override these to change behaviour):
 105 #ifdef GLIBMM_VFUNCS_ENABLED
 106 #endif //GLIBMM_VFUNCS_ENABLED
 107
 108   //Default Signal Handlers::
 109 #ifdef GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 110 #endif //GLIBMM_DEFAULT_SIGNAL_HANDLERS_ENABLED
 111
 112
 113 private:
 114
 115
 116    //deprecated.
 117 public:
 118   Menu();
 119
 120 /* append, prepend, and insert are defined in MenuShell */
 121
 122   /** For instance,
 123    * void on_popup_menu_position(int& x, int& y, bool& push_in);
 124    */
 125   typedef sigc::slot<void, int&, int&, bool&> SlotPositionCalc;
 126
 127   void popup(MenuShell& parent_menu_shell, MenuItem& parent_menu_item, const SlotPositionCalc& slot, guint button, guint32 activate_time);
 128
 129
 130   /** Displays a menu and makes it available for selection.  Applications can use
 131    * this function to display context-sensitive menus.
 132    *
 133    * The @a button  parameter should be the mouse button pressed to initiate
 134    * the menu popup. If the menu popup was initiated by something other than
 135    * a mouse button press, such as a mouse button release or a keypress,
 136    *  @a button  should be 0.
 137    *
 138    * The @a activate_time  parameter should be the time stamp of the event that
 139    * initiated the popup. If such an event is not available, use
 140    * gtk_get_current_event_time() instead.
 141    * @param func A position_calc_slot supplied function used to position the menu, or <tt>0</tt>.
 142    * @param button The mouse button which was pressed to initiate the event.
 143    * @param activate_time The time at which the activation event occurred.
 144    */
 145   void popup(const SlotPositionCalc& position_calc_slot, guint button, guint32 activate_time);
 146
 147   /** Displays a menu and makes it available for selection.
 148    * Applications can use this function to display context-sensitive menus, at the current pointer position.
 149    * @param button The button which was pressed to initiate the event.
 150    * @param activate_time The time at which the activation event occurred.
 151    */
 152   void popup(guint button, guint32 activate_time);
 153
 154
 155   void reposition();
 156
 157
 158   void popdown();
 159
 160
 161   MenuItem* get_active();
 162
 163   const MenuItem* get_active() const;
 164
 165   void set_active(guint index);
 166
 167
 168   void set_accel_group(const Glib::RefPtr<AccelGroup>& accel_group);
 169   void unset_accel_group();
 170
 171   Glib::RefPtr<AccelGroup> get_accel_group();
 172
 173   Glib::RefPtr<const AccelGroup> get_accel_group() const;
 174
 175
 176   /** Sets an accelerator path for this menu from which accelerator paths
 177    * for its immediate children, its menu items, can be constructed.
 178    * The main purpose of this function is to spare the programmer the
 179    * inconvenience of having to call Gtk::MenuItem::set_accel_path() on
 180    * each menu item that should support runtime user changable accelerators.
 181    * Instead, by just calling set_accel_path() on their parent,
 182    * each menu item of this menu, that contains a label describing its purpose,
 183    * automatically gets an accel path assigned. For example, a menu containing
 184    * menu items "New" and "Exit", will, after
 185    * <tt>gtk_menu_set_accel_path (menu, "&lt;Gnumeric-Sheet&gt;/File");</tt>
 186    * has been called, assign its items the accel paths:
 187    * <tt>"&lt;Gnumeric-Sheet&gt;/File/New"</tt> and <tt>"&lt;Gnumeric-Sheet&gt;/File/Exit"</tt>.
 188    * Assigning accel paths to menu items then enables the user to change
 189    * their accelerators at runtime. More details about accelerator paths
 190    * and their default setups can be found at gtk_accel_map_add_entry().
 191    * @param accel_path A valid accelerator path.
 192    */
 193   void set_accel_path(const Glib::ustring& accel_path);
 194
 195
 196   void detach();
 197
 198   Widget* get_attach_widget();
 199
 200   const Widget* get_attach_widget() const;
 201
 202
 203   void set_tearoff_state(bool torn_off = true);
 204
 205   /** Return value: <tt>true</tt> if the menu is currently torn off.
 206    * @return <tt>true</tt> if the menu is currently torn off.
 207    */
 208   bool get_tearoff_state() const;
 209
 210
 211   /** Sets the title string for the menu.  The title is displayed when the menu
 212    * is shown as a tearoff menu.  If @a title  is <tt>0</tt>, the menu will see if it is
 213    * attached to a parent menu item, and if so it will try to use the same text as
 214    * that menu item's label.
 215    * @param title A string containing the title for the menu.
 216    */
 217   void set_title(const Glib::ustring& title);
 218   void unset_title();
 219
 220   /** Return value: the title of the menu, or <tt>0</tt> if the menu has no
 221    * @return The title of the menu, or <tt>0</tt> if the menu has no
 222    * title set on it. This string is owned by the widget and should
 223    * not be modified or freed.
 224    */
 225   Glib::ustring get_title() const;
 226
 227   /** Sets the Gdk::Screen on which the menu will be displayed.
 228    *
 229    * @newin2p2
 230    * @param screen A Gdk::Screen, or <tt>0</tt> if the screen should be
 231    * determined by the widget the menu is attached to.
 232    */
 233   void set_screen(const Glib::RefPtr<Gdk::Screen>& screen);
 234
 235
 236   /** Adds a new Gtk::MenuItem to a (table) menu. The number of 'cells' that
 237    * an item will occupy is specified by @a left_attach , @a right_attach ,
 238    *  @a top_attach  and @a bottom_attach . These each represent the leftmost,
 239    * rightmost, uppermost and lower column and row numbers of the table.
 240    * (Columns and rows are indexed from zero).
 241    *
 242    * Note that this function is not related to detach().
 243    *
 244    * @newin2p4
 245    * @param child A Gtk::MenuItem.
 246    * @param left_attach The column number to attach the left side of the item to.
 247    * @param right_attach The column number to attach the right side of the item to.
 248    * @param top_attach The row number to attach the top of the item to.
 249    * @param bottom_attach The row number to attach the bottom of the item to.
 250    */
 251   void attach(Gtk::Widget& child, guint left_attach, guint right_attach, guint top_attach, guint bottom_attach);
 252
 253
 254   /** Informs GTK+ on which monitor a menu should be popped up.
 255    * See gdk_screen_get_monitor_geometry().
 256    *
 257    * This function should be called from a Gtk::MenuPositionFunc if the
 258    * menu should not appear on the same monitor as the pointer. This
 259    * information can't be reliably inferred from the coordinates returned
 260    * by a Gtk::MenuPositionFunc, since, for very long menus, these coordinates
 261    * may extend beyond the monitor boundaries or even the screen boundaries.
 262    *
 263    * @newin2p4
 264    * @param monitor_num The number of the monitor on which the menu should
 265    * be popped up.
 266    */
 267   void set_monitor(int monitor_num);
 268
 269   void reorder_child(const MenuItem& child, int position);
 270
 271
 272   #ifdef GLIBMM_PROPERTIES_ENABLED
 273 /** A title that may be displayed by the window manager when this menu is torn-off.
 274    *
 275    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 276    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 277    * the value of the property changes.
 278    */
 279   Glib::PropertyProxy<Glib::ustring> property_tearoff_title() ;
 280 #endif //#GLIBMM_PROPERTIES_ENABLED
 281
 282 #ifdef GLIBMM_PROPERTIES_ENABLED
 283 /** A title that may be displayed by the window manager when this menu is torn-off.
 284    *
 285    * You rarely need to use properties because there are get_ and set_ methods for almost all of them.
 286    * @return A PropertyProxy that allows you to get or set the property of the value, or receive notification when
 287    * the value of the property changes.
 288    */
 289   Glib::PropertyProxy_ReadOnly<Glib::ustring> property_tearoff_title() const;
 290 #endif //#GLIBMM_PROPERTIES_ENABLED
 291
 292
 293 protected:
 294
 295   //We can not wrap this as a slot because there is no data parameter, and no destroy callback to destroy that data.
 296   typedef void (*GtkMenuDetachFunc)   (GtkWidget *attach_widget, GtkMenu   *menu);
 297
 298   void attach_to_widget(Widget& attach_widget, GtkMenuDetachFunc detacher);
 299
 300   //TODO: What does "attach" actually mean here? murrayc
 301   /** Attaches the menu to the widget.
 302    *
 303    * param @attach_widget: the Widget that the menu will be attached to.
 304    *
 305    * @newin2p10
 306    */
 307   void attach_to_widget(Widget& attach_widget);
 308
 309
 310 };
 311
 312 } // namespace Gtk
 313
 314
 315 namespace Glib
 316 {
 317   /** A Glib::wrap() method for this object.
 318    *
 319    * @param object The C instance.
 320    * @param take_copy False if the result should take ownership of the C instance. True if it should take a new copy or ref.
 321    * @result A C++ instance that wraps this C instance.
 322    *
 323    * @relates Gtk::Menu
 324    */
 325   Gtk::Menu* wrap(GtkMenu* object, bool take_copy = false);
 326 } //namespace Glib
 327
 328
 329 #endif /* _GTKMM_MENU_H */
 330