[Xfce4-commits] [apps/xfdashboard] 01/01: Add annotation for API documentation of XfdashboardToggleButton
noreply at xfce.org
noreply at xfce.org
Wed Jun 22 15:37:35 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 5b27397e45456bd40b3770d392b30f6af8745a90
Author: Stephan Haller <nomad at froevel.de>
Date: Wed Jun 22 15:37:28 2016 +0200
Add annotation for API documentation of XfdashboardToggleButton
---
libxfdashboard/application.h | 14 ++---
libxfdashboard/click-action.h | 4 +-
libxfdashboard/toggle-button.c | 125 +++++++++++++++++++++++++++++++++++++++--
libxfdashboard/toggle-button.h | 13 +++++
libxfdashboard/view-selector.c | 3 -
libxfdashboard/view-selector.h | 2 +-
6 files changed, 144 insertions(+), 17 deletions(-)
diff --git a/libxfdashboard/application.h b/libxfdashboard/application.h
index cf51c92..ee91d54 100644
--- a/libxfdashboard/application.h
+++ b/libxfdashboard/application.h
@@ -87,13 +87,13 @@ struct _XfdashboardApplication
/**
* XfdashboardApplicationClass:
- * @initialized: class handler for the #XfdashboardApplicationClass::initialized signal
- * @suspend: class handler for the #XfdashboardApplicationClass::suspend signal
- * @resume: class handler for the #XfdashboardApplicationClass::resume signal
- * @quit: class handler for the #XfdashboardApplicationClass::quit signal
- * @shutdown_final: class handler for the #XfdashboardApplicationClass::shutdown_final signal
- * @theme_changed: class handler for the #XfdashboardApplicationClass::theme_changed signal
- * @application_launched: class handler for the #XfdashboardApplicationClass::application_launched signal
+ * @initialized: Class handler for the #XfdashboardApplicationClass::initialized signal
+ * @suspend: Class handler for the #XfdashboardApplicationClass::suspend signal
+ * @resume: Class handler for the #XfdashboardApplicationClass::resume signal
+ * @quit: Class handler for the #XfdashboardApplicationClass::quit signal
+ * @shutdown_final: Class handler for the #XfdashboardApplicationClass::shutdown_final signal
+ * @theme_changed: Class handler for the #XfdashboardApplicationClass::theme_changed signal
+ * @application_launched: Class handler for the #XfdashboardApplicationClass::application_launched signal
*
* The #XfdashboardApplicationClass structure contains only private data
*/
diff --git a/libxfdashboard/click-action.h b/libxfdashboard/click-action.h
index 2e98498..ae76528 100644
--- a/libxfdashboard/click-action.h
+++ b/libxfdashboard/click-action.h
@@ -100,8 +100,8 @@ struct _XfdashboardClickAction
/**
* XfdashboardClickActionClass:
- * @clicked: class handler for the #XfdashboardClickActionClass::clicked signal
- * @long_press: class handler for the #XfdashboardClickActionClass::long-press signal
+ * @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
*/
diff --git a/libxfdashboard/toggle-button.c b/libxfdashboard/toggle-button.c
index a1dced0..271c44f 100644
--- a/libxfdashboard/toggle-button.c
+++ b/libxfdashboard/toggle-button.c
@@ -21,6 +21,30 @@
*
*/
+/**
+ * SECTION:toggle-button
+ * @short_description: A button which can toggle its state between on and off
+ * @include: xfdashboard/toggle-button.h
+ *
+ * #XfdashboardToggleButton is a #XfdashboardButton which will remain in "pressed"
+ * state when clicked. This is the "on" state. When it is clicked again it will
+ * change its state back to normal state. This is the "off" state.
+ *
+ * A toggle button is created by calling either xfdashboard_toggle_button_new(),
+ * xfdashboard_toggle_button_new_with_text(), xfdashboard_toggle_button_new_with_icon()
+ * or xfdashboard_toggle_button_new_full(). This function will create a toggle
+ * button with state "off".
+ *
+ * The state of a #XfdashboardToggleButton can be set specifically using
+ * xfdashboard_toggle_button_set_toggle_state() and retrieved using
+ * xfdashboard_toggle_button_get_toggle_state().
+ *
+ * On creation the #XfdashboardToggleButton will be configured to change its state
+ * automatically when clicked. This behaviour can be changed using
+ * xfdashboard_toggle_button_set_auto_toggle() and retrieved using
+ * xfdashboard_toggle_button_get_auto_toggle().
+ */
+
#ifdef HAVE_CONFIG_H
#include "config.h"
#endif
@@ -159,6 +183,13 @@ static void xfdashboard_toggle_button_class_init(XfdashboardToggleButtonClass *k
g_type_class_add_private(klass, sizeof(XfdashboardToggleButtonPrivate));
/* Define properties */
+ /**
+ * XfdashboardToggleButton:toggle-state:
+ *
+ * A flag indicating if the state of toggle button. It is set to %TRUE if it
+ * is in "on" state that means it is pressed state and %FALSE if it is in
+ * "off" state that means it is not pressed.
+ */
XfdashboardToggleButtonProperties[PROP_TOGGLE_STATE]=
g_param_spec_boolean("toggle-state",
_("Toggle state"),
@@ -166,6 +197,12 @@ static void xfdashboard_toggle_button_class_init(XfdashboardToggleButtonClass *k
FALSE,
G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS);
+ /**
+ * XfdashboardToggleButton:auto-toggle:
+ *
+ * A flag indicating if the state of toggle button should be changed between
+ * "on" and "off" state automatically if it was clicked.
+ */
XfdashboardToggleButtonProperties[PROP_AUTO_TOGGLE]=
g_param_spec_boolean("auto-toggle",
_("Auto toggle"),
@@ -176,6 +213,15 @@ static void xfdashboard_toggle_button_class_init(XfdashboardToggleButtonClass *k
g_object_class_install_properties(gobjectClass, PROP_LAST, XfdashboardToggleButtonProperties);
/* Define signals */
+ /**
+ * XfdashboardToggleButton::toggled:
+ * @self: The #XfdashboardToggleButton which changed its state
+ *
+ * Should be connected if you wish to perform an action whenever the
+ * #XfdashboardToggleButton's state has changed.
+ *
+ * The state has to be retrieved using xfdashboard_toggle_button_get_toggle_state().
+ */
XfdashboardToggleButtonSignals[SIGNAL_TOGGLED]=
g_signal_new("toggled",
G_TYPE_FROM_CLASS(klass),
@@ -207,7 +253,13 @@ static void xfdashboard_toggle_button_init(XfdashboardToggleButton *self)
/* IMPLEMENTATION: Public API */
-/* Create new actor */
+/**
+ * xfdashboard_toggle_button_new:
+ *
+ * Creates a new #XfdashboardToggleButton actor
+ *
+ * Return value: The newly created #XfdashboardToggleButton
+ */
ClutterActor* xfdashboard_toggle_button_new(void)
{
return(g_object_new(XFDASHBOARD_TYPE_TOGGLE_BUTTON,
@@ -216,6 +268,14 @@ ClutterActor* xfdashboard_toggle_button_new(void)
NULL));
}
+/**
+ * xfdashboard_toggle_button_new_with_text:
+ * @inText: A string containing the text to be placed in the toggle button
+ *
+ * Creates a new #XfdashboardToggleButton actor with a text label.
+ *
+ * Return value: The newly created #XfdashboardToggleButton
+ */
ClutterActor* xfdashboard_toggle_button_new_with_text(const gchar *inText)
{
return(g_object_new(XFDASHBOARD_TYPE_TOGGLE_BUTTON,
@@ -224,6 +284,15 @@ ClutterActor* xfdashboard_toggle_button_new_with_text(const gchar *inText)
NULL));
}
+/**
+ * xfdashboard_toggle_button_new_with_icon:
+ * @inIconName: A string containing the stock icon name or file name for the icon
+ * to be place in the toogle button
+ *
+ * Creates a new #XfdashboardToggleButton actor with an icon.
+ *
+ * Return value: The newly created #XfdashboardToggleButton
+ */
ClutterActor* xfdashboard_toggle_button_new_with_icon(const gchar *inIconName)
{
return(g_object_new(XFDASHBOARD_TYPE_TOGGLE_BUTTON,
@@ -232,7 +301,18 @@ ClutterActor* xfdashboard_toggle_button_new_with_icon(const gchar *inIconName)
NULL));
}
-ClutterActor* xfdashboard_toggle_button_new_full(const gchar *inIconName, const gchar *inText)
+/**
+ * xfdashboard_toggle_button_new_full:
+ * @inIconName: A string containing the stock icon name or file name for the icon
+ * to be place in the toogle button
+ * @inText: A string containing the text to be placed in the toggle button
+ *
+ * Creates a new #XfdashboardToggleButton actor with a text label and an icon.
+ *
+ * Return value: The newly created #XfdashboardToggleButton
+ */
+ClutterActor* xfdashboard_toggle_button_new_full(const gchar *inIconName,
+ const gchar *inText)
{
return(g_object_new(XFDASHBOARD_TYPE_TOGGLE_BUTTON,
"text", inText,
@@ -241,7 +321,15 @@ ClutterActor* xfdashboard_toggle_button_new_full(const gchar *inIconName, const
NULL));
}
-/* Get/set toggle state */
+/**
+ * xfdashboard_toggle_button_get_toggle_state:
+ * @self: A #XfdashboardToggleButton
+ *
+ * Retrieves the current state of @self.
+ *
+ * Return value: Returns %TRUE if the toggle button is pressed in ("on" state) and
+ * %FALSE if it is raised ("off" state).
+ */
gboolean xfdashboard_toggle_button_get_toggle_state(XfdashboardToggleButton *self)
{
g_return_val_if_fail(XFDASHBOARD_IS_TOGGLE_BUTTON(self), 0);
@@ -249,6 +337,15 @@ gboolean xfdashboard_toggle_button_get_toggle_state(XfdashboardToggleButton *sel
return(self->priv->toggleState);
}
+/**
+ * xfdashboard_toggle_button_set_toggle_state:
+ * @self: A #XfdashboardToggleButton
+ * @inToggleState: The state to set at @self
+ *
+ * Sets the state of @self. If @inToggleState is set to %TRUE then the toggle button
+ * will set to and remain in pressed state ("on" state). If set to %FALSE then the
+ * toggle button will raised ("off" state).
+ */
void xfdashboard_toggle_button_set_toggle_state(XfdashboardToggleButton *self, gboolean inToggleState)
{
XfdashboardToggleButtonPrivate *priv;
@@ -277,7 +374,16 @@ void xfdashboard_toggle_button_set_toggle_state(XfdashboardToggleButton *self, g
}
}
-/* Get/set auto-toggle (on click) */
+/**
+ * xfdashboard_toggle_button_get_auto_toggle:
+ * @self: A #XfdashboardToggleButton
+ *
+ * Retrieves the automatic toggle mode of @self. If automatic toggle mode is %TRUE
+ * then it is active and the toggle button changes its state automatically when
+ * clicked.
+ *
+ * Return value: Returns %TRUE if automatic toggle mode is active, otherwise %FALSE.
+ */
gboolean xfdashboard_toggle_button_get_auto_toggle(XfdashboardToggleButton *self)
{
g_return_val_if_fail(XFDASHBOARD_IS_TOGGLE_BUTTON(self), 0);
@@ -285,6 +391,17 @@ gboolean xfdashboard_toggle_button_get_auto_toggle(XfdashboardToggleButton *self
return(self->priv->autoToggleOnClick);
}
+/**
+ * xfdashboard_toggle_button_set_auto_toggle:
+ * @self: A #XfdashboardToggleButton
+ * @inAuto: The state to set at @self
+ *
+ * Sets the automatic toggle mode of @self. If @inAuto is set to %TRUE then the toggle
+ * button will change its state automatically between pressed ("on") and raised ("off")
+ * state when it is clicked. The "clicked" signal will be emitted before the toggle
+ * changes its state. If @inAuto is set to %FALSE a signal handler for "clicked" signal
+ * should be connected to handle the toggle state on your own.
+ */
void xfdashboard_toggle_button_set_auto_toggle(XfdashboardToggleButton *self, gboolean inAuto)
{
XfdashboardToggleButtonPrivate *priv;
diff --git a/libxfdashboard/toggle-button.h b/libxfdashboard/toggle-button.h
index f6c5b00..08c3570 100644
--- a/libxfdashboard/toggle-button.h
+++ b/libxfdashboard/toggle-button.h
@@ -43,8 +43,15 @@ typedef struct _XfdashboardToggleButton XfdashboardToggleButton;
typedef struct _XfdashboardToggleButtonClass XfdashboardToggleButtonClass;
typedef struct _XfdashboardToggleButtonPrivate XfdashboardToggleButtonPrivate;
+/**
+ * XfdashboardToggleButton:
+ *
+ * The #XfdashboardToggleButton structure contains only private data and
+ * should be accessed using the provided API
+ */
struct _XfdashboardToggleButton
{
+ /*< private >*/
/* Parent instance */
XfdashboardButton parent_instance;
@@ -52,6 +59,12 @@ struct _XfdashboardToggleButton
XfdashboardToggleButtonPrivate *priv;
};
+/**
+ * XfdashboardToggleButtonClass:
+ * @toggled: Class handler for the #XfdashboardToggleButtonClass::toggled signal
+ *
+ * The #XfdashboardToggleButtonClass structure contains only private data
+ */
struct _XfdashboardToggleButtonClass
{
/*< private >*/
diff --git a/libxfdashboard/view-selector.c b/libxfdashboard/view-selector.c
index fc9c1a6..358ea24 100644
--- a/libxfdashboard/view-selector.c
+++ b/libxfdashboard/view-selector.c
@@ -471,7 +471,6 @@ static void xfdashboard_view_selector_init(XfdashboardViewSelector *self)
/* IMPLEMENTATION: Public API */
-/* Create new instance */
/**
* xfdashboard_view_selector_new:
*
@@ -513,7 +512,6 @@ ClutterActor* xfdashboard_view_selector_new_for_viewpad(XfdashboardViewpad *inVi
NULL)));
}
-/* Get/set viewpad */
/**
* xfdashboard_view_selector_get_viewpad:
* @self: A #XfdashboardViewSelector
@@ -581,7 +579,6 @@ void xfdashboard_view_selector_set_viewpad(XfdashboardViewSelector *self, Xfdash
g_object_notify_by_pspec(G_OBJECT(self), XfdashboardViewSelectorProperties[PROP_VIEWPAD]);
}
-/* Get/set spacing */
/**
* xfdashboard_view_selector_get_spacing:
* @self: A #XfdashboardViewSelector
diff --git a/libxfdashboard/view-selector.h b/libxfdashboard/view-selector.h
index 70812fc..8f023a9 100644
--- a/libxfdashboard/view-selector.h
+++ b/libxfdashboard/view-selector.h
@@ -64,7 +64,7 @@ struct _XfdashboardViewSelector
/**
* XfdashboardViewSelectorClass:
- * @state_changed: class handler for the #XfdashboardViewSelectorClass::state_changed signal
+ * @state_changed: Class handler for the #XfdashboardViewSelectorClass::state_changed signal
*
* The #XfdashboardViewSelectorClass structure contains only private data
*/
--
To stop receiving notification emails like this one, please contact
the administrator of this repository.
More information about the Xfce4-commits
mailing list