mirror of
https://gitlab.gnome.org/GNOME/gtk.git
synced 2024-12-26 13:41:07 +00:00
shortcuttrigger: Convert docs
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
9fbe61e01f
commit
9d95c5a26d
@ -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. `<Control>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. `<Control>C`
|
||||
* - underscore, followed by a single character, for `GtkMnemonicTrigger`, e.g. `_l`
|
||||
* - two valid trigger strings, separated by a `|` character, for a
|
||||
* #GtkAlternativeTrigger: `<Control>q|<Control>w`
|
||||
* `GtkAlternativeTrigger`: `<Control>q|<Control>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)
|
||||
{
|
||||
|
||||
@ -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)
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user