X-Git-Url: http://pileus.org/git/?a=blobdiff_plain;f=gtk%2Fgtkaccelmap.c;h=7154b404f86e6e60ebdda2322a5eb8feb05e4afc;hb=dc331ccb171151d737112d8dc55b25709271d2c7;hp=179351a3bf0a031b2c9872017630f67d07ca7d19;hpb=5f1b5d24067468fc86b28dccc504c71abdaf68b8;p=~andy%2Fgtk diff --git a/gtk/gtkaccelmap.c b/gtk/gtkaccelmap.c index 179351a3b..7154b404f 100644 --- a/gtk/gtkaccelmap.c +++ b/gtk/gtkaccelmap.c @@ -12,17 +12,15 @@ * Lesser General Public License for more details. * * You should have received a copy of the GNU Lesser General Public - * License along with this library; if not, write to the - * Free Software Foundation, Inc., 59 Temple Place - Suite 330, - * Boston, MA 02111-1307, USA. + * License along with this library. If not, see . */ #include "config.h" -#include "gtkaccelmap.h" +#include "gtkaccelmapprivate.h" #include "gtkmarshalers.h" -#include "gtkwindow.h" /* in lack of GtkAcceleratable */ +#include "gtkwindowprivate.h" #include "gtkintl.h" #include @@ -38,6 +36,76 @@ #endif +/** + * SECTION:gtkaccelmap + * @Short_description: Loadable keyboard accelerator specifications + * @Title: Accelerator Maps + * @See_also: #GtkAccelGroup, #GtkAccelKey, #GtkUIManager, gtk_widget_set_accel_path(), gtk_menu_item_set_accel_path(), #GtkSettings:gtk-can-change-accels + * + * Accelerator maps are used to define runtime configurable accelerators. + * Functions for manipulating them are are usually used by higher level + * convenience mechanisms like #GtkUIManager and are thus considered + * "low-level". You'll want to use them if you're manually creating menus that + * should have user-configurable accelerators. + * + * Accelerator is uniquely defined by: + * + * + * accelerator path + * accelerator key + * accelerator modifiers + * + * + * The accelerator path must consist of + * "<WINDOWTYPE>/Category1/Category2/.../Action", where WINDOWTYPE + * should be a unique application-specific identifier that corresponds to the + * kind of window the accelerator is being used in, e.g. "Gimp-Image", + * "Abiword-Document" or "Gnumeric-Settings". + * The "Category1/.../Action" portion is most appropriately chosen by the action + * the accelerator triggers, i.e. for accelerators on menu items, choose the + * item's menu path, e.g. "File/Save As", "Image/View/Zoom" or + * "Edit/Select All". So a full valid accelerator path may look like: + * "<Gimp-Toolbox>/File/Dialogs/Tool Options...". + * + * All accelerators are stored inside one global #GtkAccelMap that can be + * obtained using gtk_accel_map_get(). See Monitoring changes for additional + * details. + * + * + * Manipulating accelerators + * + * New accelerators can be added using gtk_accel_map_add_entry(). To search for + * specific accelerator, use gtk_accel_map_lookup_entry(). Modifications of + * existing accelerators should be done using gtk_accel_map_change_entry(). + * + * In order to avoid having some accelerators changed, they can be locked using + * gtk_accel_map_lock_path(). Unlocking is done using + * gtk_accel_map_unlock_path(). + * + * + * + * Saving and loading accelerator maps + * + * Accelerator maps can be saved to and loaded from some external resource. For + * simple saving and loading from file, gtk_accel_map_save() and + * gtk_accel_map_load() are provided. Saving and loading can also be done by + * providing file descriptor to gtk_accel_map_save_fd() and + * gtk_accel_map_load_fd(). + * + * + * + * Monitoring changes + * + * #GtkAccelMap object is only useful for monitoring changes of accelerators. By + * connecting to #GtkAccelMap::changed signal, one can monitor changes of all + * accelerators. It is also possible to monitor only single accelerator path by + * using it as a detail of the #GtkAccelMap::changed signal. + * + * + */ + + /* --- structures --- */ struct _GtkAccelMap { @@ -109,9 +177,8 @@ accel_path_lookup (const gchar *accel_path) void _gtk_accel_map_init (void) { - g_assert (accel_entry_ht == NULL); - - accel_entry_ht = g_hash_table_new (accel_entry_hash, accel_entry_equal); + if (accel_entry_ht == NULL) + accel_entry_ht = g_hash_table_new (accel_entry_hash, accel_entry_equal); } gboolean @@ -139,16 +206,10 @@ _gtk_accel_path_is_valid (const gchar *accel_path) * with the canonical @accel_key and @accel_mods for this path. * To change the accelerator during runtime programatically, use * gtk_accel_map_change_entry(). - * The accelerator path must consist of "<WINDOWTYPE>/Category1/Category2/.../Action", - * where <WINDOWTYPE> should be a unique application-specific identifier, that - * corresponds to the kind of window the accelerator is being used in, e.g. "Gimp-Image", - * "Abiword-Document" or "Gnumeric-Settings". - * The Category1/.../Action portion is most appropriately chosen by the action the - * accelerator triggers, i.e. for accelerators on menu items, choose the item's menu path, - * e.g. "File/Save As", "Image/View/Zoom" or "Edit/Select All". - * So a full valid accelerator path may look like: - * "<Gimp-Toolbox>/File/Dialogs/Tool Options...". * + * Set @accel_key and @accel_mods to 0 to request a removal of + * the accelerator. + * * Note that @accel_path string will be stored in a #GQuark. Therefore, if you * pass a static string, you can save some memory by interning it first with * g_intern_static_string(). @@ -199,9 +260,10 @@ gtk_accel_map_add_entry (const gchar *accel_path, * gtk_accel_map_lookup_entry: * @accel_path: a valid accelerator path * @key: (allow-none) (out): the accelerator key to be filled in (optional) - * @returns: %TRUE if @accel_path is known, %FALSE otherwise * * Looks up the accelerator entry for @accel_path and fills in @key. + * + * Returns: %TRUE if @accel_path is known, %FALSE otherwise */ gboolean gtk_accel_map_lookup_entry (const gchar *accel_path, @@ -424,7 +486,6 @@ internal_change_entry (const gchar *accel_path, * @accel_key: the new accelerator key * @accel_mods: the new accelerator modifiers * @replace: %TRUE if other accelerators may be deleted upon conflicts - * @returns: %TRUE if the accelerator could be changed, %FALSE otherwise * * Changes the @accel_key and @accel_mods currently associated with @accel_path. * Due to conflicts with other accelerators, a change may not always be possible, @@ -432,10 +493,12 @@ internal_change_entry (const gchar *accel_path, * conflicts. A change will only occur if all conflicts could be resolved (which * might not be the case if conflicting accelerators are locked). Successful * changes are indicated by a %TRUE return value. - * + * * Note that @accel_path string will be stored in a #GQuark. Therefore, if you - * pass a static string, you can save some memory by interning it first with + * pass a static string, you can save some memory by interning it first with * g_intern_static_string(). + * + * Returns: %TRUE if the accelerator could be changed, %FALSE otherwise */ gboolean gtk_accel_map_change_entry (const gchar *accel_path, @@ -608,7 +671,7 @@ gtk_accel_map_load_fd (gint fd) /** * gtk_accel_map_load: - * @file_name: a file containing accelerator specifications, + * @file_name: (type filename): a file containing accelerator specifications, * in the GLib file name encoding * * Parses a file previously saved with gtk_accel_map_save() for @@ -719,8 +782,8 @@ gtk_accel_map_save_fd (gint fd) /** * gtk_accel_map_save: - * @file_name: the name of the file to contain accelerator specifications, - * in the GLib file name encoding + * @file_name: (type filename): the name of the file to contain + * accelerator specifications, in the GLib file name encoding * * Saves current accelerator specifications (accelerator path, key * and modifiers) to @file_name. @@ -745,9 +808,9 @@ gtk_accel_map_save (const gchar *file_name) /** * gtk_accel_map_foreach: - * @data: data to be passed into @foreach_func - * @foreach_func: function to be executed for each accel map entry which - * is not filtered out + * @data: (allow-none): data to be passed into @foreach_func + * @foreach_func: (scope call): function to be executed for each accel + * map entry which is not filtered out * * Loops over the entries in the accelerator map whose accel path * doesn't match any of the filters added with gtk_accel_map_add_filter(), @@ -783,7 +846,8 @@ gtk_accel_map_foreach (gpointer data, /** * gtk_accel_map_foreach_unfiltered: * @data: data to be passed into @foreach_func - * @foreach_func: function to be executed for each accel map entry + * @foreach_func: (scope call): function to be executed for each accel + * map entry * * Loops over all entries in the accelerator map, and execute * @foreach_func on each. The signature of @foreach_func is that of @@ -891,7 +955,7 @@ _gtk_accel_map_remove_group (const gchar *accel_path, * * Note that locking of individual accelerator paths is independent from * locking the #GtkAccelGroup containing them. For runtime accelerator - * changes to be possible both the accelerator path and its #GtkAccelGroup + * changes to be possible, both the accelerator path and its #GtkAccelGroup * have to be unlocked. * * Since: 2.4 @@ -1004,30 +1068,19 @@ do_accel_map_changed (AccelEntry *entry) entry->accel_mods); } -#if defined (G_OS_WIN32) && !defined (_WIN64) - -#undef gtk_accel_map_load - -void -gtk_accel_map_load (const gchar *file_name) -{ - gchar *utf8_file_name = g_locale_to_utf8 (file_name, -1, NULL, NULL, NULL); - - gtk_accel_map_load_utf8 (utf8_file_name); - - g_free (utf8_file_name); -} - -#undef gtk_accel_map_save - -void -gtk_accel_map_save (const gchar *file_name) +gchar * +_gtk_accel_path_for_action (const gchar *action_name, + GVariant *parameter) { - gchar *utf8_file_name = g_locale_to_utf8 (file_name, -1, NULL, NULL, NULL); - - gtk_accel_map_save_utf8 (utf8_file_name); + GString *s; - g_free (utf8_file_name); + s = g_string_new ("/"); + g_string_append (s, action_name); + if (parameter) + { + g_string_append_c (s, '/'); + g_variant_print_string (parameter, s, FALSE); + } + return g_string_free (s, FALSE); } -#endif