diff --git a/gtk/gtkshortcuttrigger.c b/gtk/gtkshortcuttrigger.c index fab339fe54..2e99c9bc63 100644 --- a/gtk/gtkshortcuttrigger.c +++ b/gtk/gtkshortcuttrigger.c @@ -20,21 +20,19 @@ */ /** - * SECTION:gtkshortcuttrigger - * @Title: GtkShortcutTrigger - * @Short_description: Triggers to track if shortcuts should be activated - * @See_also: #GtkShortcut + * GtkShortcutTrigger: * - * #GtkShortcutTrigger is the object used to track if a #GtkShortcut should be - * activated. For this purpose, gtk_shortcut_trigger_trigger() can be called - * on a #GdkEvent. + * `GtkShortcutTrigger` tracks how a `GtkShortcut` should be activated. * - * #GtkShortcutTriggers contain functions that allow easy presentation to end - * users as well as being printed for debugging. + * To find out if a `GtkShortcutTrigger` triggers, you can call + * [method@Gtk.ShortcutTrigger.trigger] on a `GdkEvent`. * - * All #GtkShortcutTriggers are immutable, you can only specify their properties - * during construction. If you want to change a trigger, you have to replace it - * with a new one. + * `GtkShortcutTriggers` contain functions that allow easy presentation + * to end users as well as being printed for debugging. + * + * All `GtkShortcutTriggers` are immutable, you can only specify their + * properties during construction. If you want to change a trigger, you + * have to replace it with a new one. */ #include "config.h" @@ -86,7 +84,7 @@ gtk_shortcut_trigger_init (GtkShortcutTrigger *self) /** * gtk_shortcut_trigger_trigger: - * @self: a #GtkShortcutTrigger + * @self: a `GtkShortcutTrigger` * @event: the event to check * @enable_mnemonics: %TRUE if mnemonics should trigger. Usually the * value of this property is determined by checking that the passed @@ -95,7 +93,7 @@ gtk_shortcut_trigger_init (GtkShortcutTrigger *self) * Checks if the given @event triggers @self. * * Returns: Whether the event triggered the shortcut - **/ + */ GdkKeyMatch gtk_shortcut_trigger_trigger (GtkShortcutTrigger *self, GdkEvent *event, @@ -110,23 +108,24 @@ gtk_shortcut_trigger_trigger (GtkShortcutTrigger *self, * gtk_shortcut_trigger_parse_string: (constructor) * @string: the string to parse * - * Tries to parse the given string into a trigger. On success, - * the parsed trigger is returned. When parsing failed, %NULL is - * returned. + * Tries to parse the given string into a trigger. + * + * On success, the parsed trigger is returned. + * When parsing failed, %NULL is returned. * * The accepted strings are: * - * - `never`, for #GtkNeverTrigger - * - a string parsed by gtk_accelerator_parse(), for a #GtkKeyvalTrigger, e.g. `C` - * - underscore, followed by a single character, for MnemonicTrigger, e.g. `_l` + * - `never`, for `GtkNeverTrigger` + * - a string parsed by gtk_accelerator_parse(), for a `GtkKeyvalTrigger`, e.g. `C` + * - underscore, followed by a single character, for `GtkMnemonicTrigger`, e.g. `_l` * - two valid trigger strings, separated by a `|` character, for a - * #GtkAlternativeTrigger: `q|w` + * `GtkAlternativeTrigger`: `q|w` * * Note that you will have to escape the `<` and `>` characters when specifying * triggers in XML files, such as GtkBuilder ui files. Use `<` instead of * `<` and `>` instead of `>`. * - * Returns: (nullable) (transfer full): a new #GtkShortcutTrigger + * Returns: (nullable) (transfer full): a new `GtkShortcutTrigger` * or %NULL on error */ GtkShortcutTrigger * @@ -196,10 +195,11 @@ gtk_shortcut_trigger_parse_string (const char *string) /** * gtk_shortcut_trigger_to_string: - * @self: a #GtkShortcutTrigger + * @self: a `GtkShortcutTrigger` * * Prints the given trigger into a human-readable string. - * This is a small wrapper around gtk_shortcut_trigger_print() + * + * This is a small wrapper around [method@Gtk.ShortcutTrigger.print] * to help when debugging. * * Returns: (transfer full): a new string @@ -220,8 +220,8 @@ gtk_shortcut_trigger_to_string (GtkShortcutTrigger *self) /** * gtk_shortcut_trigger_print: - * @self: a #GtkShortcutTrigger - * @string: a #GString to print into + * @self: a `GtkShortcutTrigger` + * @string: a `GString` to print into * * Prints the given trigger into a string for the developer. * This is meant for debugging and logging. @@ -241,12 +241,14 @@ gtk_shortcut_trigger_print (GtkShortcutTrigger *self, /** * gtk_shortcut_trigger_to_label: - * @self: a #GtkShortcutTrigger - * @display: #GdkDisplay to print for + * @self: a `GtkShortcutTrigger` + * @display: `GdkDisplay` to print for * - * Gets textual representation for the given trigger. This - * function is returning a translated string for presentation - * to end users for example in menu items or in help texts. + * Gets textual representation for the given trigger. + * + * This function is returning a translated string for + * presentation to end users for example in menu items + * or in help texts. * * The @display in use may influence the resulting string in * various forms, such as resolving hardware keycodes or by @@ -256,7 +258,7 @@ gtk_shortcut_trigger_print (GtkShortcutTrigger *self, * not guaranteed to stay identical. * * Returns: (transfer full): a new string - **/ + */ char * gtk_shortcut_trigger_to_label (GtkShortcutTrigger *self, GdkDisplay *display) @@ -273,13 +275,14 @@ gtk_shortcut_trigger_to_label (GtkShortcutTrigger *self, /** * gtk_shortcut_trigger_print_label: - * @self: a #GtkShortcutTrigger - * @display: #GdkDisplay to print for - * @string: a #GString to print into + * @self: a `GtkShortcutTrigger` + * @display: `GdkDisplay` to print for + * @string: a `GString` to print into * - * Prints the given trigger into a string. This function is - * returning a translated string for presentation to end users - * for example in menu items or in help texts. + * Prints the given trigger into a string. + * + * This function is returning a translated string for presentation + * to end users for example in menu items or in help texts. * * The @display in use may influence the resulting string in * various forms, such as resolving hardware keycodes or by @@ -306,20 +309,20 @@ gtk_shortcut_trigger_print_label (GtkShortcutTrigger *self, /** * gtk_shortcut_trigger_hash: - * @trigger: (type GtkShortcutTrigger): a #GtkShortcutTrigger + * @trigger: (type GtkShortcutTrigger): a `GtkShortcutTrigger` * - * Generates a hash value for a #GtkShortcutTrigger. + * Generates a hash value for a `GtkShortcutTrigger`. * * The output of this function is guaranteed to be the same for a given - * value only per-process. It may change between different processor - * architectures or even different versions of GTK. Do not use this + * value only per-process. It may change between different processor + * architectures or even different versions of GTK. Do not use this * function as a basis for building protocols or file formats. * * The types of @trigger is #gconstpointer only to allow use of this - * function with #GHashTable. They must each be a #GtkShortcutTrigger. + * function with #GHashTable. They must each be a `GtkShortcutTrigger`. * * Returns: a hash value corresponding to @trigger - **/ + */ guint gtk_shortcut_trigger_hash (gconstpointer trigger) { @@ -332,16 +335,16 @@ gtk_shortcut_trigger_hash (gconstpointer trigger) /** * gtk_shortcut_trigger_equal: - * @trigger1: (type GtkShortcutTrigger): a #GtkShortcutTrigger - * @trigger2: (type GtkShortcutTrigger): a #GtkShortcutTrigger + * @trigger1: (type GtkShortcutTrigger): a `GtkShortcutTrigger` + * @trigger2: (type GtkShortcutTrigger): a `GtkShortcutTrigger` * * Checks if @trigger1 and @trigger2 trigger under the same conditions. * * The types of @one and @two are #gconstpointer only to allow use of this - * function with #GHashTable. They must each be a #GtkShortcutTrigger. + * function with #GHashTable. They must each be a `GtkShortcutTrigger`. * * Returns: %TRUE if @trigger1 and @trigger2 are equal - **/ + */ gboolean gtk_shortcut_trigger_equal (gconstpointer trigger1, gconstpointer trigger2) @@ -351,17 +354,18 @@ gtk_shortcut_trigger_equal (gconstpointer trigger1, /** * gtk_shortcut_trigger_compare: - * @trigger1: (type GtkShortcutTrigger): a #GtkShortcutTrigger - * @trigger2: (type GtkShortcutTrigger): a #GtkShortcutTrigger - * + * @trigger1: (type GtkShortcutTrigger): a `GtkShortcutTrigger` + * @trigger2: (type GtkShortcutTrigger): a `GtkShortcutTrigger` + * * The types of @trigger1 and @trigger2 are #gconstpointer only to allow - * use of this function as a #GCompareFunc. They must each be a - * #GtkShortcutTrigger. + * use of this function as a #GCompareFunc. + * + * They must each be a `GtkShortcutTrigger`. * * Returns: An integer less than, equal to, or greater than zero if * @trigger1 is found, respectively, to be less than, to match, * or be greater than @trigger2. - **/ + */ int gtk_shortcut_trigger_compare (gconstpointer trigger1, gconstpointer trigger2) @@ -475,9 +479,11 @@ gtk_never_trigger_init (GtkNeverTrigger *self) /** * gtk_never_trigger_get: * - * Gets the never trigger. This is a singleton for a trigger - * that never triggers. Use this trigger instead of %NULL - * because it implements all virtual functions. + * Gets the never trigger. + * + * This is a singleton for a trigger that never triggers. + * Use this trigger instead of %NULL because it implements + * all virtual functions. * * Returns: (type GtkNeverTrigger) (transfer none): The never trigger */ @@ -647,7 +653,7 @@ gtk_keyval_trigger_class_init (GtkKeyvalTriggerClass *klass) trigger_class->print_label = gtk_keyval_trigger_print_label; /** - * GtkKeyvalTrigger:keyval: + * GtkKeyvalTrigger:keyval: (attributes org.gtk.Property.get=gtk_keyval_trigger_get_keyval) * * The key value for the trigger. */ @@ -662,7 +668,7 @@ gtk_keyval_trigger_class_init (GtkKeyvalTriggerClass *klass) G_PARAM_READWRITE); /** - * GtkKeyvalTrigger:modifiers: + * GtkKeyvalTrigger:modifiers: (attributes org.gtk.Property.get=gtk_keyval_trigger_get_modifiers) * * The key modifiers for the trigger. */ @@ -689,10 +695,10 @@ gtk_keyval_trigger_init (GtkKeyvalTrigger *self) * @keyval: The keyval to trigger for * @modifiers: the modifiers that need to be present * - * Creates a #GtkShortcutTrigger that will trigger whenever + * Creates a `GtkShortcutTrigger` that will trigger whenever * the key with the given @keyval and @modifiers is pressed. * - * Returns: A new #GtkShortcutTrigger + * Returns: A new `GtkShortcutTrigger` */ GtkShortcutTrigger * gtk_keyval_trigger_new (guint keyval, @@ -705,14 +711,14 @@ gtk_keyval_trigger_new (guint keyval, } /** - * gtk_keyval_trigger_get_modifiers: - * @self: a keyval #GtkShortcutTrigger + * gtk_keyval_trigger_get_modifiers: (attributes org.gtk.Method.get_property=modifiers) + * @self: a keyval `GtkShortcutTrigger` * * Gets the modifiers that must be present to succeed * triggering @self. * * Returns: the modifiers - **/ + */ GdkModifierType gtk_keyval_trigger_get_modifiers (GtkKeyvalTrigger *self) { @@ -722,14 +728,14 @@ gtk_keyval_trigger_get_modifiers (GtkKeyvalTrigger *self) } /** - * gtk_keyval_trigger_get_keyval: - * @self: a keyval #GtkShortcutTrigger + * gtk_keyval_trigger_get_keyval: (attributes org.gtk.Method.get_property=keyval) + * @self: a keyval `GtkShortcutTrigger` * * Gets the keyval that must be pressed to succeed * triggering @self. * * Returns: the keyval - **/ + */ guint gtk_keyval_trigger_get_keyval (GtkKeyvalTrigger *self) { @@ -903,7 +909,7 @@ gtk_mnemonic_trigger_class_init (GtkMnemonicTriggerClass *klass) trigger_class->print_label = gtk_mnemonic_trigger_print_label; /** - * GtkMnemonicTrigger:keyval: + * GtkMnemonicTrigger:keyval: (attributes org.gtk.Property.get=gtk_mnemonic_trigger_get_keyval) * * The key value for the trigger. */ @@ -929,13 +935,13 @@ gtk_mnemonic_trigger_init (GtkMnemonicTrigger *self) * gtk_mnemonic_trigger_new: * @keyval: The keyval to trigger for * - * Creates a #GtkShortcutTrigger that will trigger whenever the key with + * Creates a `GtkShortcutTrigger` that will trigger whenever the key with * the given @keyval is pressed and mnemonics have been activated. * * Mnemonics are activated by calling code when a key event with the right * modifiers is detected. * - * Returns: (transfer full) (type GtkMnemonicTrigger): A new #GtkShortcutTrigger + * Returns: (transfer full) (type GtkMnemonicTrigger): A new `GtkShortcutTrigger` */ GtkShortcutTrigger * gtk_mnemonic_trigger_new (guint keyval) @@ -946,13 +952,13 @@ gtk_mnemonic_trigger_new (guint keyval) } /** - * gtk_mnemonic_trigger_get_keyval: - * @self: a mnemonic #GtkShortcutTrigger + * gtk_mnemonic_trigger_get_keyval: (attributes org.gtk.Method.get_property=keyval) + * @self: a mnemonic `GtkShortcutTrigger` * * Gets the keyval that must be pressed to succeed triggering @self. * * Returns: the keyval - **/ + */ guint gtk_mnemonic_trigger_get_keyval (GtkMnemonicTrigger *self) { @@ -1149,9 +1155,9 @@ gtk_alternative_trigger_class_init (GtkAlternativeTriggerClass *klass) trigger_class->print_label = gtk_alternative_trigger_print_label; /** - * GtkAlternativeTrigger:first: + * GtkAlternativeTrigger:first: (attributes org.gtk.Property.get=gtk_alternative_trigger_get_first) * - * The first #GtkShortcutTrigger to check. + * The first `GtkShortcutTrigger` to check. */ alternative_props[ALTERNATIVE_PROP_FIRST] = g_param_spec_object (I_("first"), @@ -1161,10 +1167,11 @@ gtk_alternative_trigger_class_init (GtkAlternativeTriggerClass *klass) G_PARAM_STATIC_STRINGS | G_PARAM_CONSTRUCT_ONLY | G_PARAM_READWRITE); + /** - * GtkAlternativeTrigger:second: + * GtkAlternativeTrigger:second: (attributes org.gtk.Property.get=gtk_alternative_trigger_get_second) * - * The second #GtkShortcutTrigger to check. + * The second `GtkShortcutTrigger` to check. */ alternative_props[ALTERNATIVE_PROP_SECOND] = g_param_spec_object (I_("second"), @@ -1188,13 +1195,13 @@ gtk_alternative_trigger_init (GtkAlternativeTrigger *self) * @first: (transfer full): The first trigger that may trigger * @second: (transfer full): The second trigger that may trigger * - * Creates a #GtkShortcutTrigger that will trigger whenever + * Creates a `GtkShortcutTrigger` that will trigger whenever * either of the two given triggers gets triggered. * * Note that nesting is allowed, so if you want more than two * alternative, create a new alternative trigger for each option. * - * Returns: a new #GtkShortcutTrigger + * Returns: a new `GtkShortcutTrigger` */ GtkShortcutTrigger * gtk_alternative_trigger_new (GtkShortcutTrigger *first, @@ -1217,15 +1224,17 @@ gtk_alternative_trigger_new (GtkShortcutTrigger *first, } /** - * gtk_alternative_trigger_get_first: - * @self: an alternative #GtkShortcutTrigger + * gtk_alternative_trigger_get_first: (attributes org.gtk.Method.get_property=first) + * @self: an alternative `GtkShortcutTrigger` * * Gets the first of the two alternative triggers that may - * trigger @self. gtk_alternative_trigger_get_second() will - * return the other one. + * trigger @self. + * + * [method@Gtk.AlternativeTrigger.get_second] will return + * the other one. * * Returns: (transfer none): the first alternative trigger - **/ + */ GtkShortcutTrigger * gtk_alternative_trigger_get_first (GtkAlternativeTrigger *self) { @@ -1235,15 +1244,17 @@ gtk_alternative_trigger_get_first (GtkAlternativeTrigger *self) } /** - * gtk_alternative_trigger_get_second: - * @self: an alternative #GtkShortcutTrigger + * gtk_alternative_trigger_get_second: (attributes org.gtk.Method.get_property=second) + * @self: an alternative `GtkShortcutTrigger` * * Gets the second of the two alternative triggers that may - * trigger @self. gtk_alternative_trigger_get_first() will - * return the other one. + * trigger @self. + * + * [method@Gtk.AlternativeTrigger.get_first] will return + * the other one. * * Returns: (transfer none): the second alternative trigger - **/ + */ GtkShortcutTrigger * gtk_alternative_trigger_get_second (GtkAlternativeTrigger *self) { diff --git a/gtk/gtkshortcuttrigger.h b/gtk/gtkshortcuttrigger.h index 8fae538f29..7d42489d91 100644 --- a/gtk/gtkshortcuttrigger.h +++ b/gtk/gtkshortcuttrigger.h @@ -30,12 +30,6 @@ G_BEGIN_DECLS #define GTK_TYPE_SHORTCUT_TRIGGER (gtk_shortcut_trigger_get_type ()) -/** - * GtkShortcutTrigger: - * - * A trigger for a key shortcut. - */ - GDK_AVAILABLE_IN_ALL GDK_DECLARE_INTERNAL_TYPE (GtkShortcutTrigger, gtk_shortcut_trigger, GTK, SHORTCUT_TRIGGER, GObject)