Commit 9104420c authored by Matthias Clasen's avatar Matthias Clasen Committed by Emmanuele Bassi
Browse files

shortcutswindow: Convert docs

parent 0d238f4c
......@@ -30,16 +30,16 @@
#include "gtksizegroup.h"
/**
* SECTION:gtkshortcutsgroup
* @Title: GtkShortcutsGroup
* @Short_description: Represents a group of shortcuts in a GtkShortcutsWindow
* GtkShortcutsGroup:
*
* A GtkShortcutsGroup represents a group of related keyboard shortcuts
* or gestures. The group has a title. It may optionally be associated with
* a view of the application, which can be used to show only relevant shortcuts
* A `GtkShortcutsGroup` represents a group of related keyboard shortcuts
* or gestures.
*
* The group has a title. It may optionally be associated with a view
* of the application, which can be used to show only relevant shortcuts
* depending on the application context.
*
* This widget is only meant to be used with #GtkShortcutsWindow.
* This widget is only meant to be used with [class@Gtk.ShortcutsWindow].
*/
struct _GtkShortcutsGroup
......@@ -284,8 +284,9 @@ gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass)
* GtkShortcutsGroup:view:
*
* An optional view that the shortcuts in this group are relevant for.
* The group will be hidden if the #GtkShortcutsWindow:view-name property
* does not match the view of this group.
*
* The group will be hidden if the [property@Gtk.ShortcutsWindow:view-name]
* property does not match the view of this group.
*
* Set this to %NULL to make the group always visible.
*/
......
......@@ -38,20 +38,21 @@
#include "gtkintl.h"
/**
* SECTION:gtkshortcutssection
* @Title: GtkShortcutsSection
* @Short_description: Represents an application mode in a GtkShortcutsWindow
* GtkShortcutsSection:
*
* A GtkShortcutsSection collects all the keyboard shortcuts and gestures
* for a major application mode. If your application needs multiple sections,
* you should give each section a unique #GtkShortcutsSection:section-name and
* a #GtkShortcutsSection:title that can be shown in the section selector of
* the GtkShortcutsWindow.
* A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures
* for a major application mode.
*
* The #GtkShortcutsSection:max-height property can be used to influence how
* the groups in the section are distributed over pages and columns.
* If your application needs multiple sections, you should give each
* section a unique [property@Gtk.ShortcutsSection:section-name] and
* a [property@Gtk.ShortcutsSection:title] that can be shown in the
* section selector of the [class@Gtk.ShortcutsWindow].
*
* This widget is only meant to be used with #GtkShortcutsWindow.
* The [property@Gtk.ShortcutsSection:max-height] property can be used
* to influence how the groups in the section are distributed over pages
* and columns.
*
* This widget is only meant to be used with [class@Gtk.ShortcutsWindow].
*/
struct _GtkShortcutsSection
......@@ -286,9 +287,10 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
* GtkShortcutsSection:section-name:
*
* A unique name to identify this section among the sections
* added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name
* property to this string will make this section shown in the
* GtkShortcutsWindow.
* added to the `GtkShortcutsWindow`.
*
* Setting the [property@Gtk.ShortcutsWindow:section-name] property
* to this string will make this section shown in the `GtkShortcutsWindow`.
*/
properties[PROP_SECTION_NAME] =
g_param_spec_string ("section-name", P_("Section Name"), P_("Section Name"),
......@@ -299,10 +301,12 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
* GtkShortcutsSection:view-name:
*
* A view name to filter the groups in this section by.
* See #GtkShortcutsGroup:view.
*
* Applications are expected to use the #GtkShortcutsWindow:view-name
* property for this purpose.
* See [property@Gtk.ShortcutsGroup:view].
*
* Applications are expected to use the
* [property@Gtk.ShortcutsWindow:view-name] property
* for this purpose.
*/
properties[PROP_VIEW_NAME] =
g_param_spec_string ("view-name", P_("View Name"), P_("View Name"),
......@@ -312,9 +316,11 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
/**
* GtkShortcutsSection:title:
*
* The string to show in the section selector of the GtkShortcutsWindow
* for this section. If there is only one section, you don't need to
* set a title, since the section selector will not be shown in this case.
* The string to show in the section selector of the `GtkShortcutsWindow`
* for this section.
*
* If there is only one section, you don't need to set a title,
* since the section selector will not be shown in this case.
*/
properties[PROP_TITLE] =
g_param_spec_string ("title", P_("Title"), P_("Title"),
......@@ -324,10 +330,11 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
/**
* GtkShortcutsSection:max-height:
*
* The maximum number of lines to allow per column. This property can
* be used to influence how the groups in this section are distributed
* across pages and columns. The default value of 15 should work in
* most cases.
* The maximum number of lines to allow per column.
*
* This property can be used to influence how the groups in this
* section are distributed across pages and columns. The default
* value of 15 should work in most cases.
*/
properties[PROP_MAX_HEIGHT] =
g_param_spec_uint ("max-height", P_("Maximum Height"), P_("Maximum Height"),
......
......@@ -32,12 +32,12 @@
#include "gtktypebuiltins.h"
/**
* SECTION:gtkshortcutsshortcut
* @Title: GtkShortcutsShortcut
* @Short_description: Represents a keyboard shortcut in a GtkShortcutsWindow
* GtkShortcutsShortcut:
*
* A GtkShortcutsShortcut represents a single keyboard shortcut or gesture
* with a short text. This widget is only meant to be used with #GtkShortcutsWindow.
* A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture
* with a short text.
*
* This widget is only meant to be used with `GtkShortcutsWindow`.
*/
struct _GtkShortcutsShortcut
......@@ -551,24 +551,30 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/**
* GtkShortcutsShortcut:accelerator:
*
* The accelerator(s) represented by this object. This property is used
* if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_ACCELERATOR.
* The accelerator(s) represented by this object.
*
* This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type]
* is set to %GTK_SHORTCUT_ACCELERATOR.
*
* The syntax of this property is (an extension of) the syntax understood
* by [func@Gtk.accelerator_parse]. Multiple accelerators can be specified
* by separating them with a space, but keep in mind that the available width
* is limited.
*
* The syntax of this property is (an extension of) the syntax understood by
* gtk_accelerator_parse(). Multiple accelerators can be specified by separating
* them with a space, but keep in mind that the available width is limited.
* It is also possible to specify ranges of shortcuts, using ... between the keys.
* Sequences of keys can be specified using a + or & between the keys.
* It is also possible to specify ranges of shortcuts, using "..." between
* the keys. Sequences of keys can be specified using a "+" or "&" between
* the keys.
*
* Examples:
*
* - A single shortcut: <ctl><alt>delete
* - Two alternative shortcuts: <shift>a Home
* - A range of shortcuts: <alt>1...<alt>9
* - Several keys pressed together: Control_L&Control_R
* - A sequence of shortcuts or keys: <ctl>c+<ctl>x
*
* Use + instead of & when the keys may (or have to be) pressed sequentially (e.g
* use t+t for 'press the t key twice').
* Use "+" instead of "&" when the keys may (or have to be) pressed
* sequentially (e.g use "t+t" for 'press the t key twice').
*
* Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
* in .ui files.
......@@ -583,8 +589,11 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/**
* GtkShortcutsShortcut:icon:
*
* An icon to represent the shortcut or gesture. This property is used if
* #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_GESTURE.
* An icon to represent the shortcut or gesture.
*
* This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type]
* is set to %GTK_SHORTCUT_GESTURE.
*
* For the other predefined gesture types, GTK provides an icon on its own.
*/
properties[PROP_ICON] =
......@@ -610,7 +619,9 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
* GtkShortcutsShortcut:title:
*
* The textual description for the shortcut or gesture represented by
* this object. This should be a short string that can fit in a single line.
* this object.
*
* This should be a short string that can fit in a single line.
*/
properties[PROP_TITLE] =
g_param_spec_string ("title",
......@@ -678,9 +689,10 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/**
* GtkShortcutsShortcut:direction:
*
* The text direction for which this shortcut is active. If the shortcut
* is used regardless of the text direction, set this property to
* #GTK_TEXT_DIR_NONE.
* The text direction for which this shortcut is active.
*
* If the shortcut is used regardless of the text direction,
* set this property to %GTK_TEXT_DIR_NONE.
*/
properties[PROP_DIRECTION] =
g_param_spec_enum ("direction",
......@@ -706,11 +718,12 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/**
* GtkShortcutsShortcut:action-name:
*
* A detailed action name. If this is set for a shortcut
* of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use
* the accelerators that are associated with the action
* via gtk_application_set_accels_for_action(), and setting
* #GtkShortcutsShortcut:accelerator is not necessary.
* A detailed action name.
*
* If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR,
* then GTK will use the accelerators that are associated with the
* action via [method@Gtk.Application.set_accels_for_action], and
* setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary.
*/
properties[PROP_ACTION_NAME] =
g_param_spec_string ("action-name",
......
......@@ -38,7 +38,7 @@ typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass;
/**
* GtkShortcutType:
* @GTK_SHORTCUT_ACCELERATOR:
* The shortcut is a keyboard accelerator. The #GtkShortcutsShortcut:accelerator
* The shortcut is a keyboard accelerator. The GtkShortcutsShortcut:accelerator
* property will be used.
* @GTK_SHORTCUT_GESTURE_PINCH:
* The shortcut is a pinch gesture. GTK provides an icon and subtitle.
......@@ -53,7 +53,7 @@ typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass;
* @GTK_SHORTCUT_GESTURE_TWO_FINGER_SWIPE_RIGHT:
* The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle.
* @GTK_SHORTCUT_GESTURE:
* The shortcut is a gesture. The #GtkShortcutsShortcut:icon property will be
* The shortcut is a gesture. The GtkShortcutsShortcut:icon property will be
* used.
* @GTK_SHORTCUT_GESTURE_SWIPE_LEFT:
* The shortcut is a swipe gesture. GTK provides an icon and subtitle.
......
......@@ -44,22 +44,21 @@
#include "gtkwidgetprivate.h"
/**
* SECTION:gtkshortcutswindow
* @Title: GtkShortcutsWindow
* @Short_description: Toplevel which shows help for shortcuts
* GtkShortcutsWindow:
*
* A GtkShortcutsWindow shows brief information about the keyboard shortcuts
* and gestures of an application. The shortcuts can be grouped, and you can
* have multiple sections in this window, corresponding to the major modes of
* your application.
* A `GtkShortcutsWindow` shows information about the keyboard shortcuts
* and gestures of an application.
*
* The shortcuts can be grouped, and you can have multiple sections in this
* window, corresponding to the major modes of your application.
*
* Additionally, the shortcuts can be filtered by the current view, to avoid
* showing information that is not relevant in the current application context.
*
* The recommended way to construct a GtkShortcutsWindow is with GtkBuilder,
* by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection
* objects, which contain #GtkShortcutsGroups that in turn contain objects of
* class #GtkShortcutsShortcut.
* The recommended way to construct a `GtkShortcutsWindow` is with
* [class@Gtk.Builder], by populating a `GtkShortcutsWindow` with one or
* more `GtkShortcutsSection` objects, which contain `GtkShortcutsGroups`
* that in turn contain objects of class `GtkShortcutsShortcut`.
*
* # A simple example:
*
......@@ -75,7 +74,7 @@
*
* ![](clocks-shortcuts.png)
*
* This example shows a #GtkShortcutsWindow that has been configured to show only
* This example shows a `GtkShortcutsWindow` that has been configured to show only
* the shortcuts relevant to the "stopwatch" view.
*
* The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/master/demos/gtk-demo/shortcuts-clocks.ui).
......@@ -84,7 +83,7 @@
*
* ![](builder-shortcuts.png)
*
* This example shows a #GtkShortcutsWindow with two sections, "Editor Shortcuts"
* This example shows a `GtkShortcutsWindow` with two sections, "Editor Shortcuts"
* and "Terminal Shortcuts".
*
* The .ui file for this example can be found [here](https://gitlab.gnome.org/GNOME/gtk/tree/master/demos/gtk-demo/shortcuts-builder.ui).
......@@ -746,7 +745,7 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
*
* The name of the section to show.
*
* This should be the section-name of one of the #GtkShortcutsSection
* This should be the section-name of one of the `GtkShortcutsSection`
* objects that are in this shortcuts window.
*/
properties[PROP_SECTION_NAME] =
......@@ -759,8 +758,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
*
* The view name by which to filter the contents.
*
* This should correspond to the #GtkShortcutsGroup:view property of some of
* the #GtkShortcutsGroup objects that are inside this shortcuts window.
* This should correspond to the [property@Gtk.ShortcutsGroup:view]
* property of some of the [class@Gtk.ShortcutsGroup] objects that
* are inside this shortcuts window.
*
* Set this to %NULL to show all groups.
*/
......@@ -774,10 +774,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
/**
* GtkShortcutsWindow::close:
*
* The ::close signal is a
* [keybinding signal][GtkSignalAction]
* which gets emitted when the user uses a keybinding to close
* the window.
* Emitted when the user uses a keybinding to close the window.
*
* This is a [keybinding signal](class.SignalAction.html).
*
* The default binding for this signal is the Escape key.
*/
......@@ -792,9 +791,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
/**
* GtkShortcutsWindow::search:
*
* The ::search signal is a
* [keybinding signal][GtkSignalAction]
* which gets emitted when the user uses a keybinding to start a search.
* Emitted when the user uses a keybinding to start a search.
*
* This is a [keybinding signal](class.SignalAction.html).
*
* The default binding for this signal is Control-F.
*/
......
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