<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
<!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
<!ENTITY version SYSTEM "version.xml">
<!ENTITY pi "&#960;">
<!ENTITY solidus "&#8260;">
]>
<refentry id="GtkPadController">
<refmeta>
<refentrytitle role="top_of_page" id="GtkPadController.top_of_page">GtkPadController</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GTK4 Library</refmiscinfo>
</refmeta>
<refnamediv>
<refname>GtkPadController</refname>
<refpurpose>Controller for drawing tablet pads</refpurpose>
</refnamediv>

<refsect1 id="GtkPadController.functions" role="functions_proto">
<title role="functions_proto.title">Functions</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="functions_proto_type" colwidth="150px"/>
<colspec colname="functions_proto_name"/>
<tbody>
<row><entry role="function_type"><link linkend="GtkPadController"><returnvalue>GtkPadController</returnvalue></link>&#160;*
</entry><entry role="function_name"><link linkend="gtk-pad-controller-new">gtk_pad_controller_new</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-pad-controller-set-action-entries">gtk_pad_controller_set_action_entries</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>
<row><entry role="function_type"><link linkend="void"><returnvalue>void</returnvalue></link>
</entry><entry role="function_name"><link linkend="gtk-pad-controller-set-action">gtk_pad_controller_set_action</link>&#160;<phrase role="c_punctuation">()</phrase></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkPadController.properties" role="properties">
<title role="properties.title">Properties</title>
<informaltable frame="none">
<tgroup cols="3">
<colspec colname="properties_type" colwidth="150px"/>
<colspec colname="properties_name" colwidth="300px"/>
<colspec colname="properties_flags" colwidth="200px"/>
<tbody>
<row><entry role="property_type"><link linkend="GActionGroup"><type>GActionGroup</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkPadController--action-group">action-group</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>
<row><entry role="property_type"><link linkend="GdkDevice"><type>GdkDevice</type></link>&#160;*</entry><entry role="property_name"><link linkend="GtkPadController--pad">pad</link></entry><entry role="property_flags">Read / Write / Construct&#160;Only</entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkPadController.other" role="other_proto">
<title role="other_proto.title">Types and Values</title>
<informaltable pgwide="1" frame="none">
<tgroup cols="2">
<colspec colname="other_proto_type" colwidth="150px"/>
<colspec colname="other_proto_name"/>
<tbody>
<row><entry role="datatype_keyword"></entry><entry role="function_name"><link linkend="GtkPadController-struct">GtkPadController</link></entry></row>
<row><entry role="datatype_keyword">enum</entry><entry role="function_name"><link linkend="GtkPadActionType">GtkPadActionType</link></entry></row>
<row><entry role="datatype_keyword">struct</entry><entry role="function_name"><link linkend="GtkPadActionEntry">GtkPadActionEntry</link></entry></row>

</tbody>
</tgroup>
</informaltable>
</refsect1>
<refsect1 id="GtkPadController.object-hierarchy" role="object_hierarchy">
<title role="object_hierarchy.title">Object Hierarchy</title>
<screen>    <link linkend="GObject">GObject</link>
    <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> <link linkend="GtkEventController">GtkEventController</link>
        <phrase role="lineart">&#9584;&#9472;&#9472;</phrase> GtkPadController
</screen>
</refsect1>

<refsect1 id="GtkPadController.includes"><title>Includes</title><synopsis>#include &lt;gtk/gtk.h&gt;
</synopsis></refsect1>

<refsect1 id="GtkPadController.description" role="desc">
<title role="desc.title">Description</title>
<para><link linkend="GtkPadController"><type>GtkPadController</type></link> 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).</para>
<para>These buttons and sensors have no implicit meaning, and by default they
perform no action, this event controller is provided to map those to
<link linkend="GAction"><type>GAction</type></link> objects, thus letting the application give those a more semantic
meaning.</para>
<para>Buttons and sensors are not constrained to triggering a single action, some
<link linkend="GDK-SOURCE-TABLET-PAD:CAPS"><literal>GDK_SOURCE_TABLET_PAD</literal></link> 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 <link linkend="gdk-device-pad-get-n-groups"><function>gdk_device_pad_get_n_groups()</function></link> and
<link linkend="gdk-device-pad-get-group-n-modes"><function>gdk_device_pad_get_group_n_modes()</function></link>.</para>
<para>Each of the actions that a given button/strip/ring performs for a given
mode is defined by <link linkend="GtkPadActionEntry"><type>GtkPadActionEntry</type></link>, it contains an action name that
will be looked up in the given <link linkend="GActionGroup"><type>GActionGroup</type></link> and activated whenever the
specified input element and mode are triggered.</para>
<para>A simple example of <link linkend="GtkPadController"><type>GtkPadController</type></link> usage, assigning button 1 in all
modes and pad devices to an "invert-selection" action:</para>
<informalexample><programlisting role="example"><![CDATA[
  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);
]]></programlisting></informalexample>
<para></para>
<para>The actions belonging to rings/strips will be activated with a parameter
of type <link linkend="G-VARIANT-TYPE-DOUBLE:CAPS"><literal>G_VARIANT_TYPE_DOUBLE</literal></link> bearing the value of the given axis, it
is required that those are made stateful and accepting this <link linkend="GVariantType"><type>GVariantType</type></link>.</para>

