AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

shortcutswindow: Convert docs

Browse Source
This commit is contained in:
Matthias Clasen 2021-02-26 23:16:11 -05:00 committed by Emmanuele Bassi
parent 0d238f4c99
commit 9104420c87
5 changed files with 103 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

19
gtk/gtkshortcutsgroup.c
View File

@ -30,16 +30,16 @@
#include "gtksizegroup.h" #include "gtksizegroup.h"
/** /**
* SECTION:gtkshortcutsgroup * GtkShortcutsGroup:
* @Title: GtkShortcutsGroup
* @Short_description: Represents a group of shortcuts in a GtkShortcutsWindow
* *
* A GtkShortcutsGroup represents a group of related keyboard shortcuts * A `GtkShortcutsGroup` represents a group of related keyboard shortcuts
* or gestures. The group has a title. It may optionally be associated with * or gestures.
* a view of the application, which can be used to show only relevant shortcuts *
* 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. * 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 struct _GtkShortcutsGroup
@ -284,8 +284,9 @@ gtk_shortcuts_group_class_init (GtkShortcutsGroupClass *klass)
* GtkShortcutsGroup:view: * GtkShortcutsGroup:view:
* *
* An optional view that the shortcuts in this group are relevant for. * 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. * Set this to %NULL to make the group always visible.
*/ */

55
gtk/gtkshortcutssection.c
View File

