/* $Id: accelgroup.hg,v 1.8 2005/04/07 08:46:44 murrayc Exp $ */

/* Copyright (C) 1998-2002 The gtkmm Development Team
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the Free
 * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
 */


_DEFS(gtkmm,gtk)
_PINCLUDE(glibmm/private/object_p.h)

#include <gdkmm/types.h>
#include <gtkmm/object.h>


namespace Gtk
{

/** A Gtk::AccelGroup represents a group of keyboard accelerators, typically
 * attached to a toplevel Gtk::Window (with Gtk::Window::add_accel_group()).
 * Usually you won't need to create a Gtk::AccelGroup directly; instead, gtkmm
 * automatically sets up the accelerators for your menus.  Note that
 * accelerators are different from mnemonics.  Accelerators are shortcuts for
 * activating a menu item; they appear alongside the menu item for which
 * they're a shortcut. For example "Ctrl+Q" might appear alongside the "Quit"
 * menu item.  Mnemonics are shortcuts for GUI elements such as text entries or
 * buttons; they appear as underlined characters. See the Gtk::Label
 * constructor. Menu items can have both accelerators and mnemonics, of course.
 *
 * You can use Gtk::Window::get_accel_group() to get an accel group for that window,
 * then use it with other widgets too.
 */
class AccelGroup : public Glib::Object
{
   _CLASS_GOBJECT(AccelGroup, GtkAccelGroup, GTK_ACCEL_GROUP,Glib::Object,GObject)
   _IGNORE(gtk_accel_group_connect, gtk_accel_group_connect_by_path, gtk_accel_group_disconnect,
           gtk_accel_group_query, _gtk_accel_group_reconnect)
   _IGNORE_SIGNAL(accel_activate)
protected:
  _CTOR_DEFAULT

public:
  /** Creates a new Gtk::AccelGroup object.
   * @return A Glib::RefPtr<> to a newly created Gtk::AccelGroup object.
   */
  _WRAP_CREATE()

  _WRAP_METHOD(void lock(), gtk_accel_group_lock)
  _WRAP_METHOD(void unlock(), gtk_accel_group_unlock)
  _WRAP_METHOD(bool disconnect_key(guint accel_key, Gdk::ModifierType accel_mods), gtk_accel_group_disconnect_key)

  /** Determines whether a given keyval and modifier mask constitute
  * a valid keyboard accelerator. For example, the 'a' keyval
  * plus Gdk::CONTROL_MASK is valid - this is a "Ctrl+a" accelerator.
  * But you can't, for instance, use the GDK_Control_L keyval
  * as an accelerator.
  */
  static bool valid(guint keyval, Gdk::ModifierType modifiers);

   /** Parse the accelerator string.
   * @param accelerator See the Gtk::AccelKey constructor for the format.
   * @param accelerator_key Output argument
   * @param accelerator_mods Output argument
   */
  static void parse(const Glib::ustring& accelerator, guint& accelerator_key, Gdk::ModifierType& accelerator_mods);

  /** Converts an accelerator keyval and modifier mask
   * into a string parseable by parse().
   * For example, if you pass in 'q' and Gdk::CONTROL_MASK, it returns "&lt;Control&gt;q".
   */
  static Glib::ustring name(guint accelerator_key, Gdk::ModifierType accelerator_mods);

  _WRAP_METHOD(static Glib::ustring get_label(guint accelerator_key, Gdk::ModifierType accelerator_mods), gtk_accelerator_get_label)

  /** Sets the modifiers that will be considered significant for keyboard
   * accelerators. The default mod mask is Gdk::CONTROL_MASK |
   * Gdk::SHIFT_MASK | Gdk::MOD1_MASK, that is, Control, Shift, and Alt.
   * Other modifiers will ignored by default.
   * You must include at least the three default modifiers in any
   * value you pass to this function.
   *
   * The default mod mask should be changed on application startup,
   * before using any accelerator groups.
   */
  static void set_default_mod_mask(Gdk::ModifierType default_mod_mask);

  /// See set_default_mod_mask().
  static Gdk::ModifierType get_default_mod_mask();

  //TODO: This is undocumented in GTK+ at the moment. When would it be used and where does the quark come from? murrayc.
  _WRAP_METHOD(bool activate(GQuark accel_quark, const Glib::RefPtr<Glib::Object>& acceleratable, guint	accel_key, Gdk::ModifierType accel_mods), gtk_accel_group_activate)

  _IGNORE(gtk_accel_group_find)
  //Let's not wrap this, because the GtkAccelGroupFindFunc callback uses GClosures, and it's not clear that this is useful.
  //AccelKey find(const SlotFind& slot);
  //GtkAccelKey*	gtk_accel_group_find(GtkAccelGroup* accel_group, GtkAccelGroupFindFunc find_func, gpointer data);
                            
  _WRAP_METHOD(static bool activate(Gtk::Object& object, guint accel_key, Gdk::ModifierType accel_mods), gtk_accel_groups_activate)

  //TODO: Discover real parameter names:
  _WRAP_SIGNAL(bool accel_activate(const Glib::RefPtr<Glib::Object>& object, guint param2, Gdk::ModifierType param3), "accel_activate", no_default_handler)   
  //TODO: The C type is unpleasant:
  //This has C docs, but it isn't worth mentioning them for such a useless signal. murrayc.
  _WRAP_SIGNAL(void accel_changed(guint keyval, Gdk::ModifierType modifier, GClosure* accel_closure), "accel_changed")
};

} // namespace Gtk