</refsect1>
<refsect1 id="GtkPadController.functions_details" role="details">
<title role="details.title">Functions</title>
<refsect2 id="gtk-pad-controller-new" role="function">
<title>gtk_pad_controller_new&#160;()</title>
<indexterm zone="gtk-pad-controller-new"><primary>gtk_pad_controller_new</primary></indexterm>
<programlisting language="C"><link linkend="GtkPadController"><returnvalue>GtkPadController</returnvalue></link>&#160;*
gtk_pad_controller_new (<parameter><link linkend="GActionGroup"><type>GActionGroup</type></link> *group</parameter>,
                        <parameter><link linkend="GdkDevice"><type>GdkDevice</type></link> *pad</parameter>);</programlisting>
<para>Creates a new <link linkend="GtkPadController"><type>GtkPadController</type></link> that will associate events from <parameter>pad</parameter>
 to
actions. A <link linkend="NULL:CAPS"><literal>NULL</literal></link> pad may be provided so the controller manages all pad devices
generically, it is discouraged to mix <link linkend="GtkPadController"><type>GtkPadController</type></link> objects with <link linkend="NULL:CAPS"><literal>NULL</literal></link>
and non-<link linkend="NULL:CAPS"><literal>NULL</literal></link> <parameter>pad</parameter>
 argument on the same toplevel window, as execution order
is not guaranteed.</para>
<para>The <link linkend="GtkPadController"><type>GtkPadController</type></link> is created with no mapped actions. In order to map pad
events to actions, use <link linkend="gtk-pad-controller-set-action-entries"><function>gtk_pad_controller_set_action_entries()</function></link> or
<link linkend="gtk-pad-controller-set-action"><function>gtk_pad_controller_set_action()</function></link>.</para>
<para>Be aware that pad events will only be delivered to <link linkend="GtkWindows"><type>GtkWindows</type></link>, so adding a pad
controller to any other type of widget will not have an effect.</para>
<refsect3 id="gtk-pad-controller-new.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>group</para></entry>
<entry role="parameter_description"><para><link linkend="GActionGroup"><type>GActionGroup</type></link> to trigger actions from</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>pad</para></entry>
<entry role="parameter_description"><para>A <link linkend="GDK-SOURCE-TABLET-PAD:CAPS"><literal>GDK_SOURCE_TABLET_PAD</literal></link> device, or <link linkend="NULL:CAPS"><literal>NULL</literal></link> to handle all pads. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>nullable</acronym>]</emphasis></entry></row>
</tbody></tgroup></informaltable>
</refsect3><refsect3 id="gtk-pad-controller-new.returns" role="returns">
<title>Returns</title>
<para> A newly created <link linkend="GtkPadController"><type>GtkPadController</type></link></para>
</refsect3></refsect2>
<refsect2 id="gtk-pad-controller-set-action-entries" role="function">
<title>gtk_pad_controller_set_action_entries&#160;()</title>
<indexterm zone="gtk-pad-controller-set-action-entries"><primary>gtk_pad_controller_set_action_entries</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_pad_controller_set_action_entries (<parameter><link linkend="GtkPadController"><type>GtkPadController</type></link> *controller</parameter>,
                                       <parameter>const <link linkend="GtkPadActionEntry"><type>GtkPadActionEntry</type></link> *entries</parameter>,
                                       <parameter><link linkend="gint"><type>gint</type></link> n_entries</parameter>);</programlisting>
