diff --git a/gtk/gtkshortcutsgroup.c b/gtk/gtkshortcutsgroup.c index 07abe4f535..4c8cebd703 100644 --- a/gtk/gtkshortcutsgroup.c +++ b/gtk/gtkshortcutsgroup.c @@ -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. */ diff --git a/gtk/gtkshortcutssection.c b/gtk/gtkshortcutssection.c index 6d44a42a7e..1e9038a240 100644 --- a/gtk/gtkshortcutssection.c +++ b/gtk/gtkshortcutssection.c @@ -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"), diff --git a/gtk/gtkshortcutsshortcut.c b/gtk/gtkshortcutsshortcut.c index dcef5d51a1..d04e367198 100644 --- a/gtk/gtkshortcutsshortcut.c +++ b/gtk/gtkshortcutsshortcut.c @@ -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. * - * 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. + * 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. + * + * 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: delete * - Two alternative shortcuts: a Home * - A range of shortcuts: 1...9 * - Several keys pressed together: Control_L&Control_R * - A sequence of shortcuts or keys: c+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 <, > and & 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", diff --git a/gtk/gtkshortcutsshortcut.h b/gtk/gtkshortcutsshortcut.h index eb47ffffaf..5846d2c287 100644 --- a/gtk/gtkshortcutsshortcut.h +++ b/gtk/gtkshortcutsshortcut.h @@ -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. diff --git a/gtk/gtkshortcutswindow.c b/gtk/gtkshortcutswindow.c index ea0032bc26..632ad964cd 100644 --- a/gtk/gtkshortcutswindow.c +++ b/gtk/gtkshortcutswindow.c @@ -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. */