[Xfce4-commits] <xfce4-panel:devel> Add a lot of API documentation.
Nick Schermer
noreply at xfce.org
Fri Dec 4 17:14:01 CET 2009
Updating branch refs/heads/devel
to b80df3fa706b966c395d01f8b55870823b831a5b (commit)
from f39dc5028d126a77e1d128496c471649184bb972 (commit)
commit b80df3fa706b966c395d01f8b55870823b831a5b
Author: Nick Schermer <nick at xfce.org>
Date: Fri Dec 4 16:39:19 2009 +0100
Add a lot of API documentation.
Something around 90% symbol coverage. This a lot to do, but a
big step forward.
docs/references/libxfce4panel-docs.xml | 1 +
docs/references/libxfce4panel-sections.txt | 14 ++-
libxfce4panel/libxfce4panel-config.c | 15 +++-
libxfce4panel/libxfce4panel-config.h.in | 27 +++--
libxfce4panel/xfce-arrow-button.c | 19 +++-
libxfce4panel/xfce-hvbox.c | 26 +++++
libxfce4panel/xfce-panel-convenience.c | 15 +++-
libxfce4panel/xfce-panel-image.c | 16 +++
libxfce4panel/xfce-panel-macros.h | 164 ++++++++++++++++++++++++----
libxfce4panel/xfce-panel-plugin.c | 148 +++++++++++++++++++-------
libxfce4panel/xfce-panel-plugin.h | 11 ++
11 files changed, 377 insertions(+), 79 deletions(-)
diff --git a/docs/references/libxfce4panel-docs.xml b/docs/references/libxfce4panel-docs.xml
index 8de1488..e505bd4 100644
--- a/docs/references/libxfce4panel-docs.xml
+++ b/docs/references/libxfce4panel-docs.xml
@@ -50,6 +50,7 @@
<title>Panel Plugins</title>
<xi:include href="xml/xfce-panel-plugin.xml"/>
+ <xi:include href="xml/xfce-panel-macros.xml"/>
</part>
<part id="libxfce4panel-widgets">
diff --git a/docs/references/libxfce4panel-sections.txt b/docs/references/libxfce4panel-sections.txt
index e376e76..1b044a3 100644
--- a/docs/references/libxfce4panel-sections.txt
+++ b/docs/references/libxfce4panel-sections.txt
@@ -84,6 +84,19 @@ xfce_panel_image_get_type
</SECTION>
<SECTION>
+<FILE>xfce-panel-macros</FILE>
+<TITLE>Panel Plugin Macros</TITLE>
+XFCE_PANEL_PLUGIN_CHANNEL_NAME
+xfce_panel_plugin_xfconf_channel_new
+XFCE_PANEL_DEFINE_PLUGIN
+XFCE_PANEL_DEFINE_PLUGIN_RESIDENT
+XFCE_PANEL_DEFINE_TYPE
+XFCE_PANEL_PLUGIN_REGISTER
+XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK
+XFCE_PANEL_PLUGIN_REGISTER_FULL
+</SECTION>
+
+<SECTION>
<FILE>xfce-panel-plugin</FILE>
<TITLE>XfcePanelPlugin</TITLE>
XfcePanelPlugin
@@ -125,4 +138,3 @@ XFCE_PANEL_PLUGIN_GET_CLASS
<SUBSECTION Private>
xfce_panel_plugin_get_type
</SECTION>
-
diff --git a/libxfce4panel/libxfce4panel-config.c b/libxfce4panel/libxfce4panel-config.c
index 4948626..3d4c6c3 100644
--- a/libxfce4panel/libxfce4panel-config.c
+++ b/libxfce4panel/libxfce4panel-config.c
@@ -26,6 +26,18 @@
/**
+ * SECTION: libxfce4panel-config
+ * @title: Version Information
+ * @short_description: Information about the panel version in use.
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * The panel library provides version information, which could be used
+ * by plugins to handle new API.
+ **/
+
+
+
+/**
* libxfce4panel_major_version:
*
* The major version number of the libxfce4panel library (e.g. in
@@ -112,7 +124,8 @@ libxfce4panel_check_version (guint required_major,
return "Xfce Panel version too new (major mismatch)";
if (required_minor > LIBXFCE4PANEL_MINOR_VERSION)
return "Xfce Panel version too old (minor mismatch)";
- if (required_minor == LIBXFCE4PANEL_MINOR_VERSION && required_micro > LIBXFCE4PANEL_MICRO_VERSION)
+ if (required_minor == LIBXFCE4PANEL_MINOR_VERSION
+ && required_micro > LIBXFCE4PANEL_MICRO_VERSION)
return "Xfce Panel version too old (micro mismatch)";
return NULL;
}
diff --git a/libxfce4panel/libxfce4panel-config.h.in b/libxfce4panel/libxfce4panel-config.h.in
index 096d6e7..001e4e8 100644
--- a/libxfce4panel/libxfce4panel-config.h.in
+++ b/libxfce4panel/libxfce4panel-config.h.in
@@ -29,30 +29,30 @@ G_BEGIN_DECLS
/**
* LIBXFCE4PANEL_MAJOR_VERSION:
- *
+ *
* The major version number of the libxfce4panel library.
- * Like libxfce4panel_major_version, but from the headers used at
- * application compile time, rather than from the library
+ * Like libxfce4panel_major_version, but from the headers used at
+ * application compile time, rather than from the library
* linked against at application run time.
**/
#define LIBXFCE4PANEL_MAJOR_VERSION (@LIBXFCE4PANEL_VERSION_MAJOR@)
/**
* LIBXFCE4PANEL_MINOR_VERSION:
- *
+ *
* The minor version number of the libxfce4panel library.
- * Like libxfce4panel_minor_version, but from the headers used at
- * application compile time, rather than from the library
+ * Like libxfce4panel_minor_version, but from the headers used at
+ * application compile time, rather than from the library
* linked against at application run time.
**/
#define LIBXFCE4PANEL_MINOR_VERSION (@LIBXFCE4PANEL_VERSION_MINOR@)
/**
* LIBXFCE4PANEL_MICRO_VERSION:
- *
+ *
* The micro version number of the libxfce4panel library.
- * Like libxfce4panel_micro_version, but from the headers used at
- * application compile time, rather than from the library
+ * Like libxfce4panel_micro_version, but from the headers used at
+ * application compile time, rather than from the library
* linked against at application run time
**/
#define LIBXFCE4PANEL_MICRO_VERSION (@LIBXFCE4PANEL_VERSION_MICRO@)
@@ -62,10 +62,11 @@ G_BEGIN_DECLS
* @major : the major version number.
* @minor : the minor version number.
* @micro : the micro version number.
- *
- * Checks the version of the libxfce4panel library. Returns
- * %TRUE if the version of the libxfce4panel header files is
- * the same as or newer than the passed-in version.
+ *
+ * Checks the version of the libxfce4panel library.
+ *
+ * Returns: %TRUE if the version of the libxfce4panel header files is
+ * the same as or newer than the passed-in version.
**/
#define LIBXFCE4PANEL_CHECK_VERSION(major,minor,micro) \
(LIBXFCE4PANEL_MAJOR_VERSION > (major) \
diff --git a/libxfce4panel/xfce-arrow-button.c b/libxfce4panel/xfce-arrow-button.c
index d89b10a..a38856d 100644
--- a/libxfce4panel/xfce-arrow-button.c
+++ b/libxfce4panel/xfce-arrow-button.c
@@ -35,6 +35,22 @@
#include <libxfce4panel/xfce-arrow-button.h>
#include <libxfce4panel/libxfce4panel-alias.h>
+
+
+/**
+ * SECTION: xfce-arrow-button
+ * @title: XfceArrowButton
+ * @short_description: Toggle button with arrow
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Toggle button with (optional) arrow. The arrow direction will be
+ * inverted when the button is toggled.
+ * It is also possible to make the button blink and pack additional
+ * widgets in the button, using gtk_container_add().
+ **/
+
+
+
#define XFCE_ARROW_BUTTON_GET_PRIVATE(obj) (G_TYPE_INSTANCE_GET_PRIVATE ((obj), \
XFCE_TYPE_ARROW_BUTTON, \
XfceArrowButtonPrivate))
@@ -475,7 +491,8 @@ xfce_arrow_button_set_arrow_type (XfceArrowButton *button,
* xfce_arrow_button_get_blinking:
* @button : a #XfceArrowButton
*
- * Whether the button is blinking.
+ * Whether the button is blinking. If the blink timeout is finished
+ * and the button is still highlighted, this functions returns %FALSE.
*
* Returns: %TRUE when @button is blinking.
*
diff --git a/libxfce4panel/xfce-hvbox.c b/libxfce4panel/xfce-hvbox.c
index 223a7e7..45983a8 100644
--- a/libxfce4panel/xfce-hvbox.c
+++ b/libxfce4panel/xfce-hvbox.c
@@ -33,6 +33,24 @@
+/**
+ * SECTION: xfce-hvbox
+ * @title: XfceHVBox
+ * @short_description: Container widget with configurable orienation
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * #XfceHVBox is a #GtkBox widget that allows the user to change
+ * its orientation. It is in fact a combination of #GtkHBox and #GtkVBox.
+ *
+ * If your code depends on Gtk+ 2.16 or later, if it better to use
+ * the normal #GtkBox widgets in combination with
+ * gtk_orientable_set_orientation().
+ *
+ * See also: #GtkOrientable and #GtkBox.
+ **/
+
+
+
#if !GTK_CHECK_VERSION (2, 16, 0)
enum
{
@@ -76,6 +94,12 @@ xfce_hvbox_class_init (XfceHVBoxClass *klass)
gtkwidget_class->size_request = xfce_hvbox_size_request;
gtkwidget_class->size_allocate = xfce_hvbox_size_allocate;
+ /**
+ * XfceHVBox:orientation:
+ *
+ * The orientation of the #XfceHVBox. When compiled with Gtk+ 2.16,
+ * this is the orientation property of the #GtkOrientable.
+ **/
g_object_class_install_property (gobject_class,
PROP_ORIENTATION,
g_param_spec_enum ("orientation",
@@ -260,6 +284,8 @@ xfce_hvbox_set_orientation (XfceHVBox *hvbox,
* xfce_hvbox_get_orientation:
* @hvbox : #XfceHVBox
*
+ * TODO
+ *
* Returns: the current orientation of the #XfceHVBox.
**/
GtkOrientation
diff --git a/libxfce4panel/xfce-panel-convenience.c b/libxfce4panel/xfce-panel-convenience.c
index 01970c5..a618bd9 100644
--- a/libxfce4panel/xfce-panel-convenience.c
+++ b/libxfce4panel/xfce-panel-convenience.c
@@ -1,4 +1,3 @@
-/* $Id */
/*
* Copyright (C) 2006-2007 Jasper Huijsmans <jasper at xfce.org>
* Copyright (C) 2008-2009 Nick Schermer <nick at xfce.org>
@@ -29,6 +28,20 @@
#include <libxfce4panel/xfce-panel-convenience.h>
#include <libxfce4panel/libxfce4panel-alias.h>
+
+
+/**
+ * SECTION: xfce-panel-convenience
+ * @title: Convenience Functions
+ * @short_description: Special purpose widgets and utilities
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * This section describes a number of functions that were created
+ * to help developers of Xfce Panel plugins.
+ **/
+
+
+
/**
* xfce_panel_create_button:
*
diff --git a/libxfce4panel/xfce-panel-image.c b/libxfce4panel/xfce-panel-image.c
index c6ed868..a929187 100644
--- a/libxfce4panel/xfce-panel-image.c
+++ b/libxfce4panel/xfce-panel-image.c
@@ -32,6 +32,22 @@
#include <libxfce4panel/libxfce4panel-alias.h>
+
+/**
+ * SECTION: xfce-panel-image
+ * @title: XfcePanelImage
+ * @short_description: Scalable image suitable for panel plugins
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * The #XfcePanelImage is a widgets suitable for for example panel
+ * buttons where the developer does not exacly know the size of the
+ * image (due to theming and user setting).
+ *
+ * The #XfcePanelImage is a widget that will not
+ **/
+
+
+
/* design limit for the panel, to reduce the uncached pixbuf size */
#define MAX_PIXBUF_SIZE (128)
diff --git a/libxfce4panel/xfce-panel-macros.h b/libxfce4panel/xfce-panel-macros.h
index c15fd7e..bf70d2d 100644
--- a/libxfce4panel/xfce-panel-macros.h
+++ b/libxfce4panel/xfce-panel-macros.h
@@ -29,24 +29,118 @@
G_BEGIN_DECLS
+
+
+/**
+ * SECTION: xfce-panel-macros
+ * @title: Panel Plugin Macros
+ * @short_description: Various macros for registering panel plugin.
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Convenient macros to register #XfcePanelPlugin. This can be done
+ * by using a construct function or registering a new GObject with
+ * #XFCE_TYPE_PANEL_PLUGIN is parent type.
+ **/
+
+
+
+/**
+ * XfcePanelTypeModule:
+ *
+ * TODO
+ *
+ * Since: 4.8.0
+ **/
typedef GTypeModule XfcePanelTypeModule;
-/* xfconf channel for plugins */
+
+
+/**
+ * XFCE_PANEL_PLUGIN_CHANNEL_NAME:
+ *
+ * Macro for the name of the Xfconf channel used by the panel.
+ *
+ * See also: xfce_panel_plugin_xfconf_channel_new,
+ * xfce_panel_plugin_get_property_base
+ *
+ * Since: 4.8.0
+ **/
#define XFCE_PANEL_PLUGIN_CHANNEL_NAME ("xfce4-panel")
-/* macro for opening an XfconfChannel for plugins */
+
+
+/**
+ * xfce_panel_plugin_xfconf_channel_new:
+ * @plugin : An #XfcePanelPlugin.
+ *
+ * Convienient function for opening an XfconfChannel for a plugin. The
+ * channel's property base will be propery returned from
+ * xfce_panel_plugin_get_property_base().
+ *
+ * See also: xfce_panel_plugin_get_property_base,
+ * XFCE_PANEL_PLUGIN_CHANNEL_NAME
+ *
+ * Since: 4.8.0
+ **/
#define xfce_panel_plugin_xfconf_channel_new(plugin) \
xfconf_channel_new_with_property_base (XFCE_PANEL_PLUGIN_CHANNEL_NAME, \
xfce_panel_plugin_get_property_base (XFCE_PANEL_PLUGIN (plugin)))
-/* register a resident panel plugin */
-#define XFCE_PANEL_DEFINE_PLUGIN_RESIDENT(TypeName, type_name, args...) \
- _XPP_DEFINE_PLUGIN (TypeName, type_name, TRUE, args)
-/* register a panel plugin that can unload the module */
+
+/**
+ * XFCE_PANEL_DEFINE_PLUGIN:
+ * @TypeName : The name of the new type, in Camel case.
+ * @type_name : The name of the new type, in lowercase, with words separated by '_'.
+ * @args... : Optional list of *_register_type() function from other
+ * objects in the plugin created with #XFCE_PANEL_DEFINE_TYPE.
+ *
+ * Define a new (resident) GObject panel plugin, the parent type of the object
+ * should be XFCE_TYPE_PANEL_PLUGIN.
+ *
+ * Since: 4.8.0
+ **/
#define XFCE_PANEL_DEFINE_PLUGIN(TypeName, type_name, args...) \
_XPP_DEFINE_PLUGIN (TypeName, type_name, FALSE, args)
+
+
+/**
+ * XFCE_PANEL_DEFINE_PLUGIN_RESIDENT:
+ * @TypeName : The name of the new type, in Camel case.
+ * @type_name : The name of the new type, in lowercase, with words separated by '_'.
+ * @args... : Optional list of *_register_type() function from other
+ * objects in the plugin created with #XFCE_PANEL_DEFINE_TYPE.
+ *
+ * Same as #XFCE_PANEL_DEFINE_PLUGIN, but if you use special libraries or objects,
+ * it is possible the plugin will give problems when unloading the library,
+ * a resident plugin will never be unloaded after the first load, avoiding
+ * those issues.
+ *
+ * Since: 4.8.0
+ **/
+#define XFCE_PANEL_DEFINE_PLUGIN_RESIDENT(TypeName, type_name, args...) \
+ _XPP_DEFINE_PLUGIN (TypeName, type_name, TRUE, args)
+
+
+
+/**
+ * XFCE_PANEL_DEFINE_TYPE:
+ * @TypeName : The name of the new type, in Camel case.
+ * @type_name : The name of the new type, in lowercase, with words separated by '_'.
+ * @TYPE_PARENT : The GType of the parent type.
+ *
+ * A convenient macro of #G_DEFINE_DYNAMIC_TYPE for panel plugins. Only
+ * difference with #G_DEFINE_DYNAMIC_TYPE is that the type name send to
+ * g_type_module_register_type() is prefixed with "Xfce". This allows you
+ * use use shorted structure names in the code, while the real name of the
+ * object is a full "Xfce" name.
+ *
+ * The _register_type function should be added to the args in
+ * #XFCE_PANEL_DEFINE_PLUGIN.
+ *
+ * Since: 4.8.0
+ **/
#define XFCE_PANEL_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT) \
static gpointer type_name##_parent_class = NULL; \
static GType type_name##_type = 0; \
@@ -90,6 +184,9 @@ typedef GTypeModule XfcePanelTypeModule;
type_name##_type = plugin_define_type_id; \
}
+
+
+/* <private> */
#define _XPP_DEFINE_PLUGIN(TypeName, type_name, resident, args...) \
GType xfce_panel_module_init (GTypeModule *type_module, gboolean *make_resident); \
\
@@ -114,28 +211,38 @@ typedef GTypeModule XfcePanelTypeModule;
return type_name##_get_type (); \
}
+
+
/**
* XFCE_PANEL_PLUGIN_REGISTER:
- * construct_func : name of the function that points to an
- * #XfcePanelPluginFunc function.
+ * @construct_func : name of the function that points to an
+ * #XfcePanelPluginFunc function.
*
- * TODO
+ * Register a panel plugin using a construct function. This is the
+ * simplest way to register a panel plugin.
+ * The @construct_func is called everytime a plugin is created.
*
- * Since: 4.8
+ * Since: 4.8.0
**/
#define XFCE_PANEL_PLUGIN_REGISTER(construct_func) \
XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, /* foo */)
+
+
/**
* XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK:
- * construct_func : name of the function that points to an
- * #XfcePanelPluginFunc function.
- * check_func : name of the function that points to an
- * #XfcePanelPluginCheck function.
+ * @construct_func : name of the function that points to an
+ * #XfcePanelPluginFunc function.
+ * @check_func : name of the function that points to an
+ * #XfcePanelPluginCheck function.
*
- * TODO
+ * Register a panel plugin using a construct function. The @check_func
+ * will be called before the plugin is created. If this function returns
+ * %FALSE, the plugin won't be added to the panel. For proper feedback,
+ * you are responsible for showing a dialog why the plugin is not added
+ * to the panel.
*
- * Since: 4.8
+ * Since: 4.8.0
**/
#define XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK(construct_func, check_func) \
XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, \
@@ -143,16 +250,23 @@ typedef GTypeModule XfcePanelTypeModule;
/**
* XFCE_PANEL_PLUGIN_REGISTER_FULL:
- * construct_func : name of the function that points to an
- * #XfcePanelPluginFunc function.
- * preinit_func : name of the function that points to an
- * #XfcePanelPluginPreInit function.
- * check_func : name of the function that points to an
- * #XfcePanelPluginCheck function.
+ * @construct_func : name of the function that points to an
+ * #XfcePanelPluginFunc function.
+ * @preinit_func : name of the function that points to an
+ * #XfcePanelPluginPreInit function.
+ * @check_func : name of the function that points to an
+ * #XfcePanelPluginCheck function.
*
- * TODO
+ * Same as #XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK, but with a preinit
+ * function. This function is called before all the other functions and
+ * also before gtk_init(), so you can use this to enable threads or
+ * initialize other libraries/functions.
*
- * Since: 4.8
+ * Downside of this that the plugin cannot run internal. Even if you set
+ * X-XFCE-Interal=TRUE in the desktop file, the panel will force the
+ * plugin to run inside a wrapper.
+ *
+ * Since: 4.8.0
**/
#define XFCE_PANEL_PLUGIN_REGISTER_FULL(construct_func, preinit_func, check_func) \
XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, \
@@ -167,6 +281,8 @@ typedef GTypeModule XfcePanelTypeModule;
\
if (G_LIKELY ((*check_func) (xpp_screen) == TRUE)))
+
+
/* <private> */
#define XFCE_PANEL_PLUGIN_REGISTER_EXTENDED(construct_func, PREINIT_CODE, CHECK_CODE) \
static void \
diff --git a/libxfce4panel/xfce-panel-plugin.c b/libxfce4panel/xfce-panel-plugin.c
index 5d9f157..dd6c53b 100644
--- a/libxfce4panel/xfce-panel-plugin.c
+++ b/libxfce4panel/xfce-panel-plugin.c
@@ -31,6 +31,20 @@
#include <libxfce4panel/libxfce4panel-marshal.h>
#include <libxfce4panel/libxfce4panel-alias.h>
+
+
+/**
+ * SECTION: xfce-panel-plugin
+ * @title: XfcePanelPlugin
+ * @short_description: Interface for panel plugins
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * The interface plugin developers used to interact with the plugin and
+ * the panel.
+ **/
+
+
+
#define XFCE_PANEL_PLUGIN_CONSTRUCTED(plugin) \
PANEL_HAS_FLAG (XFCE_PANEL_PLUGIN (plugin)->priv->flags, \
PLUGIN_FLAG_CONSTRUCTED)
@@ -302,7 +316,7 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
* returned by xfce_panel_plugin_save_location(), the panel will take
* care of removing those settings.
*
- * Since: 4.8
+ * Since: 4.8.0
**/
plugin_signals[REMOVED] =
g_signal_new (g_intern_static_string ("removed"),
@@ -380,8 +394,8 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
*
* The internal, unstranslated, name of the #XfcePanelPlugin. Plugin
* writer can use it to read the plugin name, but
- * xfce_panel_plugin_get_name() is recommended since that
- * returns a const string.
+ * xfce_panel_plugin_get_name() is recommended since that returns
+ * a const string.
**/
g_object_class_install_property (gobject_class,
PROP_NAME,
@@ -1300,6 +1314,9 @@ xfce_panel_plugin_get_name (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_display_name:
* @plugin : an #XfcePanelPlugin.
*
+ * This returns the translated name of the plugin set in the .desktop
+ * file of the plugin.
+ *
* Returns: the (translated) display name of the plugin.
**/
const gchar *
@@ -1320,7 +1337,8 @@ xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_comment:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * This returns the translated comment of the plugin set in
+ * the .desktop file of the plugin.
*
* Returns: the (translated) comment of the plugin.
**/
@@ -1339,7 +1357,9 @@ xfce_panel_plugin_get_comment (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_unique_id:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The internal unique id of the plugin. Each plugin in the panel has
+ * a unique number that is for example used for the config file name
+ * or property base in the xfconf channel.
*
* Returns: the unique id of the plugin.
*
@@ -1360,7 +1380,8 @@ xfce_panel_plugin_get_unique_id (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_property_base:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The property base for this plugin in the xfce4-panel XfconfChannel,
+ * this name is something like /plugins/plugin-1.
*
* Returns: the property base for the xfconf channel userd by a plugin.
*
@@ -1385,9 +1406,15 @@ xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin)
/**
* xfce_panel_plugin_get_arguments:
- * @plugin : an #XfcePanelPlugin.
+ * @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Argument vector passed to the plugin when it was added. Most of the
+ * time the return value will be %NULL, but if could for example contain
+ * a list of filenames when the user added the plugin with
+ *
+ * xfce4-panel --add=launcher *.desktop
+ *
+ * see the code of the launcher plugin how to use this.
*
* Returns: the argument vector. The vector is owned by the plugin and
* should not be freed.
@@ -1409,7 +1436,7 @@ xfce_panel_plugin_get_arguments (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_size:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The size of the panel in which the plugin is embedded.
*
* Returns: the current size of the panel.
**/
@@ -1429,7 +1456,8 @@ xfce_panel_plugin_get_size (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_expand:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Whether the plugin is expanded or not. This set by the plugin using
+ * xfce_panel_plugin_set_expand().
*
* Returns: %TRUE when the plugin should expand,
* %FALSE otherwise.
@@ -1448,9 +1476,9 @@ xfce_panel_plugin_get_expand (XfcePanelPlugin *plugin)
/**
* xfce_panel_plugin_set_expand:
* @plugin : an #XfcePanelPlugin.
- * @expand : TODO.
+ * @expand : whether to expand the plugin.
*
- * TODO
+ * Wether the plugin should expand of not
**/
void
xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin,
@@ -1484,7 +1512,7 @@ xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin,
* xfce_panel_plugin_get_orientation:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The orientation of the panel in which the plugin is embedded.
*
* Returns: the current #GtkOrientation of the panel.
**/
@@ -1503,7 +1531,7 @@ xfce_panel_plugin_get_orientation (XfcePanelPlugin *plugin)
* xfce_panel_plugin_get_screen_position:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The screen position of the panel in which the plugin is embedded.
*
* Returns: the current #XfceScreenPosition of the panel.
**/
@@ -1523,7 +1551,9 @@ xfce_panel_plugin_get_screen_position (XfcePanelPlugin *plugin)
* @plugin : an #XfcePanelPlugin.
* @window : a #GtkWindow.
*
- * TODO
+ * Connect a dialog to the plugin. When the panel is closed or the
+ * plugin is removed from the panel, the window will be closed by
+ * the panel.
*
* Since: 4.8.0
**/
@@ -1546,9 +1576,12 @@ xfce_panel_plugin_take_window (XfcePanelPlugin *plugin,
/**
* xfce_panel_plugin_add_action_widget:
* @plugin : an #XfcePanelPlugin.
- * @widget : a #GtkWidget.
+ * @widget : a #GtkWidget that receives mouse events.
*
- * TODO
+ * Attach the plugin menu to this widget. Plugin writers should call this
+ * for every widget that can receive mouse events. If you forget to call this
+ * the plugin will not have a right-click menu and the user won't be able to
+ * remove it.
**/
void
xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin,
@@ -1569,7 +1602,8 @@ xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin,
* @plugin : an #XfcePanelPlugin.
* @item : a #GtkMenuItem.
*
- * TODO
+ * Insert a custom menu item to the plugin's right click menu. This item
+ * is packed below the "Move" menu item.
**/
void
xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin,
@@ -1593,7 +1627,8 @@ xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin,
* xfce_panel_plugin_menu_show_configure:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Show the "Properties" item in the menu. Clicking on the menu item
+ * will emit the "configure-plugin" signal.
**/
void
xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin)
@@ -1628,7 +1663,8 @@ xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin)
* xfce_panel_plugin_menu_show_about:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Show the "About" item in the menu. Clicking on the menu item
+ * will emit the "about" signal.
**/
void
xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin)
@@ -1661,9 +1697,10 @@ xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin)
/**
* xfce_panel_plugin_block_menu:
- * plugin : an #XfcePanelPlugin.
+ * @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Block configuring the plugin. This will make the "Properties" menu
+ * item insensitive.
**/
void
xfce_panel_plugin_block_menu (XfcePanelPlugin *plugin)
@@ -1678,9 +1715,10 @@ xfce_panel_plugin_block_menu (XfcePanelPlugin *plugin)
/**
* xfce_panel_plugin_unblock_menu:
- * plugin : an #XfcePanelPlugin.
+ * @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Unblock configuring the plugin. This will make the "Properties" menu
+ * item sensitive.
**/
void
xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin)
@@ -1698,9 +1736,18 @@ xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin)
/**
* xfce_panel_plugin_register_menu:
* @plugin : an #XfcePanelPlugin.
- * @menu : a #GtkMenu.
+ * @menu : a #GtkMenu that will be opened
*
- * TODO
+ * Register a menu tha is about to popup. This will make sure the panel
+ * will properly handle its autohide behaviour. You have to call this
+ * function every time the menu is opened (e.g. using gtk_popup_menu()).
+ *
+ * If you want to open the menu aligned to the side of the panel (and the
+ * plugin), you should use xfce_panel_plugin_position_menu() as
+ * #GtkMenuPositionFunc. This callback function will take care of calling
+ * xfce_panel_plugin_register_menu() as well.
+ *
+ * See also: xfce_panel_plugin_position_menu().
**/
void
xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin,
@@ -1729,11 +1776,10 @@ xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin,
* xfce_panel_plugin_arrow_type:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Determine the #GtkArrowType for a widget that opens a menu and uses
+ * xfce_panel_plugin_position_menu() to position the menu.
*
* Returns: the #GtkArrowType to use.
- *
- * Since: 4.6.0
**/
GtkArrowType
xfce_panel_plugin_arrow_type (XfcePanelPlugin *plugin)
@@ -1787,9 +1833,15 @@ xfce_panel_plugin_arrow_type (XfcePanelPlugin *plugin)
* @x : return location for the x coordinate.
* @y : return location for the x coordinate.
*
- * TODO
+ * The menu widget is positioned relative to @attach_widget.
+ * If @attach_widget is NULL, the menu widget is instead positioned
+ * relative to @panel_plugin.
+ *
+ * This function is intended for custom menu widgets.
+ * For a regular #GtkMenu you should use xfce_panel_plugin_position_menu()
+ * instead (as callback argument to gtk_menu_popup()).
*
- * Since: 4.6.0
+ * See also: xfce_panel_plugin_position_menu().
**/
void
xfce_panel_plugin_position_widget (XfcePanelPlugin *plugin,
@@ -1881,9 +1933,32 @@ xfce_panel_plugin_position_widget (XfcePanelPlugin *plugin,
* @push_in : keep inside the screen (see #GtkMenuPositionFunc)
* @panel_plugin : an #XfcePanelPlugin.
*
- * TODO
+ * Function to be used as #GtkMenuPositionFunc in a call to gtk_menu_popup().
+ * As data argument it needs an #XfcePanelPlugin.
+ *
+ * The menu is normally positioned relative to @panel_plugin. If you want the
+ * menu to be positioned relative to another widget, you can use
+ * gtk_menu_attach_to_widget() to explicitly set a 'parent' widget.
+ *
+ * As a convenience, xfce_panel_plugin_position_menu() calls
+ * xfce_panel_plugin_register_menu() for the menu.
*
- * Since: 4.6.0
+ * <example>
+ * void
+ * myplugin_popup_menu (XfcePanelPlugin *plugin,
+ * GtkMenu *menu,
+ * GdkEventButton *ev)
+ * {
+ * gtk_menu_popup (menu, NULL, NULL,
+ * xfce_panel_plugin_position_menu, plugin,
+ * ev->button, ev->time );
+ * }
+ * </example>
+ *
+ * For a custom widget that will be used as a popup menu, use
+ * xfce_panel_plugin_position_widget() instead.
+ *
+ * See also: gtk_menu_popup().
**/
void
xfce_panel_plugin_position_menu (GtkMenu *menu,
@@ -1919,9 +1994,8 @@ xfce_panel_plugin_position_menu (GtkMenu *menu,
* @plugin : an #XfcePanelPlugin.
* @widget : a #GtkWidget inside the plugins that should be focussed.
*
- * TODO
- *
- * Since: 4.6.0
+ * Grab the focus on @widget. Asks the panel to allow focus on its items
+ * and set the focus to the requested widget.
**/
void
xfce_panel_plugin_focus_widget (XfcePanelPlugin *plugin,
@@ -1947,8 +2021,6 @@ xfce_panel_plugin_focus_widget (XfcePanelPlugin *plugin,
* @blocked : TODO
*
* TODO
- *
- * Since: 4.6.0
**/
void
xfce_panel_plugin_block_autohide (XfcePanelPlugin *plugin,
diff --git a/libxfce4panel/xfce-panel-plugin.h b/libxfce4panel/xfce-panel-plugin.h
index 27626cd..ea61291 100644
--- a/libxfce4panel/xfce-panel-plugin.h
+++ b/libxfce4panel/xfce-panel-plugin.h
@@ -44,6 +44,11 @@ typedef gboolean (*XfcePanelPluginCheck) (GdkScreen *screen);
#define XFCE_IS_PANEL_PLUGIN_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), XFCE_TYPE_PANEL_PLUGIN))
#define XFCE_PANEL_PLUGIN_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), XFCE_TYPE_PANEL_PLUGIN, XfcePanelPluginClass))
+/**
+ * XfcePanelPluginClass:
+ *
+ * TODO
+ **/
struct _XfcePanelPluginClass
{
/*< private >*/
@@ -75,6 +80,12 @@ struct _XfcePanelPluginClass
void (*reserved4) (void);
};
+
+/**
+ * XfcePanelPlugin:
+ *
+ * TODO
+ **/
struct _XfcePanelPlugin
{
/*< private >*/
More information about the Xfce4-commits
mailing list