<para>This is a convenience function to add a group of action entries on
<parameter>controller</parameter>
. See <link linkend="GtkPadActionEntry"><type>GtkPadActionEntry</type></link> and <link linkend="gtk-pad-controller-set-action"><function>gtk_pad_controller_set_action()</function></link>.</para>
<refsect3 id="gtk-pad-controller-set-action-entries.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>controller</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkPadController"><type>GtkPadController</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>entries</para></entry>
<entry role="parameter_description"><para>the action entries to set on <parameter>controller</parameter>
. </para></entry>
<entry role="parameter_annotations"><emphasis role="annotation">[<acronym>array</acronym> length=n_entries]</emphasis></entry></row>
<row><entry role="parameter_name"><para>n_entries</para></entry>
<entry role="parameter_description"><para>the number of elements in <parameter>entries</parameter>
</para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="gtk-pad-controller-set-action" role="function">
<title>gtk_pad_controller_set_action&#160;()</title>
<indexterm zone="gtk-pad-controller-set-action"><primary>gtk_pad_controller_set_action</primary></indexterm>
<programlisting language="C"><link linkend="void"><returnvalue>void</returnvalue></link>
gtk_pad_controller_set_action (<parameter><link linkend="GtkPadController"><type>GtkPadController</type></link> *controller</parameter>,
                               <parameter><link linkend="GtkPadActionType"><type>GtkPadActionType</type></link> type</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> index</parameter>,
                               <parameter><link linkend="gint"><type>gint</type></link> mode</parameter>,
                               <parameter>const <link linkend="gchar"><type>gchar</type></link> *label</parameter>,
                               <parameter>const <link linkend="gchar"><type>gchar</type></link> *action_name</parameter>);</programlisting>
<para>Adds an individual action to <parameter>controller</parameter>
. This action will only be activated
if the given button/ring/strip number in <parameter>index</parameter>
 is interacted while
the current mode is <parameter>mode</parameter>
. -1 may be used for simple cases, so the action
is triggered on all modes.</para>
<para>The given <parameter>label</parameter>
 should be considered user-visible, so internationalization
rules apply. Some windowing systems may be able to use those for user
feedback.</para>
<refsect3 id="gtk-pad-controller-set-action.parameters" role="parameters">
<title>Parameters</title>
<informaltable role="parameters_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="parameters_name" colwidth="150px"/>
<colspec colname="parameters_description"/>
<colspec colname="parameters_annotations" colwidth="200px"/>
<tbody>
<row><entry role="parameter_name"><para>controller</para></entry>
<entry role="parameter_description"><para>a <link linkend="GtkPadController"><type>GtkPadController</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>type</para></entry>
<entry role="parameter_description"><para>the type of pad feature that will trigger this action</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>index</para></entry>
<entry role="parameter_description"><para>the 0-indexed button/ring/strip number that will trigger this action</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>mode</para></entry>
<entry role="parameter_description"><para>the mode that will trigger this action, or -1 for all modes.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>label</para></entry>
<entry role="parameter_description"><para>Human readable description of this action, this string should
be deemed user-visible.</para></entry>
<entry role="parameter_annotations"></entry></row>
<row><entry role="parameter_name"><para>action_name</para></entry>
<entry role="parameter_description"><para>action name that will be activated in the <link linkend="GActionGroup"><type>GActionGroup</type></link></para></entry>
<entry role="parameter_annotations"></entry></row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>

