1/* $Id: accelgroup.hg,v 1.8 2005/04/07 08:46:44 murrayc Exp $ */
2
3/* Copyright (C) 1998-2002 The gtkmm Development Team
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2.1 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13 * Lesser General Public License for more details.
14 *
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, write to the Free
17 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
18 */
19
20
21_DEFS(gtkmm,gtk)
22_PINCLUDE(glibmm/private/object_p.h)
23
24#include <gdkmm/types.h>
25#include <gtkmm/object.h>
26
27
28namespace Gtk
29{
30
31/** A Gtk::AccelGroup represents a group of keyboard accelerators, typically
32 * attached to a toplevel Gtk::Window (with Gtk::Window::add_accel_group()).
33 * Usually you won't need to create a Gtk::AccelGroup directly; instead, gtkmm
34 * automatically sets up the accelerators for your menus.  Note that
35 * accelerators are different from mnemonics.  Accelerators are shortcuts for
36 * activating a menu item; they appear alongside the menu item for which
37 * they're a shortcut. For example "Ctrl+Q" might appear alongside the "Quit"
38 * menu item.  Mnemonics are shortcuts for GUI elements such as text entries or
39 * buttons; they appear as underlined characters. See the Gtk::Label
40 * constructor. Menu items can have both accelerators and mnemonics, of course.
41 *
42 * You can use Gtk::Window::get_accel_group() to get an accel group for that window,
43 * then use it with other widgets too.
44 */
45class AccelGroup : public Glib::Object
46{
47   _CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP,Glib::Object,GObject)
48   _IGNORE(gtk_accel_group_connect, gtk_accel_group_connect_by_path, gtk_accel_group_disconnect,
49           gtk_accel_group_query, _gtk_accel_group_reconnect)
50   _IGNORE_SIGNAL(accel_activate)
51protected:
52  _CTOR_DEFAULT
53
54public:
55  /** Creates a new Gtk::AccelGroup object.
56   * @return A Glib::RefPtr<> to a newly created Gtk::AccelGroup object.
57   */
58  _WRAP_CREATE()
59
60  _WRAP_METHOD(bool get_is_locked() const, gtk_accel_group_get_is_locked)
61  _WRAP_METHOD(Gdk::ModifierType get_modifier_mask() const, gtk_accel_group_get_modifier_mask)
62
63  _WRAP_METHOD(void lock(), gtk_accel_group_lock)
64  _WRAP_METHOD(void unlock(), gtk_accel_group_unlock)
65  _WRAP_METHOD(bool disconnect_key(guint accel_key, Gdk::ModifierType accel_mods), gtk_accel_group_disconnect_key)
66
67  /** Determines whether a given keyval and modifier mask constitute
68  * a valid keyboard accelerator. For example, the 'a' keyval
69  * plus Gdk::CONTROL_MASK is valid - this is a "Ctrl+a" accelerator.
70  * But you can't, for instance, use the GDK_Control_L keyval
71  * as an accelerator.
72  */
73  static bool valid(guint keyval, Gdk::ModifierType modifiers);
74
75   /** Parse the accelerator string.
76   * @param accelerator See the Gtk::AccelKey constructor for the format.
77   * @param accelerator_key Output argument
78   * @param accelerator_mods Output argument
79   */
80  static void parse(const Glib::ustring& accelerator, guint& accelerator_key, Gdk::ModifierType& accelerator_mods);
81
82  /** Converts an accelerator keyval and modifier mask
83   * into a string parseable by parse().
84   * For example, if you pass in 'q' and Gdk::CONTROL_MASK, it returns "&lt;Control&gt;q".
85   */
86  static Glib::ustring name(guint accelerator_key, Gdk::ModifierType accelerator_mods);
87
88  _WRAP_METHOD(static Glib::ustring get_label(guint accelerator_key, Gdk::ModifierType accelerator_mods), gtk_accelerator_get_label)
89
90  /** Sets the modifiers that will be considered significant for keyboard
91   * accelerators. The default mod mask is Gdk::CONTROL_MASK |
92   * Gdk::SHIFT_MASK | Gdk::MOD1_MASK, that is, Control, Shift, and Alt.
93   * Other modifiers will ignored by default.
94   * You must include at least the three default modifiers in any
95   * value you pass to this function.
96   *
97   * The default mod mask should be changed on application startup,
98   * before using any accelerator groups.
99   */
100  static void set_default_mod_mask(Gdk::ModifierType default_mod_mask);
101
102  /// See set_default_mod_mask().
103  static Gdk::ModifierType get_default_mod_mask();
104
105  //TODO: Add an overload that takes a ustring instead of a GQuark.
106  _WRAP_METHOD(bool activate(GQuark accel_quark, const Glib::RefPtr<Glib::Object>& acceleratable, guint	accel_key, Gdk::ModifierType accel_mods), gtk_accel_group_activate)
107
108  _IGNORE(gtk_accel_group_find)
109  //Let's not wrap this, because the GtkAccelGroupFindFunc callback uses GClosures, and it's not clear that this is useful.
110  //AccelKey find(const SlotFind& slot);
111  //GtkAccelKey*	gtk_accel_group_find(GtkAccelGroup* accel_group, GtkAccelGroupFindFunc find_func, gpointer data);
112
113  _WRAP_METHOD(static bool activate(Gtk::Object& object, guint accel_key, Gdk::ModifierType accel_mods), gtk_accel_groups_activate)
114
115
116  _WRAP_SIGNAL(bool accel_activate(const Glib::RefPtr<Glib::Object>& acceleratable, guint keyval, Gdk::ModifierType modifier), "accel_activate", no_default_handler)
117
118  //TODO: The C type is unpleasant:
119  //This has C docs, but it isn't worth mentioning them for such a useless signal. murrayc.
120  _WRAP_SIGNAL(void accel_changed(guint keyval, Gdk::ModifierType modifier, GClosure* accel_closure), "accel_changed")
121
122  _WRAP_PROPERTY("is-locked", bool)
123  _WRAP_PROPERTY("modifier-mask", Gdk::ModifierType)
124};
125
126} // namespace Gtk
127
128