[Xfce4-commits] [apps/xfdashboard] 01/02: Add annotation for API documentation of XfdashboardClickAction and replace hard-coded numbers for checking button pressed with macros
noreply at xfce.org
noreply at xfce.org
Tue Jun 21 12:52:22 CEST 2016
This is an automated email from the git hooks/post-receive script.
nomad pushed a commit to branch master
in repository apps/xfdashboard.
commit 42c5ee3e8b36f8045f1a06080792d1e7244621f6
Author: Stephan Haller <nomad at froevel.de>
Date: Tue Jun 21 12:47:24 2016 +0200
Add annotation for API documentation of XfdashboardClickAction and replace hard-coded numbers for checking button pressed with macros
---
libxfdashboard/button.c | 2 +-
libxfdashboard/click-action.c | 185 ++++++++++++++++++++++++++++++-
libxfdashboard/click-action.h | 44 ++++++++
libxfdashboard/live-window.c | 2 +-
libxfdashboard/live-workspace.c | 2 +-
libxfdashboard/search-result-container.c | 2 +-
6 files changed, 228 insertions(+), 9 deletions(-)
diff --git a/libxfdashboard/button.c b/libxfdashboard/button.c
index df3a8f7..7e868d7 100644
--- a/libxfdashboard/button.c
+++ b/libxfdashboard/button.c
@@ -1075,7 +1075,7 @@ static void _xfdashboard_button_clicked(XfdashboardClickAction *inAction,
g_return_if_fail(XFDASHBOARD_IS_BUTTON(self));
/* Only emit signal if click was perform with left button */
- if(xfdashboard_click_action_get_button(inAction)==1)
+ if(xfdashboard_click_action_get_button(inAction)==XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON)
{
/* Emit 'clicked' signal */
g_signal_emit(self, XfdashboardButtonSignals[SIGNAL_CLICKED], 0);
diff --git a/libxfdashboard/click-action.c b/libxfdashboard/click-action.c
index 1b813e5..8af272f 100644
--- a/libxfdashboard/click-action.c
+++ b/libxfdashboard/click-action.c
@@ -31,6 +31,80 @@
*
*/
+/**
+ * SECTION:click-action
+ * @short_Description: Action for clickable actors
+ * @include: xfdashboard/click-action.h
+ *
+ * #XfdashboardClickAction is a sub-class of #ClutterAction that implements
+ * the logic for clickable actors, by using the low level events of
+ * #ClutterActor, such as #ClutterActor::button-press-event and
+ * #ClutterActor::button-release-event, to synthesize the high level
+ * #ClutterClickAction::clicked signal.
+ *
+ * This action is a bad workaround for ClutterClickAction which prevents
+ * drag actions to work properly (at least since clutter version 1.12).
+ * #XfdashboardClickAction is a complete copy of the original ClutterClickAction
+ * except for one line to get the click actions work with other added actions
+ * like drag'n'drop actions.
+ *
+ * To use #XfdashboardClickAction you just need to apply it to a #ClutterActor
+ * using clutter_actor_add_action() and connect to the
+ * #XfdashboardClickAction::clicked signal:
+ *
+ * |[
+ * ClutterAction *action = xfdashboard_click_action_new ();
+ *
+ * clutter_actor_add_action (actor, action);
+ *
+ * g_signal_connect (action, "clicked", G_CALLBACK (on_clicked), NULL);
+ * ]|
+ *
+ * #XfdashboardClickAction also supports long press gestures: a long press
+ * is activated if the pointer remains pressed within a certain threshold
+ * (as defined by the #XfdashboardClickAction:long-press-threshold property)
+ * for a minimum amount of time (as the defined by the
+ * #XfdashboardClickAction:long-press-duration property).
+ * The #XfdashboardClickAction::long-press signal is emitted multiple times,
+ * using different #ClutterLongPressState values; to handle long presses
+ * you should connect to the #XfdashboardClickAction::long-press signal and
+ * handle the different states:
+ *
+ * |[
+ * static gboolean
+ * on_long_press (XfdashboardClickAction *self,
+ * ClutterActor *inActor,
+ * ClutterLongPressState inState)
+ * {
+ * switch (inState)
+ * {
+ * case CLUTTER_LONG_PRESS_QUERY:
+ * /* return TRUE if the actor should support long press
+ * * gestures, and FALSE otherwise; this state will be
+ * * emitted on button presses
+ * */
+ * return(TRUE);
+ *
+ * case CLUTTER_LONG_PRESS_ACTIVATE:
+ * /* this state is emitted if the minimum duration has
+ * * been reached without the gesture being cancelled.
+ * * the return value is not used
+ * */
+ * return(TRUE);
+ *
+ * case CLUTTER_LONG_PRESS_CANCEL:
+ * /* this state is emitted if the long press was cancelled;
+ * * for instance, the pointer went outside the actor or the
+ * * allowed threshold, or the button was released before
+ * * the minimum duration was reached. the return value is
+ * * not used
+ * */
+ * return(FALSE);
+ * }
+ * }
+ * ]|
+ */
+
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
@@ -582,6 +656,11 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
g_type_class_add_private(klass, sizeof (XfdashboardClickActionPrivate));
/* Define properties */
+ /**
+ * XfdashboardClickAction:pressed:
+ *
+ * Whether the clickable actor should be in "pressed" state
+ */
XfdashboardClickActionProperties[PROP_PRESSED]=
g_param_spec_boolean("pressed",
_("Pressed"),
@@ -589,6 +668,11 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+ /**
+ * XfdashboardClickAction:held:
+ *
+ * Whether the clickable actor has the pointer grabbed
+ */
XfdashboardClickActionProperties[PROP_HELD]=
g_param_spec_boolean("held",
_("Held"),
@@ -596,6 +680,15 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
FALSE,
G_PARAM_READABLE | G_PARAM_STATIC_STRINGS);
+ /**
+ * XfdashboardClickAction:long-press-duration:
+ *
+ * The minimum duration of a press for it to be recognized as a long press
+ * gesture, in milliseconds.
+ *
+ * A value of -1 will make the #XfdashboardClickAction use the value of the
+ * #ClutterSettings:long-press-duration property.
+ */
XfdashboardClickActionProperties[PROP_LONG_PRESS_DURATION]=
g_param_spec_int("long-press-duration",
_("Long Press Duration"),
@@ -605,6 +698,15 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
-1,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+ /**
+ * XfdashboardClickAction:long-press-threshold:
+ *
+ * The maximum allowed distance that can be covered (on both axes) before
+ * a long press gesture is cancelled, in pixels.
+ *
+ * A value of -1 will make the #XfdashboardClickAction use the value of the
+ * #ClutterSettings:dnd-drag-threshold property.
+ */
XfdashboardClickActionProperties[PROP_LONG_PRESS_THRESHOLD]=
g_param_spec_int("long-press-threshold",
_("Long Press Threshold"),
@@ -617,6 +719,15 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
g_object_class_install_properties(gobjectClass, PROP_LAST, XfdashboardClickActionProperties);
/* Define signals */
+ /**
+ * XfdashboardClickAction::clicked:
+ * @self: The #XfdashboardClickAction that emitted the signal
+ * @inActor: The #ClutterActor attached to @self
+ *
+ * The ::clicked signal is emitted when the #ClutterActor to which
+ * a #XfdashboardClickAction has been applied should respond to a
+ * pointer button press and release events
+ */
XfdashboardClickActionSignals[SIGNAL_CLICKED]=
g_signal_new("clicked",
G_TYPE_FROM_CLASS(klass),
@@ -628,6 +739,31 @@ static void xfdashboard_click_action_class_init(XfdashboardClickActionClass *kla
1,
CLUTTER_TYPE_ACTOR);
+ /**
+ * XfdashboardClickAction::long-press:
+ * @self: The #XfdashboardClickAction that emitted the signal
+ * @inActor: The #ClutterActor attached to @self
+ * @inState: The long press state
+ *
+ * The ::long-press signal is emitted during the long press gesture
+ * handling.
+ *
+ * This signal can be emitted multiple times with different states.
+ *
+ * The %CLUTTER_LONG_PRESS_QUERY state will be emitted on button presses,
+ * and its return value will determine whether the long press handling
+ * should be initiated. If the signal handlers will return %TRUE, the
+ * %CLUTTER_LONG_PRESS_QUERY state will be followed either by a signal
+ * emission with the %CLUTTER_LONG_PRESS_ACTIVATE state if the long press
+ * constraints were respected, or by a signal emission with the
+ * %CLUTTER_LONG_PRESS_CANCEL state if the long press was cancelled.
+ *
+ * It is possible to forcibly cancel a long press detection using
+ * xfdashboard_click_action_release().
+ *
+ * Return value: Only the %CLUTTER_LONG_PRESS_QUERY state uses the
+ * returned value of the handler; other states will ignore it
+ */
XfdashboardClickActionSignals[SIGNAL_LONG_PRESS]=
g_signal_new("long-press",
G_TYPE_FROM_CLASS(klass),
@@ -657,13 +793,26 @@ static void xfdashboard_click_action_init(XfdashboardClickAction *self)
/* IMPLEMENTATION: Public API */
-/* Create new action */
+/**
+ * xfdashboard_click_action_new:
+ *
+ * Creates a new #XfdashboardClickAction instance
+ *
+ * Return value: The newly created #XfdashboardClickAction
+ */
ClutterAction* xfdashboard_click_action_new(void)
{
return(CLUTTER_ACTION(g_object_new(XFDASHBOARD_TYPE_CLICK_ACTION, NULL)));
}
-/* Get pressed button */
+/**
+ * xfdashboard_click_action_get_button:
+ * @self: A #XfdashboardClickAction
+ *
+ * Retrieves the button that was pressed.
+ *
+ * Return value: The button value
+ */
guint xfdashboard_click_action_get_button(XfdashboardClickAction *self)
{
g_return_val_if_fail(XFDASHBOARD_IS_CLICK_ACTION(self), 0);
@@ -671,7 +820,14 @@ guint xfdashboard_click_action_get_button(XfdashboardClickAction *self)
return(self->priv->pressButton);
}
-/* Get modifier state of the click action */
+/**
+ * xfdashboard_click_action_get_state:
+ * @self: A #XfdashboardClickAction
+ *
+ * Retrieves the modifier state of the click action.
+ *
+ * Return value: The modifier state parameter or 0
+ */
ClutterModifierType xfdashboard_click_action_get_state(XfdashboardClickAction *self)
{
g_return_val_if_fail(XFDASHBOARD_IS_CLICK_ACTION(self), 0);
@@ -679,7 +835,14 @@ ClutterModifierType xfdashboard_click_action_get_state(XfdashboardClickAction *s
return(self->priv->modifierState);
}
-/* Get screen coordinates of the button press */
+/**
+ * xfdashboard_click_action_get_coords:
+ * @self: A #XfdashboardClickAction
+ * @outPressX: (out): Return location for the X coordinate or %NULL
+ * @outPressY: (out): Return location for the Y coordinate or %NULL
+ *
+ * Retrieves the screen coordinates of the button press.
+ */
void xfdashboard_click_action_get_coords(XfdashboardClickAction *self, gfloat *outPressX, gfloat *outPressY)
{
g_return_if_fail(XFDASHBOARD_IS_CLICK_ACTION(self));
@@ -688,7 +851,19 @@ void xfdashboard_click_action_get_coords(XfdashboardClickAction *self, gfloat *o
if(outPressY!=NULL) *outPressY=self->priv->pressY;
}
-/* Emulate a release of the pointer button */
+/**
+ * xfdashboard_click_action_release:
+ * @self: A #XfdashboardClickAction
+ *
+ * Emulates a release of the pointer button, which ungrabs the pointer
+ * and unsets the #XfdashboardClickAction:pressed state.
+ *
+ * This function will also cancel the long press gesture if one was
+ * initiated.
+ *
+ * This function is useful to break a grab, for instance after a certain
+ * amount of time has passed.
+ */
void xfdashboard_click_action_release(XfdashboardClickAction *self)
{
XfdashboardClickActionPrivate *priv;
diff --git a/libxfdashboard/click-action.h b/libxfdashboard/click-action.h
index 88f85de..2e98498 100644
--- a/libxfdashboard/click-action.h
+++ b/libxfdashboard/click-action.h
@@ -42,6 +42,36 @@
G_BEGIN_DECLS
+/* Public definitions */
+/**
+ * XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON:
+ *
+ * A helper macro to determine left button clicks using
+ * the function xfdashboard_click_action_get_button().
+ * The value for this macro is an unsinged integer.
+ **/
+#define XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON ((guint)1)
+
+/**
+ * XFDASHBOARD_CLICK_ACTION_MIDDLE_BUTTON:
+ *
+ * A helper macro to determine middle button clicks using
+ * the function xfdashboard_click_action_get_button().
+ * The value for this macro is an unsinged integer.
+ **/
+#define XFDASHBOARD_CLICK_ACTION_MIDDLE_BUTTON ((guint)2)
+
+/**
+ * XFDASHBOARD_CLICK_ACTION_RIGHT_BUTTON:
+ *
+ * A helper macro to determine right button clicks using
+ * the function xfdashboard_click_action_get_button().
+ * The value for this macro is an unsinged integer.
+ **/
+#define XFDASHBOARD_CLICK_ACTION_RIGHT_BUTTON ((guint)3)
+
+
+/* Object declaration */
#define XFDASHBOARD_TYPE_CLICK_ACTION (xfdashboard_click_action_get_type ())
#define XFDASHBOARD_CLICK_ACTION(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), XFDASHBOARD_TYPE_CLICK_ACTION, XfdashboardClickAction))
#define XFDASHBOARD_IS_CLICK_ACTION(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), XFDASHBOARD_TYPE_CLICK_ACTION))
@@ -53,14 +83,28 @@ typedef struct _XfdashboardClickAction XfdashboardClickAction;
typedef struct _XfdashboardClickActionPrivate XfdashboardClickActionPrivate;
typedef struct _XfdashboardClickActionClass XfdashboardClickActionClass;
+/**
+ * XfdashboardClickAction:
+ *
+ * The #XfdashboardClickAction structure contains only private data and
+ * should be accessed using the provided API
+ */
struct _XfdashboardClickAction
{
+ /*< private >*/
/* Parent instance */
ClutterAction parent_instance;
XfdashboardClickActionPrivate *priv;
};
+/**
+ * XfdashboardClickActionClass:
+ * @clicked: class handler for the #XfdashboardClickActionClass::clicked signal
+ * @long_press: class handler for the #XfdashboardClickActionClass::long-press signal
+ *
+ * The #XfdashboardClickActionClass structure contains only private data
+ */
struct _XfdashboardClickActionClass
{
/*< private >*/
diff --git a/libxfdashboard/live-window.c b/libxfdashboard/live-window.c
index 15afc06..d20536d 100644
--- a/libxfdashboard/live-window.c
+++ b/libxfdashboard/live-window.c
@@ -141,7 +141,7 @@ static void _xfdashboard_live_window_on_clicked(XfdashboardLiveWindow *self, Clu
action=XFDASHBOARD_CLICK_ACTION(inUserData);
/* Only emit any of these signals if click was perform with left button */
- if(xfdashboard_click_action_get_button(action)!=1) return;
+ if(xfdashboard_click_action_get_button(action)!=XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON) return;
/* Check if click happened in "close button" */
if(clutter_actor_is_visible(priv->actorClose))
diff --git a/libxfdashboard/live-workspace.c b/libxfdashboard/live-workspace.c
index e3491f6..4495212 100644
--- a/libxfdashboard/live-workspace.c
+++ b/libxfdashboard/live-workspace.c
@@ -234,7 +234,7 @@ static void _xfdashboard_live_workspace_on_clicked(XfdashboardLiveWorkspace *sel
action=XFDASHBOARD_CLICK_ACTION(inUserData);
/* Only emit signal if click was perform with left button */
- if(xfdashboard_click_action_get_button(action)==1)
+ if(xfdashboard_click_action_get_button(action)==XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON)
{
/* Emit "clicked" signal */
g_signal_emit(self, XfdashboardLiveWorkspaceSignals[SIGNAL_CLICKED], 0);
diff --git a/libxfdashboard/search-result-container.c b/libxfdashboard/search-result-container.c
index 29881e3..2161160 100644
--- a/libxfdashboard/search-result-container.c
+++ b/libxfdashboard/search-result-container.c
@@ -393,7 +393,7 @@ static void _xfdashboard_search_result_container_on_result_item_actor_clicked(Xf
self=XFDASHBOARD_SEARCH_RESULT_CONTAINER(inUserData);
/* Only emit signal if click was perform with left button */
- if(xfdashboard_click_action_get_button(inAction)==1)
+ if(xfdashboard_click_action_get_button(inAction)==XFDASHBOARD_CLICK_ACTION_LEFT_BUTTON)
{
/* Activate result item by actor clicked */
_xfdashboard_search_result_container_activate_result_item_by_actor(self, inActor);
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list