</refsect1>
<refsect1 id="GtkPadController.other_details" role="details">
<title role="details.title">Types and Values</title>
<refsect2 id="GtkPadController-struct" role="struct">
<title>GtkPadController</title>
<indexterm zone="GtkPadController-struct"><primary>GtkPadController</primary></indexterm>
<programlisting language="C">typedef struct _GtkPadController GtkPadController;</programlisting>
</refsect2>
<refsect2 id="GtkPadActionType" role="enum">
<title>enum GtkPadActionType</title>
<indexterm zone="GtkPadActionType"><primary>GtkPadActionType</primary></indexterm>
<para>The type of a pad action.</para>
<refsect3 id="GtkPadActionType.members" role="enum_members">
<title>Members</title>
<informaltable role="enum_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="enum_members_name" colwidth="300px"/>
<colspec colname="enum_members_description"/>
<colspec colname="enum_members_annotations" colwidth="200px"/>
<tbody>
<row role="constant"><entry role="enum_member_name"><para id="GTK-PAD-ACTION-BUTTON:CAPS">GTK_PAD_ACTION_BUTTON</para></entry>
<entry role="enum_member_description"><para>Action is triggered by a pad button</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-PAD-ACTION-RING:CAPS">GTK_PAD_ACTION_RING</para></entry>
<entry role="enum_member_description"><para>Action is triggered by a pad ring</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
<row role="constant"><entry role="enum_member_name"><para id="GTK-PAD-ACTION-STRIP:CAPS">GTK_PAD_ACTION_STRIP</para></entry>
<entry role="enum_member_description"><para>Action is triggered by a pad strip</para>
</entry>
<entry role="enum_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3></refsect2>
<refsect2 id="GtkPadActionEntry" role="struct">
<title>struct GtkPadActionEntry</title>
<indexterm zone="GtkPadActionEntry"><primary>GtkPadActionEntry</primary></indexterm>
<programlisting language="C">struct GtkPadActionEntry {
  GtkPadActionType type;
  int index;
  int mode;
  const char *label;
  const char *action_name;
};
</programlisting>
<para>Struct defining a pad action entry.</para>
<refsect3 id="GtkPadActionEntry.members" role="struct_members">
<title>Members</title>
<informaltable role="struct_members_table" pgwide="1" frame="none">
<tgroup cols="3">
<colspec colname="struct_members_name" colwidth="300px"/>
<colspec colname="struct_members_description"/>
<colspec colname="struct_members_annotations" colwidth="200px"/>
<tbody>
<row role="member"><entry role="struct_member_name"><para><link linkend="GtkPadActionType"><type>GtkPadActionType</type></link>&#160;<structfield id="GtkPadActionEntry.type">type</structfield>;</para></entry>
<entry role="struct_member_description"><para>the type of pad feature that will trigger this action entry.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="int"><type>int</type></link>&#160;<structfield id="GtkPadActionEntry.index">index</structfield>;</para></entry>
<entry role="struct_member_description"><para>the 0-indexed button/ring/strip number that will trigger this action
entry.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para><link linkend="int"><type>int</type></link>&#160;<structfield id="GtkPadActionEntry.mode">mode</structfield>;</para></entry>
<entry role="struct_member_description"><para>the mode that will trigger this action entry, or -1 for all modes.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para>const&#160;<link linkend="char"><type>char</type></link>&#160;*<structfield id="GtkPadActionEntry.label">label</structfield>;</para></entry>
<entry role="struct_member_description"><para>Human readable description of this action entry, this string should
be deemed user-visible.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
<row role="member"><entry role="struct_member_name"><para>const&#160;<link linkend="char"><type>char</type></link>&#160;*<structfield id="GtkPadActionEntry.action-name">action_name</structfield>;</para></entry>
<entry role="struct_member_description"><para>action name that will be activated in the <link linkend="GActionGroup"><type>GActionGroup</type></link>.</para></entry>
<entry role="struct_member_annotations"></entry>
</row>
</tbody></tgroup></informaltable>
</refsect3>
</refsect2>

</refsect1>
<refsect1 id="GtkPadController.property-details" role="property_details">
<title role="property_details.title">Property Details</title>
<refsect2 id="GtkPadController--action-group" role="property"><title>The <literal>“action-group”</literal> property</title>
<indexterm zone="GtkPadController--action-group"><primary>GtkPadController:action-group</primary></indexterm>
<programlisting>  “action-group”             <link linkend="GActionGroup"><type>GActionGroup</type></link>&#160;*</programlisting>
<para>Action group to launch actions from.</para><para>Owner: GtkPadController</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
</refsect2>
<refsect2 id="GtkPadController--pad" role="property"><title>The <literal>“pad”</literal> property</title>
<indexterm zone="GtkPadController--pad"><primary>GtkPadController:pad</primary></indexterm>
<programlisting>  “pad”                      <link linkend="GdkDevice"><type>GdkDevice</type></link>&#160;*</programlisting>
<para>Pad device to control.</para><para>Owner: GtkPadController</para>
<para>Flags: Read / Write / Construct&#160;Only</para>
</refsect2>

</refsect1>
<refsect1 id="GtkPadController.see-also">
<title>See Also</title>
<para><link linkend="GtkEventController"><type>GtkEventController</type></link>, <link linkend="GdkDevicePad"><type>GdkDevicePad</type></link></para>

</refsect1>

</refentry>
