forked from AuroraMiddleware/gtk
padcontroller: Convert docs
This commit is contained in:
Matthias Clasen
Emmanuele Bassi
parent
7606329617
commit
d5d0cf61b9
@ -18,53 +18,55 @@
|
||||
*/
|
||||
|
||||
/**
|
||||
* SECTION:gtkpadcontroller
|
||||
* @Short_description: Controller for drawing tablet pads
|
||||
* @Title: GtkPadController
|
||||
* @See_also: #GtkEventController, #GdkDevicePad
|
||||
* GtkPadController:
|
||||
*
|
||||
* #GtkPadController is an event controller for the pads found in drawing
|
||||
* tablets (The collection of buttons and tactile sensors often found around
|
||||
* the stylus-sensitive area).
|
||||
* `GtkPadController` is an event controller for the pads found in drawing
|
||||
* tablets.
|
||||
*
|
||||
* Pads are the collection of buttons and tactile sensors often found around
|
||||
* the stylus-sensitive area.
|
||||
*
|
||||
* These buttons and sensors have no implicit meaning, and by default they
|
||||
* perform no action, this event controller is provided to map those to
|
||||
* #GAction objects, thus letting the application give those a more semantic
|
||||
* meaning.
|
||||
* perform no action. `GtkPadController` is provided to map those to
|
||||
* `GAction` objects, thus letting the application give them a more
|
||||
* semantic meaning.
|
||||
*
|
||||
* Buttons and sensors are not constrained to triggering a single action, some
|
||||
* %GDK_SOURCE_TABLET_PAD devices feature multiple "modes", all these input
|
||||
* elements have one current mode, which may determine the final action
|
||||
* being triggered. Pad devices often divide buttons and sensors into groups,
|
||||
* all elements in a group share the same current mode, but different groups
|
||||
* may have different modes. See gdk_device_pad_get_n_groups() and
|
||||
* gdk_device_pad_get_group_n_modes().
|
||||
* Buttons and sensors are not constrained to triggering a single action,
|
||||
* some %GDK_SOURCE_TABLET_PAD devices feature multiple "modes". All these
|
||||
* input elements have one current mode, which may determine the final action
|
||||
* being triggered.
|
||||
*
|
||||
* Pad devices often divide buttons and sensors into groups. All elements
|
||||
* in a group share the same current mode, but different groups may have
|
||||
* different modes. See [method@Gdk.DevicePad.get_n_groups] and
|
||||
* [method@Gdk.DevicePad.get_group_n_modes].
|
||||
*
|
||||
* Each of the actions that a given button/strip/ring performs for a given
|
||||
* mode is defined by #GtkPadActionEntry, it contains an action name that
|
||||
* will be looked up in the given #GActionGroup and activated whenever the
|
||||
* specified input element and mode are triggered.
|
||||
* mode is defined by a [struct@Gtk.PadActionEntry]. It contains an action
|
||||
* name that will be looked up in the given `GActionGroup` and activated
|
||||
* whenever the specified input element and mode are triggered.
|
||||
*
|
||||
* A simple example of #GtkPadController usage, assigning button 1 in all
|
||||
* A simple example of `GtkPadController` usage: Assigning button 1 in all
|
||||
* modes and pad devices to an "invert-selection" action:
|
||||
* |[
|
||||
* GtkPadActionEntry *pad_actions[] = {
|
||||
* { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
|
||||
* …
|
||||
* };
|
||||
*
|
||||
* ```c
|
||||
* GtkPadActionEntry *pad_actions[] = {
|
||||
* { GTK_PAD_ACTION_BUTTON, 1, -1, "Invert selection", "pad-actions.invert-selection" },
|
||||
* …
|
||||
* action_group = g_simple_action_group_new ();
|
||||
* action = g_simple_action_new ("pad-actions.invert-selection", NULL);
|
||||
* g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
|
||||
* g_action_map_add_action (G_ACTION_MAP (action_group), action);
|
||||
* …
|
||||
* pad_controller = gtk_pad_controller_new (action_group, NULL);
|
||||
* ]|
|
||||
* };
|
||||
*
|
||||
* …
|
||||
* action_group = g_simple_action_group_new ();
|
||||
* action = g_simple_action_new ("pad-actions.invert-selection", NULL);
|
||||
* g_signal_connect (action, "activate", on_invert_selection_activated, NULL);
|
||||
* g_action_map_add_action (G_ACTION_MAP (action_group), action);
|
||||
* …
|
||||
* pad_controller = gtk_pad_controller_new (action_group, NULL);
|
||||
* ```
|
||||
*
|
||||
* The actions belonging to rings/strips will be activated with a parameter
|
||||
* of type %G_VARIANT_TYPE_DOUBLE bearing the value of the given axis, it
|
||||
* is required that those are made stateful and accepting this #GVariantType.
|
||||
* is required that those are made stateful and accepting this `GVariantType`.
|
||||
*/
|
||||
|
||||
#include "config.h"
|
||||
@ -389,24 +391,26 @@ gtk_pad_controller_init (GtkPadController *controller)
|
||||
|
||||
/**
|
||||
* gtk_pad_controller_new:
|
||||
* @group: #GActionGroup to trigger actions from
|
||||
* @group: `GActionGroup` to trigger actions from
|
||||
* @pad: (nullable): A %GDK_SOURCE_TABLET_PAD device, or %NULL to handle all pads
|
||||
*
|
||||
* Creates a new #GtkPadController that will associate events from @pad to
|
||||
* actions. A %NULL pad may be provided so the controller manages all pad devices
|
||||
* generically, it is discouraged to mix #GtkPadController objects with %NULL
|
||||
* and non-%NULL @pad argument on the same toplevel window, as execution order
|
||||
* is not guaranteed.
|
||||
* Creates a new `GtkPadController` that will associate events from @pad to
|
||||
* actions.
|
||||
*
|
||||
* The #GtkPadController is created with no mapped actions. In order to map pad
|
||||
* events to actions, use gtk_pad_controller_set_action_entries() or
|
||||
* gtk_pad_controller_set_action().
|
||||
* A %NULL pad may be provided so the controller manages all pad devices
|
||||
* generically, it is discouraged to mix `GtkPadController` objects with
|
||||
* %NULL and non-%NULL @pad argument on the same toplevel window, as execution
|
||||
* order is not guaranteed.
|
||||
*
|
||||
* Be aware that pad events will only be delivered to #GtkWindows, so adding a pad
|
||||
* controller to any other type of widget will not have an effect.
|
||||
* The `GtkPadController` is created with no mapped actions. In order to
|
||||
* map pad events to actions, use [method@Gtk.PadController.set_action_entries]
|
||||
* or [method@Gtk.PadController.set_action].
|
||||
*
|
||||
* Returns: A newly created #GtkPadController
|
||||
**/
|
||||
* Be aware that pad events will only be delivered to `GtkWindow`s, so adding
|
||||
* a pad controller to any other type of widget will not have an effect.
|
||||
*
|
||||
* Returns: A newly created `GtkPadController`
|
||||
*/
|
||||
GtkPadController *
|
||||
gtk_pad_controller_new (GActionGroup *group,
|
||||
GdkDevice *pad)
|
||||
@ -465,13 +469,15 @@ gtk_pad_controller_add_entry (GtkPadController *controller,
|
||||
|
||||
/**
|
||||
* gtk_pad_controller_set_action_entries:
|
||||
* @controller: a #GtkPadController
|
||||
* @controller: a `GtkPadController`
|
||||
* @entries: (array length=n_entries): the action entries to set on @controller
|
||||
* @n_entries: the number of elements in @entries
|
||||
*
|
||||
* This is a convenience function to add a group of action entries on
|
||||
* @controller. See #GtkPadActionEntry and gtk_pad_controller_set_action().
|
||||
**/
|
||||
* A convenience function to add a group of action entries on
|
||||
* @controller.
|
||||
*
|
||||
* See [struct@Gtk.PadActionEntry] and [method@Gtk.PadController.set_action].
|
||||
*/
|
||||
void
|
||||
gtk_pad_controller_set_action_entries (GtkPadController *controller,
|
||||
const GtkPadActionEntry *entries,
|
||||
@ -488,7 +494,7 @@ gtk_pad_controller_set_action_entries (GtkPadController *controller,
|
||||
|
||||
/**
|
||||
* gtk_pad_controller_set_action:
|
||||
* @controller: a #GtkPadController
|
||||
* @controller: a `GtkPadController`
|
||||
* @type: the type of pad feature that will trigger this action
|
||||
* @index: the 0-indexed button/ring/strip number that will trigger this action
|
||||
* @mode: the mode that will trigger this action, or -1 for all modes.
|
||||
@ -496,15 +502,16 @@ gtk_pad_controller_set_action_entries (GtkPadController *controller,
|
||||
* be deemed user-visible.
|
||||
* @action_name: action name that will be activated in the #GActionGroup
|
||||
*
|
||||
* Adds an individual action to @controller. This action will only be activated
|
||||
* if the given button/ring/strip number in @index is interacted while
|
||||
* the current mode is @mode. -1 may be used for simple cases, so the action
|
||||
* is triggered on all modes.
|
||||
* Adds an individual action to @controller.
|
||||
*
|
||||
* This action will only be activated if the given button/ring/strip number
|
||||
* in @index is interacted while the current mode is @mode. -1 may be used
|
||||
* for simple cases, so the action is triggered on all modes.
|
||||
*
|
||||
* The given @label should be considered user-visible, so internationalization
|
||||
* rules apply. Some windowing systems may be able to use those for user
|
||||
* feedback.
|
||||
**/
|
||||
*/
|
||||
void
|
||||
gtk_pad_controller_set_action (GtkPadController *controller,
|
||||
GtkPadActionType type,
|
||||
|
||||
Loading…
Reference in New Issue
Block a user