libs/gtkmm2/gtk/gtkmm/accelmap.h

   1 // -*- c++ -*-
   2 #ifndef _GTKMM_ACCELMAP_H
   3 #define _GTKMM_ACCELMAP_H
   4
   5 /* $Id$ */
   6
   7 /* accelmap.h
   8  *
   9  * Copyright (C) 2002 The Gtkmm Development Team
  10  *
  11  * This library is free software; you can redistribute it and/or
  12  * modify it under the terms of the GNU Library General Public
  13  * License as published by the Free Software Foundation; either
  14  * version 2 of the License, or (at your option) any later version.
  15  *
  16  * This library is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  19  * Library General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU Library General Public
  22  * License along with this library; if not, write to the Free
  23  * Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  24  */
  25
  26 #include <string>
  27
  28 #include <gdkmm/types.h>
  29
  30 namespace Gtk
  31 {
  32
  33 namespace AccelMap
  34 {
  35
  36 //TODO: Why is the accel_path a std::string, instead of a Glib::ustring? murrayc.
  37
  38 /** Registers a new accelerator with the global accelerator map.
  39  * This function should only be called once per accel_path
  40  * with the canonical accel_key and accel_mods for this path.
  41  * To change the accelerator during runtime programatically, use
  42  * change_entry().
  43  * The accelerator path must consist of "&lt;WINDOWTYPE&gt;/Category1/Category2/.../Action",
  44  * where &lt;WINDOWTYPE&gt; should be a unique application-specific identifier, that
  45  * corresponds to the kind of window the accelerator is being used in, e.g. "Gimp-Image",
  46  * "Abiword-Document" or "Gnumeric-Settings".
  47  * The Category1/.../Action portion is most appropriately chosen by the action the
  48  * accelerator triggers, i.e. for accelerators on menu items, choose the item's menu path,
  49  * e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All".
  50  * So a full valid accelerator path may look like:
  51  * "&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...".
  52  *
  53  * @param accel_path valid accelerator path
  54  * @param accel_key the accelerator key
  55  * @param accel_mods the accelerator modifiers
  56  *
  57  */
  58 void add_entry(const std::string& accel_path,
  59                guint accel_key,
  60                Gdk::ModifierType accel_mods);
  61
  62 /** Changes the accel_key and accel_mods currently associated with accel_path.
  63  * Due to conflicts with other accelerators, a change may not always be possible,
  64  * replace indicates whether other accelerators may be deleted to resolve such
  65  * conflicts. A change will only occur if all conflicts could be resolved (which
  66  * might not be the case if conflicting accelerators are locked). Successful
  67  * changes are indicated by a true return value.
  68  *
  69  * @param accel_path  a valid accelerator path
  70  * @param accel_key   the new accelerator key
  71  * @param accel_mods  the new accelerator modifiers
  72  * @param replace     true if other accelerators may be deleted upon conflicts
  73  * @result     true if the accelerator could be changed, false otherwise
  74  */
  75 bool change_entry(const std::string& accel_path,
  76                   guint accel_key,
  77                   Gdk::ModifierType accel_mods,
  78                   bool replace);
  79
  80 /** Parses a file previously saved with save() for
  81  * accelerator specifications, and propagates them accordingly.
  82  *
  83  * @param filename a file containing accelerator specifications
  84  */
  85 void load(const std::string& filename);
  86
  87 /** Saves current accelerator specifications (accelerator path, key
  88  * and modifiers) to filename.
  89  * The file is written in a format suitable to be read back in by
  90  * load().
  91  *
  92  * @param filename the file to contain accelerator specifications
  93  */
  94 void save(const std::string& filename);
  95
  96 /** Locks the given accelerator path.
  97  *
  98  * Locking an accelerator path prevents its accelerator from being changed
  99  * during runtime. A locked accelerator path can be unlocked by
 100  * unlock_path(). Refer to change_entry()
 101  * about runtime accelerator changes.
 102  *
 103  * Note that locking of individual accelerator paths is independent from
 104  * locking the #GtkAccelGroup containing them. For runtime accelerator
 105  * changes to be possible both the accelerator path and its AccelGroup
 106  * have to be unlocked.
 107  *
 108  * @param accel_path a valid accelerator path
 109  *
 110  * Since: 2.4
 111  **/
 112 void lock_path(const std::string& accel_path);
 113
 114 /** Unlocks the given accelerator path. Refer to gtk_accel_map_lock_path()
 115  * about accelerator path locking.
 116  *
 117  * @param accel_path a valid accelerator path
 118  *
 119  * Since: 2.4
 120  **/
 121 void unlock_path(const std::string& accel_path);
 122
 123 } // namespace AccelMap
 124
 125 } // namespace Gtk
 126
 127
 128 #endif /* _GTKMM_ACCELMAP_H */
 129