Commit d947178e authored by Tadej Borovšak's avatar Tadej Borovšak Committed by Javier Jardon

Update and expand GtkAccelMap API docs

parent e267ed84
......@@ -42,6 +42,69 @@
* 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:
*
* <itemizedlist>
* <listitem><para>accelerator path</para></listitem>
* <listitem><para>accelerator key</para></listitem>
* <listitem><para>accelerator modifiers</para></listitem>
* </itemizedlist>
*
* The accelerator path must consist of
* "&lt;WINDOWTYPE&gt;/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:
* "&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...".
*
* All accelerators are stored inside one global #GtkAccelMap that can be
* obtained using gtk_accel_map_get(). See <link
* linkend="monitoring-changes">Monitoring changes</link> for additional
* details.
*
* <refsect2 id="manipulating-accelerators">
* <title>Manipulating accelerators</title>
* <para>
* 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().
* </para>
* </refsect2>
* <refsect2 id="saving-and-loading">
* <title>Saving and loading accelerator maps</title>
* <para>
* 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().
* </para>
* </refsect2>
* <refsect2 id="monitoring-changes">
* <title>Monitoring changes</title>
* <para>
* #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.
* </para>
* </refsect2>
*/
......@@ -146,15 +209,6 @@ _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 "&lt;WINDOWTYPE&gt;/Category1/Category2/.../Action",
* where &lt;WINDOWTYPE&gt; 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:
* "&lt;Gimp-Toolbox&gt;/File/Dialogs/Tool Options...".
*
* 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
......
......@@ -41,6 +41,16 @@ typedef struct _GtkAccelMap GtkAccelMap;
typedef struct _GtkAccelMapClass GtkAccelMapClass;
/* --- notifier --- */
/**
* GtkAccelMapForeach:
* @data: User data passed to gtk_accel_map_foreach() or
* gtk_accel_map_foreach_unfiltered()
* @accel_path: Accel path of the current accelerator
* @accel_key: Key of the current accelerator
* @accel_mods: Modifiers of the current accelerator
* @changed: Changed flag of the accelerator (if %TRUE, accelerator has changed
* during runtime and would need to be saved during an accelerator dump)
*/
typedef void (*GtkAccelMapForeach) (gpointer data,
const gchar *accel_path,
guint accel_key,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment