docs: Improve markup for keys

Consistently use <kbd>x</kbd> to render keys in the docs
and use + for key combinations.

diff --git a/docs/reference/gtk/input-handling.md b/docs/reference/gtk/input-handling.md
index bc40e5d12d5abb5eb94645fd6dbadabb0ae43c87..59983f092d4551a986b98ee82f371575f5c3c19d 100644 (file)
--- a/docs/reference/gtk/input-handling.md
+++ b/docs/reference/gtk/input-handling.md
@@ -103,14 +103,14 @@ fields, but e.g. buttons can take the focus too.
 
 Input widgets can be given the focus by clicking on them, but focus
 can also be moved around with certain key events (this is known as
-“keyboard navigation”). GTK reserves the Tab key to move the focus
-to the next location, and Shift-Tab to move it back to the previous
+“keyboard navigation”). GTK reserves the <kbd>Tab</kbd> key to move the focus
+to the next location, and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move it back to the previous
 one. In addition many containers allow “directional navigation” with
 the arrow keys.
 
 Many widgets can be “activated” to trigger and action. E.g., you can
 activate a button or switch by clicking on them, but you can also
-activate them with the keyboard, by using the Enter or Space keys.
+activate them with the keyboard, by using the <kbd>Enter</kbd> or <kbd>␣</kbd> keys.
 
 Apart from keyboard navigation, activation and directly typing into
 entries or text views, GTK widgets can use key events for activating

diff --git a/gtk/gtkbutton.c b/gtk/gtkbutton.c
index 318f68f30869d990384628c008cb3bc047adbcbd..d85586c82ebe1387494e7641c0fdde557f029b73 100644 (file)
--- a/gtk/gtkbutton.c
+++ b/gtk/gtkbutton.c
@@ -288,6 +288,9 @@ gtk_button_class_init (GtkButtonClass *klass)
    *
    * This is an action signal. Applications should never connect
    * to this signal, but use the [signal@Gtk.Button::clicked] signal.