@ -38,20 +38,21 @@
#include "gtkintl.h" #include "gtkintl.h"
/** /**
* SECTION:gtkshortcutssection * GtkShortcutsSection:
* @Title: GtkShortcutsSection
* @Short_description: Represents an application mode in a GtkShortcutsWindow
* *
* A GtkShortcutsSection collects all the keyboard shortcuts and gestures * A `GtkShortcutsSection` collects all the keyboard shortcuts and gestures
* for a major application mode. If your application needs multiple sections, * for a major application mode.
* 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.
* *
* The #GtkShortcutsSection:max-height property can be used to influence how * If your application needs multiple sections, you should give each
* the groups in the section are distributed over pages and columns. * 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 struct _GtkShortcutsSection
@ -286,9 +287,10 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
* GtkShortcutsSection:section-name: * GtkShortcutsSection:section-name:
* *
* A unique name to identify this section among the sections * A unique name to identify this section among the sections
* added to the GtkShortcutsWindow. Setting the #GtkShortcutsWindow:section-name * added to the `GtkShortcutsWindow`.
* property to this string will make this section shown in 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] = properties[PROP_SECTION_NAME] =
g_param_spec_string ("section-name", P_("Section Name"), P_("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: * GtkShortcutsSection:view-name:
* *
* A view name to filter the groups in this section by. * A view name to filter the groups in this section by.
* See #GtkShortcutsGroup:view.
* *
* Applications are expected to use the #GtkShortcutsWindow:view-name * See [property@Gtk.ShortcutsGroup:view].
* property for this purpose. *
* Applications are expected to use the
* [property@Gtk.ShortcutsWindow:view-name] property
* for this purpose.
*/ */
properties[PROP_VIEW_NAME] = properties[PROP_VIEW_NAME] =
g_param_spec_string ("view-name", P_("View Name"), P_("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: * GtkShortcutsSection:title:
* *
* The string to show in the section selector of the GtkShortcutsWindow * 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 * for this section.
* set a title, since the section selector will not be shown in this case. *
* 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] = properties[PROP_TITLE] =
g_param_spec_string ("title", P_("Title"), P_("Title"), g_param_spec_string ("title", P_("Title"), P_("Title"),
@ -324,10 +330,11 @@ gtk_shortcuts_section_class_init (GtkShortcutsSectionClass *klass)
/** /**
* GtkShortcutsSection:max-height: * GtkShortcutsSection:max-height:
* *
* The maximum number of lines to allow per column. This property can * The maximum number of lines to allow per column.
* be used to influence how the groups in this section are distributed *
* across pages and columns. The default value of 15 should work in * This property can be used to influence how the groups in this
* most cases. * section are distributed across pages and columns. The default
* value of 15 should work in most cases.
*/ */
properties[PROP_MAX_HEIGHT] = properties[PROP_MAX_HEIGHT] =
g_param_spec_uint ("max-height", P_("Maximum Height"), P_("Maximum Height"), g_param_spec_uint ("max-height", P_("Maximum Height"), P_("Maximum Height"),

63
gtk/gtkshortcutsshortcut.c
View File

@ -32,12 +32,12 @@
#include "gtktypebuiltins.h" #include "gtktypebuiltins.h"
/** /**
* SECTION:gtkshortcutsshortcut * GtkShortcutsShortcut:
* @Title: GtkShortcutsShortcut
* @Short_description: Represents a keyboard shortcut in a GtkShortcutsWindow
* *
* A GtkShortcutsShortcut represents a single keyboard shortcut or gesture * A `GtkShortcutsShortcut` represents a single keyboard shortcut or gesture
* with a short text. This widget is only meant to be used with #GtkShortcutsWindow. * with a short text.
*
* This widget is only meant to be used with `GtkShortcutsWindow`.
*/ */
struct _GtkShortcutsShortcut struct _GtkShortcutsShortcut
@ -551,24 +551,30 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/** /**
* GtkShortcutsShortcut:accelerator: * GtkShortcutsShortcut:accelerator:
* *
* The accelerator(s) represented by this object. This property is used * The accelerator(s) represented by this object.
* if #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_ACCELERATOR.
* *
* The syntax of this property is (an extension of) the syntax understood by * This property is used if [property@Gtk.ShortcutsShortcut:shortcut-type]
* gtk_accelerator_parse(). Multiple accelerators can be specified by separating * is set to %GTK_SHORTCUT_ACCELERATOR.
* 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. * The syntax of this property is (an extension of) the syntax understood
* Sequences of keys can be specified using a + or & between the keys. * 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.
*
* 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: * Examples:
*
* - A single shortcut: <ctl><alt>delete * - A single shortcut: <ctl><alt>delete
* - Two alternative shortcuts: <shift>a Home * - Two alternative shortcuts: <shift>a Home
* - A range of shortcuts: <alt>1...<alt>9 * - A range of shortcuts: <alt>1...<alt>9
* - Several keys pressed together: Control_L&Control_R * - Several keys pressed together: Control_L&Control_R
* - A sequence of shortcuts or keys: <ctl>c+<ctl>x * - 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 "+" instead of "&" when the keys may (or have to be) pressed
* use t+t for 'press the t key twice'). * 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 * Note that <, > and & need to be escaped as &lt;, &gt; and &amp; when used
* in .ui files. * in .ui files.
@ -583,8 +589,11 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/** /**
* GtkShortcutsShortcut:icon: * GtkShortcutsShortcut:icon:
* *
* An icon to represent the shortcut or gesture. This property is used if * An icon to represent the shortcut or gesture.
* #GtkShortcutsShortcut:shortcut-type is set to #GTK_SHORTCUT_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. * For the other predefined gesture types, GTK provides an icon on its own.
*/ */
properties[PROP_ICON] = properties[PROP_ICON] =
@ -610,7 +619,9 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
* GtkShortcutsShortcut:title: * GtkShortcutsShortcut:title:
* *
* The textual description for the shortcut or gesture represented by * 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] = properties[PROP_TITLE] =
g_param_spec_string ("title", g_param_spec_string ("title",
@ -678,9 +689,10 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/** /**
* GtkShortcutsShortcut:direction: * GtkShortcutsShortcut:direction:
* *
* The text direction for which this shortcut is active. If the shortcut * The text direction for which this shortcut is active.
* is used regardless of the text direction, set this property to *
* #GTK_TEXT_DIR_NONE. * If the shortcut is used regardless of the text direction,
* set this property to %GTK_TEXT_DIR_NONE.
*/ */
properties[PROP_DIRECTION] = properties[PROP_DIRECTION] =
g_param_spec_enum ("direction", g_param_spec_enum ("direction",
@ -706,11 +718,12 @@ gtk_shortcuts_shortcut_class_init (GtkShortcutsShortcutClass *klass)
/** /**
* GtkShortcutsShortcut:action-name: * GtkShortcutsShortcut:action-name:
* *
* A detailed action name. If this is set for a shortcut * A detailed action name.
* of type %GTK_SHORTCUT_ACCELERATOR, then GTK will use *
* the accelerators that are associated with the action * If this is set for a shortcut of type %GTK_SHORTCUT_ACCELERATOR,
* via gtk_application_set_accels_for_action(), and setting * then GTK will use the accelerators that are associated with the
* #GtkShortcutsShortcut:accelerator is not necessary. * action via [method@Gtk.Application.set_accels_for_action], and
* setting [property@Gtk.ShortcutsShortcut:accelerator] is not necessary.
*/ */
properties[PROP_ACTION_NAME] = properties[PROP_ACTION_NAME] =
g_param_spec_string ("action-name", g_param_spec_string ("action-name",

4
gtk/gtkshortcutsshortcut.h
View File

@ -38,7 +38,7 @@ typedef struct _GtkShortcutsShortcutClass GtkShortcutsShortcutClass;
/** /**
* GtkShortcutType: * GtkShortcutType:
* @GTK_SHORTCUT_ACCELERATOR: * @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. * property will be used.
* @GTK_SHORTCUT_GESTURE_PINCH: * @GTK_SHORTCUT_GESTURE_PINCH:
* The shortcut is a pinch gesture. GTK provides an icon and subtitle. * 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: * @GTK_SHORTCUT_GESTURE_TWO_FINGER_SWIPE_RIGHT:
* The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle. * The shortcut is a two-finger swipe gesture. GTK provides an icon and subtitle.
* @GTK_SHORTCUT_GESTURE: * @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. * used.
* @GTK_SHORTCUT_GESTURE_SWIPE_LEFT: * @GTK_SHORTCUT_GESTURE_SWIPE_LEFT:
* The shortcut is a swipe gesture. GTK provides an icon and subtitle. * The shortcut is a swipe gesture. GTK provides an icon and subtitle.

45
gtk/gtkshortcutswindow.c
View File

@ -44,22 +44,21 @@
#include "gtkwidgetprivate.h" #include "gtkwidgetprivate.h"
/** /**
* SECTION:gtkshortcutswindow * GtkShortcutsWindow:
* @Title: GtkShortcutsWindow
* @Short_description: Toplevel which shows help for shortcuts
* *
* A GtkShortcutsWindow shows brief information about the keyboard shortcuts * A `GtkShortcutsWindow` shows information about the keyboard shortcuts
* and gestures of an application. The shortcuts can be grouped, and you can * and gestures of an application.
* have multiple sections in this window, corresponding to the major modes of *
* your 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 * Additionally, the shortcuts can be filtered by the current view, to avoid
* showing information that is not relevant in the current application context. * showing information that is not relevant in the current application context.
* *
* The recommended way to construct a GtkShortcutsWindow is with GtkBuilder, * The recommended way to construct a `GtkShortcutsWindow` is with
* by populating a #GtkShortcutsWindow with one or more #GtkShortcutsSection * [class@Gtk.Builder], by populating a `GtkShortcutsWindow` with one or
* objects, which contain #GtkShortcutsGroups that in turn contain objects of * more `GtkShortcutsSection` objects, which contain `GtkShortcutsGroups`
* class #GtkShortcutsShortcut. * that in turn contain objects of class `GtkShortcutsShortcut`.
* *
* # A simple example: * # A simple example:
* *
@ -75,7 +74,7 @@
* *
* ![](clocks-shortcuts.png) * ![](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 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). * 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) * ![](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". * 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). * 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. * 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. * objects that are in this shortcuts window.
*/ */
properties[PROP_SECTION_NAME] = properties[PROP_SECTION_NAME] =
@ -759,8 +758,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
* *
* The view name by which to filter the contents. * The view name by which to filter the contents.
* *
* This should correspond to the #GtkShortcutsGroup:view property of some of * This should correspond to the [property@Gtk.ShortcutsGroup:view]
* the #GtkShortcutsGroup objects that are inside this shortcuts window. * property of some of the [class@Gtk.ShortcutsGroup] objects that
* are inside this shortcuts window.
* *
* Set this to %NULL to show all groups. * Set this to %NULL to show all groups.
*/ */
@ -774,10 +774,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
/** /**
* GtkShortcutsWindow::close: * GtkShortcutsWindow::close:
* *
* The ::close signal is a * Emitted when the user uses a keybinding to close the window.
* [keybinding signal][GtkSignalAction] *
* which gets emitted when the user uses a keybinding to close * This is a [keybinding signal](class.SignalAction.html).
* the window.
* *
* The default binding for this signal is the Escape key. * The default binding for this signal is the Escape key.
*/ */
@ -792,9 +791,9 @@ gtk_shortcuts_window_class_init (GtkShortcutsWindowClass *klass)
/** /**
* GtkShortcutsWindow::search: * GtkShortcutsWindow::search:
* *
* The ::search signal is a * Emitted when the user uses a keybinding to start a search.
* [keybinding signal][GtkSignalAction] *
* which gets 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. * The default binding for this signal is Control-F.
*/ */