Tap and Hold API

[Kristian Rietveld <kris imendio com>]

Hey all,

Recently I have been working on a tap-n-hold implementation based on the
implementation found in Maemo.  Tap-n-hold allows for a callback to be
called after a mouse button has been pressed for a given amount of time
This action is particularly useful on touch screen devices, since it can be
used to, for example, popup a context menu instead of using the right
mouse button which is not available on these devices.

The patch is nearing completion and I would like to propose the API
described below for inclusion into GTK+.  However, there are a few
things left to work out, these are also discussed below.


  typedef enum
  {
    GTK_TAP_AND_HOLD_QUERY,
    GTK_TAP_AND_HOLD_TRIGGER,
    GTK_TAP_AND_HOLD_CANCEL
  } GtkTapAndHoldAction;

  gboolean     (* tap_and_hold) (GtkWidget           *widget,
                                 GtkTapAndHoldAction  action,
                                 gint                 x,
                                 gint                 y);

This is the main and only signal.  People familiar with the Maemo
implementation will notice that the separate signals have been merged into
one.  Some people might find this more convenient, since you only have to
write a single callback to get things going, some might not.  A very
important reason for merging the signals into one is that GtkWidget has
only three signal slots left at the moment of writing (and only two after
this patch has been committed).

A brief description of the different actions:

  * Query: once the user presses the mouse button, this signal will be
    emitted to check whether the given location (x, y) allows for executing
    the tap-n-hold action.  The x and y parameters are set to the location
    of the mouse cursor (relative to the widget's allocation)  A return
    value of FALSE means no tap-n-hold action should occur.

  * Trigger: if the application returned TRUE in response to the query
    signal and the user hold the button and did not move the mouse past the
    threshold (currently the drag threshold is used for this) during the
    timeout period, this signal will be emitted.  X and y again reflect the
    position of the mouse cursor.  The return value of the signal is not of
    any significance and ignored.

  * Cancel: when the tap-n-hold operation was canceled (the user released
    the mouse button or the user moved the mouse past the drag threshold),
    this signal will be emitted to inform the application.  X and y
    are undefined, the return value is not of any significance and ignored.

A GtkSetting called "gtk-tap-and-hold-timeout" has been added, which is
used to set the tap-n-hold timeout.

Note there is no property to enable this functionality, like the new
tooltips API has with has-tooltip.  The plan is to enable this
functionality by default.


During the timeout period between pressing the button and triggering the
tap-n-hold action the mouse cursor will be replaced by an animation,
indicating that "something" is happening.  This animation should be
configured in an RC file, or eventually we can reserve an icon theme slot
for this with a default animation.  How do people feel about also
supporting built-in GdkCursors to be set as indication that the
tap-n-hold timeout is pending?

Another questionable point is whether we should allow for tap-n-hold
actions to be triggered via the keyboard.  This is probably a good thing
to do and would involve adding a gboolean "triggered_by_keyboard" to the
signal signature, just like the new tooltips API has.  Does anyone have
better suggestions here?


regards,

-kris.