+   *
+   * The default bindings for this signal are all forms of the
+   * <kbd>␣</kbd> and <kbd>Enter</kbd> keys.
    */
   button_signals[ACTIVATE] =
     g_signal_new (I_("activate"),
@@ -669,7 +672,8 @@ gtk_button_new_from_icon_name (const char *icon_name)
  * If characters in @label are preceded by an underscore, they are underlined.
  * If you need a literal underscore character in a label, use “__” (two
  * underscores). The first underlined character represents a keyboard
- * accelerator called a mnemonic. Pressing Alt and that key activates the button.
+ * accelerator called a mnemonic. Pressing <kbd>Alt</kbd> and that key
+ * activates the button.
  *
  * Returns: a new `GtkButton`
  */

diff --git a/gtk/gtkcheckbutton.c b/gtk/gtkcheckbutton.c
index a4a24fa8be14f160fead728597bd036253a8ef8f..b639f78faa5e0939ecc388841b5158d0f3445f46 100644 (file)
--- a/gtk/gtkcheckbutton.c
+++ b/gtk/gtkcheckbutton.c
@@ -672,6 +672,9 @@ gtk_check_button_class_init (GtkCheckButtonClass *class)
    * Applications should never connect to this signal, but use the
    * [signal@Gtk.CheckButton::toggled] signal.
    *
+   * The default bindings for this signal are all forms of the
+   * <kbd>␣</kbd> and <kbd>Enter</kbd> keys.
+   *
    * Since: 4.2
    */
   signals[ACTIVATE] =

diff --git a/gtk/gtklabel.c b/gtk/gtklabel.c
index 49908566dc78f6f6d580c9501b1597c7dcf37a50..3df6d2683e7aad25000a87fba5a1d0c93fdefeed 100644 (file)
--- a/gtk/gtklabel.c
+++ b/gtk/gtklabel.c
@@ -2237,9 +2237,11 @@ gtk_label_class_init (GtkLabelClass *class)
    * the variant with the Shift modifier extends the selection,
    * the variant without the Shift modifier does not.
    * There are too many key combinations to list them all here.
-   * - Arrow keys move by individual characters/lines
-   * - Ctrl-arrow key combinations move by words/paragraphs
-   * - Home/End keys move to the ends of the buffer
+   *
+   * - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd>
+   *   move by individual characters/lines
+   * - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs
+   * - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer
    */
   signals[MOVE_CURSOR] =
     g_signal_new (I_("move-cursor"),
@@ -2261,7 +2263,7 @@ gtk_label_class_init (GtkLabelClass *class)
    *
    * The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html).
    *
-   * The default binding for this signal is Ctrl-c.
+   * The default binding for this signal is <kbd>Ctrl</kbd>+<kbd>c</kbd>.
    */
   signals[COPY_CLIPBOARD] =
     g_signal_new (I_("copy-clipboard"),
@@ -2283,7 +2285,7 @@ gtk_label_class_init (GtkLabelClass *class)
      * Applications may also emit the signal with g_signal_emit_by_name()
      * if they need to control activation of URIs programmatically.
      *
-     * The default bindings for this signal are all forms of the Enter key.
+     * The default bindings for this signal are all forms of the <kbd>Enter</kbd> key.
      */
     signals[ACTIVATE_CURRENT_LINK] =
       g_signal_new_class_handler (I_("activate-current-link"),
@@ -2361,7 +2363,8 @@ gtk_label_class_init (GtkLabelClass *class)
   /**
    * GtkLabel:use-underline: (attributes org.gtk.Property.get=gtk_label_get_use_underline org.gtk.Property.set=gtk_label_set_use_underline)
    *
-   * %TRUE if the text of the label indicates a mnemonic with _.
+   * %TRUE if the text of the label indicates a mnemonic with an _
+   * before the mnemonic character.
    */
   label_props[PROP_USE_UNDERLINE] =
       g_param_spec_boolean ("use-underline", NULL, NULL,

diff --git a/gtk/gtktext.c b/gtk/gtktext.c
index 53335ced0535818a9812f316e79127249372dbae..98733b0f3602ed711b0e035a55116d8ecd1ab408 100644 (file)
--- a/gtk/gtktext.c
+++ b/gtk/gtktext.c
@@ -982,7 +982,7 @@ gtk_text_class_init (GtkTextClass *class)
    * GtkText::activate:
    * @self: The widget on which the signal is emitted
    *
-   * Emitted when the user hits the Enter key.
+   * Emitted when the user hits the <kbd>Enter</kbd> key.
    *
    * The default bindings for this signal are all forms
    * of the <kbd>Enter</kbd> key.
@@ -1021,8 +1021,8 @@ gtk_text_class_init (GtkTextClass *class)
    *
    * - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd>
    *   move by individual characters/lines
-   * - <kbd>Ctrl</kbd>-<kbd>→</kbd>, etc. move by words/paragraphs
-   * - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the buffer
+   * - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs
+   * - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer
    */
   signals[MOVE_CURSOR] =
     g_signal_new (I_("move-cursor"),
@@ -1073,7 +1073,7 @@ gtk_text_class_init (GtkTextClass *class)
    * of characters.
    *
    * The default bindings for this signal are <kbd>Delete</kbd>
-   * for deleting a character and <kbd>Ctrl</kbd>-<kbd>Delete</kbd>
+   * for deleting a character and <kbd>Ctrl</kbd>+<kbd>Delete</kbd>
    * for deleting a word.
    */
   signals[DELETE_FROM_CURSOR] =
@@ -1096,7 +1096,7 @@ gtk_text_class_init (GtkTextClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Backspace</kbd> and <kbd>Shift</kbd>-<kbd>Backspace</kbd>.
+   * <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>.
    */
   signals[BACKSPACE] =
     g_signal_new (I_("backspace"),
@@ -1116,8 +1116,8 @@ gtk_text_class_init (GtkTextClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>x</kbd> and
-   * <kbd>Shift</kbd>-<kbd>Delete</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>x</kbd> and
+   * <kbd>Shift</kbd>+<kbd>Delete</kbd>.
    */
   signals[CUT_CLIPBOARD] =
     g_signal_new (I_("cut-clipboard"),
@@ -1137,8 +1137,8 @@ gtk_text_class_init (GtkTextClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>c</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>Insert</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>c</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>Insert</kbd>.
    */
   signals[COPY_CLIPBOARD] =
     g_signal_new (I_("copy-clipboard"),
@@ -1158,7 +1158,7 @@ gtk_text_class_init (GtkTextClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>v</kbd> and <kbd>Shift</kbd>-<kbd>Insert</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>v</kbd> and <kbd>Shift</kbd>+<kbd>Insert</kbd>.
    */
   signals[PASTE_CLIPBOARD] =
     g_signal_new (I_("paste-clipboard"),
@@ -1218,8 +1218,8 @@ gtk_text_class_init (GtkTextClass *class)
    * This is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>.</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>;</kbd>
+   * <kbd>Ctrl</kbd>+<kbd>.</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>;</kbd>
    */
   signals[INSERT_EMOJI] =
     g_signal_new (I_("insert-emoji"),

diff --git a/gtk/gtktextview.c b/gtk/gtktextview.c
index 65b4816bffa8d075bac3ef402d1ec2fb069b4d46..465e5cd25b54511b654dff9a480d26e4ab4202fb 100644 (file)
--- a/gtk/gtktextview.c
+++ b/gtk/gtktextview.c
@@ -1171,10 +1171,10 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    *
    * - <kbd>←</kbd>, <kbd>→</kbd>, <kbd>↑</kbd>, <kbd>↓</kbd>
    *   move by individual characters/lines
-   * - <kbd>Ctrl</kbd>-<kbd>→</kbd>, etc. move by words/paragraphs
-   * - <kbd>Home</kbd>, <kbd>End</kbd> move to the ends of the buffer
-   * - <kbd>PgUp</kbd>, <kbd>PgDn</kbd> move vertically by pages
-   * - <kbd>Ctrl</kbd>-<kbd>PgUp</kbd>, <kbd>Ctrl</kbd>-<kbd>PgDn</kbd>
+   * - <kbd>Ctrl</kbd>+<kbd>←</kbd>, etc. move by words/paragraphs
+   * - <kbd>Home</kbd> and <kbd>End</kbd> move to the ends of the buffer
+   * - <kbd>PgUp</kbd> and <kbd>PgDn</kbd> move vertically by pages
+   * - <kbd>Ctrl</kbd>+<kbd>PgUp</kbd> and <kbd>Ctrl</kbd>+<kbd>PgDn</kbd>
    *   move horizontally by pages
    */
   signals[MOVE_CURSOR] =
@@ -1280,8 +1280,8 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * of characters.
    *
    * The default bindings for this signal are <kbd>Delete</kbd> for
-   * deleting a character, <kbd>Ctrl</kbd>-<kbd>Delete</kbd> for
-   * deleting a word and <kbd>Ctrl</kbd>-<kbd>Backspace</kbd> for
+   * deleting a character, <kbd>Ctrl</kbd>+<kbd>Delete</kbd> for
+   * deleting a word and <kbd>Ctrl</kbd>+<kbd>Backspace</kbd> for
    * deleting a word backwards.
    */
   signals[DELETE_FROM_CURSOR] =
@@ -1307,7 +1307,7 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::backspace signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Backspace</kbd> and <kbd>Shift</kbd>-<kbd>Backspace</kbd>.
+   * <kbd>Backspace</kbd> and <kbd>Shift</kbd>+<kbd>Backspace</kbd>.
    */
   signals[BACKSPACE] =
     g_signal_new (I_("backspace"),
@@ -1327,8 +1327,8 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::cut-clipboard signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>x</kbd> and
-   * <kbd>Shift</kbd>-<kbd>Delete</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>x</kbd> and
+   * <kbd>Shift</kbd>+<kbd>Delete</kbd>.
    */
   signals[CUT_CLIPBOARD] =
     g_signal_new (I_("cut-clipboard"),
@@ -1348,8 +1348,8 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::copy-clipboard signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>c</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>Insert</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>c</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>Insert</kbd>.
    */
   signals[COPY_CLIPBOARD] =
     g_signal_new (I_("copy-clipboard"),
@@ -1370,8 +1370,8 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::paste-clipboard signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>v</kbd> and
-   * <kbd>Shift</kbd>-<kbd>Insert</kbd>.
+   * <kbd>Ctrl</kbd>+<kbd>v</kbd> and
+   * <kbd>Shift</kbd>+<kbd>Insert</kbd>.
    */
   signals[PASTE_CLIPBOARD] =
     g_signal_new (I_("paste-clipboard"),
@@ -1411,10 +1411,10 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::select-all signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>a</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>/</kbd> for selecting and
-   * <kbd>Shift</kbd>-<kbd>Ctrl</kbd>-<kbd>a</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>\</kbd> for unselecting.
+   * <kbd>Ctrl</kbd>+<kbd>a</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>/</kbd> for selecting and
+   * <kbd>Shift</kbd>+<kbd>Ctrl</kbd>+<kbd>a</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>\</kbd> for unselecting.
    */
   signals[SELECT_ALL] =
     g_signal_new_class_handler (I_("select-all"),
@@ -1507,8 +1507,8 @@ gtk_text_view_class_init (GtkTextViewClass *klass)
    * The ::insert-emoji signal is a [keybinding signal](class.SignalAction.html).
    *
    * The default bindings for this signal are
-   * <kbd>Ctrl</kbd>-<kbd>.</kbd> and
-   * <kbd>Ctrl</kbd>-<kbd>;</kbd>
+   * <kbd>Ctrl</kbd>+<kbd>.</kbd> and
+   * <kbd>Ctrl</kbd>+<kbd>;</kbd>
    */
   signals[INSERT_EMOJI] =
     g_signal_new (I_("insert-emoji"),
@@ -7173,6 +7173,8 @@ gtk_text_view_set_overwrite (GtkTextView *text_view,
  * If @accepts_tab is %TRUE, a tab character is inserted. If @accepts_tab
  * is %FALSE the keyboard focus is moved to the next widget in the focus
  * chain.
+ *
+ * Focus can always be moved using <kbd>Ctrl</kbd>+<kbd>Tab</kbd>.
  */
 void
 gtk_text_view_set_accepts_tab (GtkTextView *text_view,

diff --git a/gtk/gtkwidget.c b/gtk/gtkwidget.c
index 2f510650a014e45796faa9c90864cce2170789e4..162beee68ca231e5b10d215e3788ac2b38bb8acd 100644 (file)
--- a/gtk/gtkwidget.c
+++ b/gtk/gtkwidget.c
@@ -1837,6 +1837,11 @@ gtk_widget_class_init (GtkWidgetClass *klass)
    * @direction: the direction of the focus move
    *
    * Emitted when the focus is moved.
+   *
+   * The ::move-focus signal is a [keybinding signal](class.SignalAction.html).
+   *
+   * The default bindings for this signal are <kbd>Tab</kbd> to move forward,
+   * and <kbd>Shift</kbd>+<kbd>Tab</kbd> to move backward.
    */
   widget_signals[MOVE_FOCUS] =
     g_signal_new (I_("move-focus"),