diff --git a/docs/Makefile.am b/docs/Makefile.am
index 9b6826627427e5fdaca570a6a5295a10e04e1fd6..66dcc2779cce40e6c5030ba115ce3b5a2c4ac7fd 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -1,9 +1,11 @@
SUBDIRS = \
references
-docdir = $(datadir)/doc/xfce4/Panel
doc_DATA = \
README.gtkrc-2.0 \
README.libxfce4panel
+EXTRA_DIST = \
+ $(doc_DATA)
+
# vi:set ts=8 sw=8 noet ai nocindent syntax=automake:
diff --git a/docs/references/Makefile.am b/docs/references/Makefile.am
index f354ac46ecf5768c51a9f4355489a1e45b2e786e..8db2c09d43def6c53a06230c675c8e91deb26a08 100644
--- a/docs/references/Makefile.am
+++ b/docs/references/Makefile.am
@@ -10,7 +10,7 @@ DOC_MODULE_VERSION=$(LIBXFCE4PANEL_VERSION_API)
DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
# Extra options to supply to gtkdoc-scan
-SCAN_OPTIONS=--deprecated-guards="XFCE_DISABLE_DEPRECATED"
+SCAN_OPTIONS=
# The directory containing the source code. Relative to $(srcdir)
DOC_SOURCE_DIR=../../libxfce4panel
@@ -18,7 +18,7 @@ DOC_SOURCE_DIR=../../libxfce4panel
# Extra options to supply to gtkdoc-mkdb
MKDB_OPTIONS=--output-format=xml --sgml-mode --name-space=xfce
-# Extra options to supply to gtkdoc-fixref
+# Extra options to supply to gtkdoc-fixxref
FIXXREF_OPTIONS=
# Used for dependencies
diff --git a/docs/references/libxfce4panel-docs.xml b/docs/references/libxfce4panel-docs.xml
index e505bd42b048c4c27b1d071ac559ca4e4029b1db..16ff243e7ffafc96e06a51a87f61e7be5984bf3e 100644
--- a/docs/references/libxfce4panel-docs.xml
+++ b/docs/references/libxfce4panel-docs.xml
@@ -9,7 +9,7 @@
<bookinfo>
<title>Libxfce4panel Reference Manual</title>
<releaseinfo>Version <xi:include href="version.xml" parse="text"/></releaseinfo>
- <pubdate>November 2009</pubdate>
+ <pubdate>Februari 2010</pubdate>
<copyright>
<year>2006</year>
@@ -19,7 +19,7 @@
<copyright>
<year>2008</year>
- <year>2009</year>
+ <year>2010</year>
<holder>Nick Schermer</holder>
</copyright>
@@ -46,16 +46,105 @@
</authorgroup>
</bookinfo>
- <part id="libxfce4panel-panel">
+ <part id="libxfce4panel-fundamentals">
+ <title>Fundamentals</title>
+
+ <xi:include href="xml/config.xml"/>
+ <xi:include href="xml/enums.xml"/>
+ <xi:include href="xml/macros.xml"/>
+ </part>
+
+ <part id="libxfce4panel-plugins">
<title>Panel Plugins</title>
+ <sect1 id="libxfce4panel-register">
+ <title>Register plugins with the panel</title>
+
+ <para>Since 4.8 there are various ways to register a plugin with the panel. Which option you
+ choose depends on a couple of things: is the plugin compiled as a module or as an
+ executable and do you want to write a plugin as a GObject.</para>
+
+ <sect2>
+ <title>Internal or external</title>
+
+ <para>In 4.6 you had to choose to compile a plugin as an executable to run it external (with
+ the appropriate macro to register external plugins) and the same for internal plugins that
+ were compiled a modules. This worked quite good, but had a couple of disadvantages:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>To switch between internal and external you needed to change the build system and
+ registration macros, so this was not very flexible.</para>
+ </listitem>
+ <listitem>
+ <para>When changes were made in the registration macros (esp the ones for external plugins)
+ a plugin had to recompile. Also each plugin copied the same piece of code.</para>
+ </listitem>
+ <listitem>
+ <para>Improvements in the panel communication (D-Bus) and transparant backgrounds where
+ either avoided or hard to implement.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>To work around those disadvantages Xfce Panel 4.8 introduced a new way to run plugins
+ that are compiled as modules in a separate process: a plugin wrapper. The plugin wrapper is started
+ by the panel for each external plugin and embeds the plugin module. It provides the communication
+ between the panel and the module using D-Bus and still has the big advantage of the 'old' exectuable
+ external plugin: if it crashes it won't crash the panel.</para>
+
+ <para>Whether a plugin is started internal or external is defined by the boolean in the
+ <varname>X-XFCE-Internal</varname> key in the plugins desktop file. No need to change the macros
+ and the registration macro code can be kept to an absolute minimum.</para>
+
+ <para>This does not mean the 4.6 executable plugins are no supported anymore. However if you write
+ a new plugin or you plugin depends on libxfce4panel 4.8, it is recommended to switch to the new
+ registration functions and compile your plugin as a module. To make this move obvious the old
+ macros are all marked as deprecated in this API reference.</para>
+ </sect2>
+
+ <sect2>
+ <title>GObject plugins</title>
+
+ <para>To handle the difference in 4.6 between internal and external plugins, the plugin API contained
+ 3 different types. There were two objects <structname>XfceInternalPanelPlugin</structname> and
+ <structname>XfceExternalPanelPlugin</structname> based on a different parents (resp.
+ <structname>GtkEventBox</structname> and <structname>GtkPlug</structname>) that both implemented the
+ <structname>XfcePanelPlugin</structname> interface.</para>
+
+ <para>Because internal and external is handled by the wrapper in 4.8, <structname>XfcePanelPlugin</structname>
+ is now a single object with <structname>GtkEventBox</structname> as parent. Apart from the fact that
+ this reduced a lot of code in libxfce4panel, it also has the advantage that it is easier to write
+ plugins as GObject with <varname>XFCE_TYPE_PANEL_PLUGIN</varname> as parent type. This brings a couple
+ of new advantages compared to plugins with register functions:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>You can easily cast you plugin to an <structname>XfcePanelPlugin</structname>, so
+ no need for custom structures. You also get all the GOBject features like type checking.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Downside is that you have to register all other types you create inside you plugin and that it
+ could be a bit difficult (when running internal) with special libraries. To work around the latter
+ you can make you plugin resident.</para>
+
+ <para>All the plugins shipped with the panel are written as GObjects, so you can find enough examples
+ in the <filename>plugins/</filename> folder.</para>
+ </sect2>
+
+ </sect1>
+
<xi:include href="xml/xfce-panel-plugin.xml"/>
- <xi:include href="xml/xfce-panel-macros.xml"/>
+ <xi:include href="xml/register-plugins.xml"/>
+ <xi:include href="xml/register-46-plugins.xml"/>
+ <xi:include href="xml/register-gobject-plugins.xml"/>
</part>
<part id="libxfce4panel-widgets">
<title>Additional Widgets</title>
+ <para>This section describes the additional widgets provided by the <application>xfce4-panel</application> library.</para>
+
<xi:include href="xml/xfce-arrow-button.xml"/>
<xi:include href="xml/xfce-hvbox.xml"/>
<xi:include href="xml/xfce-panel-image.xml"/>
@@ -64,18 +153,24 @@
<part id="libxfce4panel-miscelleanous">
<title>Miscelleanous</title>
- <xi:include href="xml/libxfce4panel-config.xml"/>
- <xi:include href="xml/xfce-panel-convenience.xml"/>
+ <xi:include href="xml/convenience.xml"/>
</part>
- <!--
- <part id="libxfce4panel-deprecated-widgets">
- <title>Deprecated widgets</title>
- </part>
- -->
-
- <index>
- <title>Index</title>
+ <index id="api-index-full">
+ <title>Index of all symbols</title>
+ <xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-deprecated" role="deprecated">
+ <title>Index of deprecated symbols</title>
+ <xi:include href="xml/api-index-deprecated.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-4-8" role="4.8">
+ <title>Index of new symbols in 4.8</title>
+ <xi:include href="xml/api-index-4.8.xml"><xi:fallback /></xi:include>
+ </index>
+ <index id="api-index-4-6" role="4.6">
+ <title>Index of new symbols in 4.6</title>
+ <xi:include href="xml/api-index-4.6.xml"><xi:fallback /></xi:include>
</index>
</book>
diff --git a/docs/references/libxfce4panel-sections.txt b/docs/references/libxfce4panel-sections.txt
index 348e6d49d0fa8a5c8e5532190b99963cab408736..eeba044f53f8e0024d8b91850398591396366dc5 100644
--- a/docs/references/libxfce4panel-sections.txt
+++ b/docs/references/libxfce4panel-sections.txt
@@ -1,6 +1,5 @@
<SECTION>
-<FILE>libxfce4panel-config</FILE>
-<TITLE>Version Information</TITLE>
+<FILE>config</FILE>
libxfce4panel_major_version
libxfce4panel_minor_version
libxfce4panel_micro_version
@@ -14,16 +13,16 @@ LIBXFCE4PANEL_CHECK_VERSION
<SECTION>
<FILE>xfce-arrow-button</FILE>
-<TITLE>XfceArrowButton</TITLE>
XfceArrowButton
-XfceArrowButtonClass
xfce_arrow_button_new
xfce_arrow_button_get_arrow_type
xfce_arrow_button_set_arrow_type
xfce_arrow_button_get_blinking
xfce_arrow_button_set_blinking
<SUBSECTION Standard>
+XfceArrowButtonClass
XfceArrowButtonPrivate
+XFCE_TYPE_ARROW_BUTTON
XFCE_ARROW_BUTTON
XFCE_IS_ARROW_BUTTON
XFCE_ARROW_BUTTON_CLASS
@@ -35,7 +34,6 @@ xfce_arrow_button_get_type
<SECTION>
<FILE>xfce-hvbox</FILE>
-<TITLE>XfceHVBox</TITLE>
XfceHVBox
xfce_hvbox_new
xfce_hvbox_set_orientation
@@ -53,15 +51,16 @@ xfce_hvbox_get_type
</SECTION>
<SECTION>
-<FILE>xfce-panel-convenience</FILE>
-<TITLE>Convenience Functions</TITLE>
+<FILE>convenience</FILE>
xfce_panel_create_button
xfce_panel_create_toggle_button
+xfce_allow_panel_customization
+xfce_create_panel_button
+xfce_create_panel_toggle_button
</SECTION>
<SECTION>
<FILE>xfce-panel-image</FILE>
-<TITLE>XfcePanelImage</TITLE>
XfcePanelImage
xfce_panel_image_new
xfce_panel_image_new_from_pixbuf
@@ -85,22 +84,38 @@ xfce_panel_image_get_type
</SECTION>
<SECTION>
-<FILE>xfce-panel-macros</FILE>
-<TITLE>Panel Plugin Macros</TITLE>
+<FILE>enums</FILE>
+XfceScreenPosition
+xfce_screen_position_get_orientation
+xfce_screen_position_is_bottom
+xfce_screen_position_is_floating
+xfce_screen_position_is_horizontal
+xfce_screen_position_is_left
+xfce_screen_position_is_right
+xfce_screen_position_is_top
+<SUBSECTION Standard>
+XFCE_TYPE_SCREEN_POSITION
+xfce_screen_position_get_type
+</SECTION>
+
+<SECTION>
+<FILE>macros</FILE>
XFCE_PANEL_CHANNEL_NAME
-xfce_panel_plugin_xfconf_channel_new
-XFCE_PANEL_DEFINE_PLUGIN
-XFCE_PANEL_DEFINE_PLUGIN_RESIDENT
-XFCE_PANEL_DEFINE_TYPE
-XFCE_PANEL_DEFINE_PREINIT_FUNC
-XFCE_PANEL_PLUGIN_REGISTER
-XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK
-XFCE_PANEL_PLUGIN_REGISTER_FULL
+<SUBSECTION>
+panel_slice_alloc
+panel_slice_alloc0
+panel_slice_free
+panel_slice_free1
+panel_slice_new
+panel_slice_new0
+<SUBSECTION>
+PANEL_PARAM_READABLE
+PANEL_PARAM_READWRITE
+PANEL_PARAM_WRITABLE
</SECTION>
<SECTION>
<FILE>xfce-panel-plugin</FILE>
-<TITLE>XfcePanelPlugin</TITLE>
XfcePanelPlugin
XfcePanelPluginClass
xfce_panel_plugin_get_name
@@ -131,6 +146,8 @@ xfce_panel_plugin_focus_widget
xfce_panel_plugin_block_autohide
xfce_panel_plugin_lookup_rc_file
xfce_panel_plugin_save_location
+xfce_panel_plugin_xfconf_channel_new
+xfce_panel_plugin_set_panel_hidden
<SUBSECTION Standard>
XfcePanelPluginPrivate
XFCE_TYPE_PANEL_PLUGIN
@@ -142,3 +159,32 @@ XFCE_PANEL_PLUGIN_GET_CLASS
<SUBSECTION Private>
xfce_panel_plugin_get_type
</SECTION>
+
+<SECTION>
+<FILE>register-plugins</FILE>
+XfcePanelPluginCheck
+XfcePanelPluginFunc
+XfcePanelPluginPreInit
+XFCE_PANEL_PLUGIN_REGISTER
+XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK
+XFCE_PANEL_PLUGIN_REGISTER_FULL
+</SECTION>
+
+<SECTION>
+<FILE>register-46-plugins</FILE>
+XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL
+XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL
+XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_WITH_CHECK
+<SUBSECTION>
+XFCE_PANEL_PLUGIN_REGISTER_INTERNAL
+XFCE_PANEL_PLUGIN_REGISTER_INTERNAL_WITH_CHECK
+</SECTION>
+
+<SECTION>
+<FILE>register-gobject-plugins</FILE>
+XfcePanelTypeModule
+XFCE_PANEL_DEFINE_PLUGIN
+XFCE_PANEL_DEFINE_PLUGIN_RESIDENT
+XFCE_PANEL_DEFINE_TYPE
+XFCE_PANEL_DEFINE_PREINIT_FUNC
+</SECTION>
diff --git a/libxfce4panel/Makefile.am b/libxfce4panel/Makefile.am
index cf0df657b7cfa45109f9a4e8f13265384a83dae4..4e126999f64f54e7744e4cac5346be43475f1767 100644
--- a/libxfce4panel/Makefile.am
+++ b/libxfce4panel/Makefile.am
@@ -22,12 +22,12 @@ libxfce4panel_built_sources = \
libxfce4panel_headers = \
libxfce4panel.h \
libxfce4panel-config.h \
- libxfce4panel-deprecated.h \
libxfce4panel-enums.h \
xfce-arrow-button.h \
xfce-hvbox.h \
xfce-panel-convenience.h \
xfce-panel-macros.h \
+ xfce-panel-macros-46.h \
xfce-panel-plugin.h \
xfce-panel-plugin-provider.h \
xfce-panel-image.h
@@ -130,4 +130,7 @@ if HAVE_GNUC_VISIBILITY
TESTS = abicheck.sh
endif
+# required for gtk-doc
+dist-hook: all
+
# vi:set ts=8 sw=8 noet ai nocindent syntax=automake:
diff --git a/libxfce4panel/abicheck.sh b/libxfce4panel/abicheck.sh
index 6370f07dcb83a61acee38a876c154650de816d80..43365b2488b750861fad3bf5f6f88b0288a165f5 100755
--- a/libxfce4panel/abicheck.sh
+++ b/libxfce4panel/abicheck.sh
@@ -19,5 +19,5 @@
#
cpp -P -DINCLUDE_INTERNAL_SYMBOLS -DINCLUDE_VARIABLES -DALL_FILES ${srcdir:-.}/libxfce4panel.symbols | sed -e '/^$/d' -e 's/ G_GNUC.*$//' -e 's/ PRIVATE//' | sort > expected-abi
-nm -D .libs/libxfce4panel.so | grep " T\|R " | cut -d ' ' -f 3 | grep -v '^_.*' | sort > actual-abi
+nm -D .libs/libxfce4panel-1.0.so | grep " T\|R " | cut -d ' ' -f 3 | grep -v '^_.*' | sort > actual-abi
diff -u expected-abi actual-abi && rm expected-abi actual-abi
diff --git a/libxfce4panel/libxfce4panel-config.c b/libxfce4panel/libxfce4panel-config.c
index 3eb52358174b0505742580736b84913284081bf3..02adfd694d553622765384b0ad2e469aabd421ec 100644
--- a/libxfce4panel/libxfce4panel-config.c
+++ b/libxfce4panel/libxfce4panel-config.c
@@ -26,7 +26,7 @@
/**
- * SECTION: libxfce4panel-config
+ * SECTION: config
* @title: Version Information
* @short_description: Information about the panel version in use.
* @include: libxfce4panel/libxfce4panel.h
@@ -47,6 +47,8 @@
* libxfce4panel library you have linked against. Contrast with the
* #LIBXFCE4PANEL_MAJOR_VERSION macro, which represents the major
* version of the libxfce4panel headers you have included.
+ *
+ * Since: 4.8
**/
const guint libxfce4panel_major_version = LIBXFCE4PANEL_MAJOR_VERSION;
@@ -62,6 +64,8 @@ const guint libxfce4panel_major_version = LIBXFCE4PANEL_MAJOR_VERSION;
* libxfce4panel library you have linked against. Contrast with the
* #LIBXFCE4PANEL_MINOR_VERSION macro, which represents the minor
* version of the libxfce4panel headers you have included.
+ *
+ * Since: 4.8
**/
const guint libxfce4panel_minor_version = LIBXFCE4PANEL_MINOR_VERSION;
@@ -77,6 +81,8 @@ const guint libxfce4panel_minor_version = LIBXFCE4PANEL_MINOR_VERSION;
* libxfce4panel library you have linked against. Contrast with the
* #LIBXFCE4PANEL_MICRO_VERSION macro, which represents the micro
* version of the libxfce4panel headers you have included.
+ *
+ * Since: 4.8
**/
const guint libxfce4panel_micro_version = LIBXFCE4PANEL_MICRO_VERSION;
@@ -112,6 +118,8 @@ const guint libxfce4panel_micro_version = LIBXFCE4PANEL_MICRO_VERSION;
* or a string describing the version mismatch. The returned
* string is owned by the library and must not be freed or
* modified by the caller.
+ *
+ * Since: 4.8
**/
G_CONST_RETURN gchar *
libxfce4panel_check_version (guint required_major,
diff --git a/libxfce4panel/libxfce4panel-config.h.in b/libxfce4panel/libxfce4panel-config.h.in
index ce72a76930a7143143d1b303994c8eb2fe118a32..f12622a1ebd34d27a647c437a25a344d52458ab2 100644
--- a/libxfce4panel/libxfce4panel-config.h.in
+++ b/libxfce4panel/libxfce4panel-config.h.in
@@ -34,6 +34,8 @@ G_BEGIN_DECLS
* Like libxfce4panel_major_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time.
+ *
+ * Since: 4.8
**/
#define LIBXFCE4PANEL_MAJOR_VERSION (@LIBXFCE4PANEL_VERSION_MAJOR@)
@@ -44,6 +46,8 @@ G_BEGIN_DECLS
* Like libxfce4panel_minor_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time.
+ *
+ * Since: 4.8
**/
#define LIBXFCE4PANEL_MINOR_VERSION (@LIBXFCE4PANEL_VERSION_MINOR@)
@@ -54,6 +58,8 @@ G_BEGIN_DECLS
* Like libxfce4panel_micro_version, but from the headers used at
* application compile time, rather than from the library
* linked against at application run time
+ *
+ * Since: 4.8
**/
#define LIBXFCE4PANEL_MICRO_VERSION (@LIBXFCE4PANEL_VERSION_MICRO@)
@@ -67,6 +73,8 @@ G_BEGIN_DECLS
*
* Returns: %TRUE if the version of the libxfce4panel header files is
* the same as or newer than the passed-in version.
+ *
+ * Since: 4.8
**/
#define LIBXFCE4PANEL_CHECK_VERSION(major,minor,micro) \
(LIBXFCE4PANEL_MAJOR_VERSION > (major) \
diff --git a/libxfce4panel/libxfce4panel-enums.h b/libxfce4panel/libxfce4panel-enums.h
index bc26d112fb1f0ff45144ed1fa12b8214a8d58325..03ee47acf42f94f39641cab6b8e0be9931011da6 100644
--- a/libxfce4panel/libxfce4panel-enums.h
+++ b/libxfce4panel/libxfce4panel-enums.h
@@ -28,6 +28,17 @@
G_BEGIN_DECLS
+/**
+ * SECTION: enums
+ * @title: Standard Enumerations
+ * @short_description: Standard enumerations used by the Xfce Panel.
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Currently only contains the definition of #XfceScreenPosition.
+ **/
+
+
+
/**
* XfceScreenPosition
* @XFCE_SCREEN_POSITION_NONE : No position has been set.
diff --git a/libxfce4panel/libxfce4panel.h b/libxfce4panel/libxfce4panel.h
index 363491163420fcfe425b1122d010f5ed4fa8db15..1930c339e82fe5be7eac0a3dbd950a827d3168c5 100644
--- a/libxfce4panel/libxfce4panel.h
+++ b/libxfce4panel/libxfce4panel.h
@@ -27,6 +27,7 @@ G_BEGIN_DECLS
#include <libxfce4panel/libxfce4panel-enums.h>
#include <libxfce4panel/libxfce4panel-enum-types.h>
#include <libxfce4panel/xfce-panel-macros.h>
+#include <libxfce4panel/xfce-panel-macros-46.h>
#include <libxfce4panel/xfce-arrow-button.h>
#include <libxfce4panel/xfce-hvbox.h>
#include <libxfce4panel/xfce-panel-convenience.h>
diff --git a/libxfce4panel/libxfce4panel.symbols b/libxfce4panel/libxfce4panel.symbols
index d22fa211cc6af9809933dae7c70182c7d96e9c0f..715bda580a0ccbc19c1d5b9160dfe45e10263e9a 100644
--- a/libxfce4panel/libxfce4panel.symbols
+++ b/libxfce4panel/libxfce4panel.symbols
@@ -31,6 +31,16 @@
#define IN_SOURCE(x) 1
#endif
+/* libxfce4panel-condif.h */
+#if IN_HEADER(__LIBXFCE4PANEL_CONFIG_H__)
+#if IN_SOURCE(__LIBXFCE4PANEL_CONFIG_C__)
+libxfce4panel_check_version
+libxfce4panel_major_version
+libxfce4panel_micro_version
+libxfce4panel_minor_version
+#endif
+#endif
+
/* libxfce4panel-enum-types.h */
#if IN_HEADER(__LIBXFCE4PANEL_ENUM_TYPES_H__)
#if IN_SOURCE(__LIBXFCE4PANEL_ENUM_TYPES_C__)
@@ -108,6 +118,7 @@ xfce_panel_plugin_block_menu
xfce_panel_plugin_unblock_menu
xfce_panel_plugin_register_menu
xfce_panel_plugin_arrow_type
+xfce_panel_plugin_remove
xfce_panel_plugin_position_widget
xfce_panel_plugin_position_menu
xfce_panel_plugin_focus_widget
@@ -134,5 +145,6 @@ xfce_panel_plugin_provider_get_show_about
xfce_panel_plugin_provider_show_about
xfce_panel_plugin_provider_removed
xfce_panel_plugin_provider_remote_event
+xfce_panel_plugin_provider_set_locked
#endif
#endif
diff --git a/libxfce4panel/xfce-arrow-button.c b/libxfce4panel/xfce-arrow-button.c
index 67426e3d1a7f563330f3eec46afbb15866779ded..ccb7f6ceecc4fe66afaa1c72090761c1098da8ae 100644
--- a/libxfce4panel/xfce-arrow-button.c
+++ b/libxfce4panel/xfce-arrow-button.c
@@ -45,7 +45,7 @@
*
* 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
+ * Since 4.8 it is also possible to make the button blink and pack additional
* widgets in the button, using gtk_container_add().
**/
@@ -496,7 +496,7 @@ xfce_arrow_button_set_arrow_type (XfceArrowButton *button,
*
* Returns: %TRUE when @button is blinking.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
gboolean
xfce_arrow_button_get_blinking (XfceArrowButton *button)
@@ -515,7 +515,7 @@ xfce_arrow_button_get_blinking (XfceArrowButton *button)
*
* Make the button blink.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
void
xfce_arrow_button_set_blinking (XfceArrowButton *button,
diff --git a/libxfce4panel/xfce-arrow-button.h b/libxfce4panel/xfce-arrow-button.h
index 0e9f3f142090a822e804a8156e7c68db2238725c..43587ec699e8ed44cf73badd7202c8d2009bf4e2 100644
--- a/libxfce4panel/xfce-arrow-button.h
+++ b/libxfce4panel/xfce-arrow-button.h
@@ -49,6 +49,12 @@ struct _XfceArrowButtonClass
GtkArrowType type);
};
+/**
+ * XfceArrowButton:
+ *
+ * This struct contain private data only and should be accessed by
+ * the functions below.
+ **/
struct _XfceArrowButton
{
/*< private >*/
diff --git a/libxfce4panel/xfce-hvbox.c b/libxfce4panel/xfce-hvbox.c
index 724d72ce231551e27a33d94fbb1f9dba9db633f3..5e198ab7b13357469e6ffda51deb5b4ed0d2f096 100644
--- a/libxfce4panel/xfce-hvbox.c
+++ b/libxfce4panel/xfce-hvbox.c
@@ -284,7 +284,7 @@ xfce_hvbox_set_orientation (XfceHVBox *hvbox,
* xfce_hvbox_get_orientation:
* @hvbox : #XfceHVBox
*
- * TODO
+ * Get the current orientation of the @hvbox.
*
* Returns: the current orientation of the #XfceHVBox.
**/
diff --git a/libxfce4panel/xfce-hvbox.h b/libxfce4panel/xfce-hvbox.h
index 7a08d8d7eeb13200c3a26e1f9a7ed5499044cf98..b2ad4f864c11caf616b8b89c6115c368f62da0e4 100644
--- a/libxfce4panel/xfce-hvbox.h
+++ b/libxfce4panel/xfce-hvbox.h
@@ -48,6 +48,12 @@ struct _XfceHVBoxClass
GtkBoxClass __parent__;
};
+/**
+ * XfceHVBox:
+ *
+ * This struct contain private data only and should be accessed by
+ * the functions below.
+ **/
struct _XfceHVBox
{
/*< private >*/
diff --git a/libxfce4panel/xfce-panel-convenience.c b/libxfce4panel/xfce-panel-convenience.c
index 506f0b0974c57e6260db68dbb326e7d02214c8eb..55dcf4eeebb089c4ceeb2ffd82d927505f666f27 100644
--- a/libxfce4panel/xfce-panel-convenience.c
+++ b/libxfce4panel/xfce-panel-convenience.c
@@ -31,7 +31,7 @@
/**
- * SECTION: xfce-panel-convenience
+ * SECTION: convenience
* @title: Convenience Functions
* @short_description: Special purpose widgets and utilities
* @include: libxfce4panel/libxfce4panel.h
diff --git a/libxfce4panel/xfce-panel-convenience.h b/libxfce4panel/xfce-panel-convenience.h
index 7ac1e834a69ea2691fc534c8969f7bcc0c8fc740..d09b60e98e92baa336c94f4e18786af7e065337f 100644
--- a/libxfce4panel/xfce-panel-convenience.h
+++ b/libxfce4panel/xfce-panel-convenience.h
@@ -25,7 +25,7 @@
#define __XFCE_PANEL_CONVENIENCE_H__
#include <gtk/gtk.h>
-#include <libxfce4panel/libxfce4panel-deprecated.h>
+#include <libxfce4panel/xfce-panel-macros-46.h>
G_BEGIN_DECLS
diff --git a/libxfce4panel/xfce-panel-image.c b/libxfce4panel/xfce-panel-image.c
index 6fb41b1800af9a3738f571884f2e9e6f71d92571..00e5d18fde1b7c145de563a7bc49872d26259f16 100644
--- a/libxfce4panel/xfce-panel-image.c
+++ b/libxfce4panel/xfce-panel-image.c
@@ -47,7 +47,13 @@
* 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
+ * The #XfcePanelImage widget automatically scales to the allocated
+ * size of the widget. Because of that nature it never requests a size,
+ * so this will only work if you pack the image in another widget
+ * that will expand it.
+ * If you want to force an image size you can use xfce_panel_image_set_size()
+ * to set a pixel size, in that case the widget will request an fixed size
+ * which makes it usefull for usage in dialogs.
**/
@@ -508,6 +514,15 @@ xfce_panel_image_scale_pixbuf (GdkPixbuf *source,
+/**
+ * xfce_panel_image_new:
+ *
+ * Creates a new empty #XfcePanelImage widget.
+ *
+ * returns: a newly created XfcePanelImage widget.
+ *
+ * Since: 4.8
+ **/
GtkWidget *
xfce_panel_image_new (void)
{
@@ -516,10 +531,24 @@ xfce_panel_image_new (void)
+/**
+ * xfce_panel_image_new_from_pixbuf:
+ * @pixbuf : a #GdkPixbuf, or %NULL.
+ *
+ * Creates a new #XfcePanelImage displaying @pixbuf. #XfcePanelImage
+ * will add its own reference rather than adopting yours. You don't
+ * need to scale the pixbuf to the correct size, the #XfcePanelImage
+ * will take care of that based on the allocation of the widget or
+ * the size set with xfce_panel_image_set_size().
+ *
+ * returns: a newly created XfcePanelImage widget.
+ *
+ * Since: 4.8
+ **/
GtkWidget *
xfce_panel_image_new_from_pixbuf (GdkPixbuf *pixbuf)
{
- g_return_val_if_fail (GDK_IS_PIXBUF (pixbuf), NULL);
+ g_return_val_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf), NULL);
return g_object_new (XFCE_TYPE_PANEL_IMAGE,
"pixbuf", pixbuf, NULL);
@@ -527,10 +556,25 @@ xfce_panel_image_new_from_pixbuf (GdkPixbuf *pixbuf)
+/**
+ * xfce_panel_image_new_from_source:
+ * @source : source of the image. This can be an absolute path or
+ * an icon-name or %NULL.
+ *
+ * Creates a new #XfcePanelImage displaying @source. #XfcePanelImage
+ * will detect if @source points to an absolute file or it and icon-name.
+ * For icon-names it will also look for files in the pixbuf folder or
+ * strip the extensions, which makes it suitable for usage with icon
+ * keys in .desktop files.
+ *
+ * returns: a newly created XfcePanelImage widget.
+ *
+ * Since: 4.8
+ **/
GtkWidget *
xfce_panel_image_new_from_source (const gchar *source)
{
- g_return_val_if_fail (source != NULL && *source != '\0', NULL);
+ g_return_val_if_fail (source == NULL || *source != '\0', NULL);
return g_object_new (XFCE_TYPE_PANEL_IMAGE,
"source", source, NULL);
@@ -538,12 +582,21 @@ xfce_panel_image_new_from_source (const gchar *source)
+/**
+ * xfce_panel_image_set_from_pixbuf:
+ * @image : an #XfcePanelImage.
+ * @pixbuf : a #GdkPixbuf, or %NULL.
+ *
+ * See xfce_panel_image_new_from_pixbuf() for details.
+ *
+ * Since: 4.8
+ **/
void
xfce_panel_image_set_from_pixbuf (XfcePanelImage *image,
GdkPixbuf *pixbuf)
{
g_return_if_fail (XFCE_IS_PANEL_IMAGE (image));
- g_return_if_fail (GDK_IS_PIXBUF (pixbuf));
+ g_return_if_fail (pixbuf == NULL || GDK_IS_PIXBUF (pixbuf));
xfce_panel_image_clear (image);
@@ -556,12 +609,22 @@ xfce_panel_image_set_from_pixbuf (XfcePanelImage *image,
+/**
+ * xfce_panel_image_set_from_source:
+ * @image : an #XfcePanelImage.
+ * @source : source of the image. This can be an absolute path or
+ * an icon-name or %NULL.
+ *
+ * See xfce_panel_image_new_from_source() for details.
+ *
+ * Since: 4.8
+ **/
void
xfce_panel_image_set_from_source (XfcePanelImage *image,
const gchar *source)
{
g_return_if_fail (XFCE_IS_PANEL_IMAGE (image));
- g_return_if_fail (source != NULL && *source != '\0');
+ g_return_if_fail (source == NULL || *source != '\0');
xfce_panel_image_clear (image);
@@ -572,6 +635,17 @@ xfce_panel_image_set_from_source (XfcePanelImage *image,
+/**
+ * xfce_panel_image_set_size:
+ * @image : an #XfcePanelImage.
+ * @size : a new size in pixels.
+ *
+ * This will force an image size, instead of looking at the allocation
+ * size, see introduction for more details. You can set a @size of
+ * -1 to turn this off.
+ *
+ * Since: 4.8
+ **/
void
xfce_panel_image_set_size (XfcePanelImage *image,
gint size)
@@ -588,6 +662,17 @@ xfce_panel_image_set_size (XfcePanelImage *image,
+/**
+ * xfce_panel_image_get_size:
+ * @image : an #XfcePanelImage.
+ *
+ * The size of the image, set by xfce_panel_image_set_size() or -1
+ * if no size is forced and the image is scaled to the allocation size.
+ *
+ * Returns: icon size in pixels of the image or -1.
+ *
+ * Since: 4.8
+ **/
gint
xfce_panel_image_get_size (XfcePanelImage *image)
{
@@ -597,6 +682,14 @@ xfce_panel_image_get_size (XfcePanelImage *image)
+/**
+ * xfce_panel_image_clear:
+ * @image : an #XfcePanelImage.
+ *
+ * Resets the image to be empty.
+ *
+ * Since: 4.8
+ **/
void
xfce_panel_image_clear (XfcePanelImage *image)
{
diff --git a/libxfce4panel/xfce-panel-image.h b/libxfce4panel/xfce-panel-image.h
index 3c53ca43a051c8dc58e98071b489231cf012ae3d..66f8bab79b5902d6e5b6386bfb00d84d92bfbfc1 100644
--- a/libxfce4panel/xfce-panel-image.h
+++ b/libxfce4panel/xfce-panel-image.h
@@ -39,8 +39,16 @@ struct _XfcePanelImageClass
/*< private >*/
void (*reserved1) (void);
void (*reserved2) (void);
+ void (*reserved3) (void);
+ void (*reserved4) (void);
};
+/**
+ * XfcePanelImage:
+ *
+ * This struct contain private data only and should be accessed by
+ * the functions below.
+ **/
struct _XfcePanelImage
{
/*< private >*/
diff --git a/libxfce4panel/libxfce4panel-deprecated.h b/libxfce4panel/xfce-panel-macros-46.h
similarity index 58%
rename from libxfce4panel/libxfce4panel-deprecated.h
rename to libxfce4panel/xfce-panel-macros-46.h
index ebd23b9c88eab8bcd6f068001994fe8bab5558be..2b7e85cc5fb85c9f54a489beb291158743e4dec0 100644
--- a/libxfce4panel/libxfce4panel-deprecated.h
+++ b/libxfce4panel/xfce-panel-macros-46.h
@@ -23,14 +23,21 @@
#ifndef __LIBXFCE4PANEL_DEPRECATED_H__
#define __LIBXFCE4PANEL_DEPRECATED_H__
-/* #ifndef XFCE_DISABLE_DEPRECATED */
#include <libxfce4panel/xfce-panel-plugin-provider.h>
#include <gdk/gdkx.h>
#include <stdlib.h>
-/* #endif *//* !XFCE_DISABLE_DEPRECATED */
G_BEGIN_DECLS
+/**
+ * SECTION: register-46-plugins
+ * @title: Panel Plugin Register Macros (4.6 Style)
+ * @short_description: The 4.6 way of registering plugins that compiled as executables
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Macros to register old external panel plugins that are compiled as executables.
+ **/
+
enum /*< skip >*/
{
PANEL_CLIENT_EVENT_REMOVED,
@@ -45,19 +52,119 @@ enum /*< skip >*/
PANEL_CLIENT_EVENT_SHOW_CONFIGURE
};
-#define PANEL_CLIENT_EVENT_ATOM "XFCE4_PANEL_PLUGIN_46"
+/*< private >*/
+#define _PANEL_CLIENT_EVENT_ATOM "XFCE4_PANEL_PLUGIN_46"
-/* #ifndef XFCE_DISABLE_DEPRECATED */
-#define panel_slice_alloc(block_size) (g_slice_alloc ((block_size)))
-#define panel_slice_alloc0(block_size) (g_slice_alloc0 ((block_size)))
+/**
+ * panel_slice_alloc:
+ * @block_size : the number of bytes to allocate
+ *
+ * See g_slice_alloc() for more information.
+ *
+ * Returns: a pointer to the allocated memory block
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_alloc() instead.
+ **/
+#define panel_slice_alloc(block_size) (g_slice_alloc ((block_size)))
+
+/**
+ * panel_slice_alloc0:
+ * @block_size : the number of bytes to allocate
+ *
+ * See g_slice_alloc0() for more information.
+ *
+ * Returns: a pointer to the allocated memory block
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_alloc0() instead.
+ **/
+#define panel_slice_alloc0(block_size) (g_slice_alloc0 ((block_size)))
+
+/**
+ * panel_slice_free1:
+ * @block_size : the size of the block
+ * @mem_block : a pointer to the block to free
+ *
+ * See g_slice_free1() for more information.
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_free1() instead.
+ **/
#define panel_slice_free1(block_size, mem_block) G_STMT_START{ g_slice_free1 ((block_size), (mem_block)); }G_STMT_END
-#define panel_slice_new(type) (g_slice_new (type))
-#define panel_slice_new0(type) (g_slice_new0 (type))
-#define panel_slice_free(type, ptr) G_STMT_START{ g_slice_free (type, (ptr)); }G_STMT_END
-#define PANEL_PARAM_READABLE (G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)
-#define PANEL_PARAM_WRITABLE (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)
+/**
+ * panel_slice_new:
+ * @type : the type to allocate, typically a structure name
+ *
+ * See g_slice_new() for more information.
+ *
+ * Returns: a pointer to the allocated memory block
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_new() instead.
+ **/
+#define panel_slice_new(type) (g_slice_new (type))
+
+/**
+ * panel_slice_new0:
+ * @type : the type to allocate, typically a structure name
+ *
+ * See g_slice_new0() for more information.
+ *
+ * Returns: a pointer to the allocated memory block
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_new0() instead.
+ **/
+#define panel_slice_new0(type) (g_slice_new0 (type))
+
+/**
+ * panel_slice_free:
+ * @type : the type to allocate, typically a structure name
+ * @ptr : a pointer to the block to free
+ *
+ * See g_slice_free() for more information.
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use g_slice_free() instead.
+ **/
+#define panel_slice_free(type, ptr) G_STMT_START{ g_slice_free (type, (ptr)); }G_STMT_END
+
+
+
+/**
+ * PANEL_PARAM_READABLE:
+ *
+ * Macro for #G_PARAM_READABLE with static strings.
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use #G_PARAM_READABLE
+ * | #G_PARAM_STATIC_STRINGS instead.
+ **/
+#define PANEL_PARAM_READABLE (G_PARAM_READABLE | G_PARAM_STATIC_STRINGS)
+
+/**
+ * PANEL_PARAM_WRITABLE:
+ *
+ * Macro for #PANEL_PARAM_WRITABLE with static strings.
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use #G_PARAM_WRITABLE
+ * | #G_PARAM_STATIC_STRINGS instead.
+ **/
+#define PANEL_PARAM_WRITABLE (G_PARAM_WRITABLE | G_PARAM_STATIC_STRINGS)
+
+/**
+ * PANEL_PARAM_READWRITE:
+ *
+ * Macro for #G_PARAM_READWRITE with static strings.
+ *
+ * Deprecated: 4.8: Deprecated because panel depends on recent enough
+ * version of glib. Use #G_PARAM_READWRITE
+ * | #G_PARAM_STATIC_STRINGS instead.
+ **/
#define PANEL_PARAM_READWRITE (G_PARAM_READWRITE | G_PARAM_STATIC_STRINGS)
#define _panel_assert(expr) g_assert (expr)
@@ -65,19 +172,106 @@ enum /*< skip >*/
#define _panel_return_if_fail(expr) g_return_if_fail (expr)
#define _panel_return_val_if_fail(expr, val) g_return_val_if_fail (expr, (val))
-#define xfce_create_panel_button xfce_panel_create_button
+
+/**
+ * xfce_create_panel_button:
+ *
+ * See xfce_panel_create_button() for more information.
+ *
+ * Deprecated: 4.8: Use xfce_panel_create_button() instead.
+ **/
+#define xfce_create_panel_button xfce_panel_create_button
+
+/**
+ * xfce_create_panel_toggle_button:
+ *
+ * See xfce_panel_create_toggle_button() for more information.
+ *
+ * Deprecated: 4.8: Use xfce_panel_create_toggle_button() instead.
+ **/
#define xfce_create_panel_toggle_button xfce_panel_create_toggle_button
+
+/**
+ * xfce_panel_plugin_set_panel_hidden:
+ * @plugin : an #XfcePanelPlugin.
+ * @hidden : new blocking state of this plugin.
+ *
+ * See xfce_panel_plugin_block_autohide() for more information.
+ *
+ * Deprecated: 4.8: Use xfce_panel_plugin_block_autohide() instead.
+ **/
+#define xfce_panel_plugin_set_panel_hidden(plugin, hidden) \
+ xfce_panel_plugin_block_autohide(plugin,hidden)
+
+/**
+ * xfce_allow_panel_customization:
+ *
+ * Always returns %FALSE. Plugins can be locked on a plugin basis
+ * level in the future, so this function is useless.
+ *
+ * Deprecated: 4.8: Look at xfce_panel_plugin_get_locked().
+ **/
#define xfce_allow_panel_customization (FALSE)
+/* <private >*/
#define _panel_g_type_register_simple(type_parent,type_name_static,class_size,class_init,instance_size,instance_init) \
g_type_register_static_simple(type_parent,type_name_static,class_size,class_init,instance_size,instance_init, 0)
+/**
+ * XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL:
+ * @construct_func : name of a function that can be cast to an
+ * #XfcePanelPluginFunc
+ *
+ * Registers and initializes the plugin. This is the only thing that is
+ * required to create a panel plugin.
+ *
+ * Deprecated: 4.8: Deprecation is not entirely true, but it should be made
+ * clear that it is recommended to use XFCE_PANEL_PLUGIN_REGISTER().
+ * See the <link linkend="libxfce4panel-register">Registering Plugins</link>
+ * for more information.
+ **/
#define XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL(construct_func) \
XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL (construct_func, NULL, NULL)
+/**
+ * XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_WITH_CHECK:
+ * @construct_func : name of a function that can be cast to an
+ * #XfcePanelPluginFunc
+ * @check_func : name of a function that can be cast to an
+ * #XfcePanelPluginCheck or %NULL
+ *
+ * Registers and initializes the plugin. This is the only thing that is
+ * required to create a panel plugin. The @check functions is run before
+ * creating the plugin, and should return FALSE if plugin creation is not
+ * possible.
+ *
+ * Deprecated: 4.8: Deprecation is not entirely true, but it should be made
+ * clear that it is recommended to use XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK().
+ * See the <link linkend="libxfce4panel-register">Registering Plugins</link>
+ * for more information.
+ **/
#define XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_WITH_CHECK(construct_func ,check_func) \
XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL (construct_func, NULL, check_func)
+/**
+ * XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL:
+ * @construct_func : name of a function that can be cast to an
+ * #XfcePanelPluginFunc
+ * @preinit_func : name of a function that can be case to #XfcePanelPluginPreInit
+ * or %NULL
+ * @check_func : name of a function that can be cast to an
+ * #XfcePanelPluginCheck or %NULL
+ *
+ * Same as XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_WITH_CHECK(), but with a
+ * preinit function that is called before gtk_init(). This allows plugins
+ * to initialize libraries or threads.
+ *
+ * Since: 4.6
+ * Deprecated: 4.8: Deprecation is not entirely true, but it should be made
+ * clear that it is recommended to use XFCE_PANEL_PLUGIN_REGISTER_FULL().
+ * See the <link linkend="libxfce4panel-register">Registering Plugins</link>
+ * for more information.
+ **/
#define XFCE_PANEL_PLUGIN_REGISTER_EXTERNAL_FULL(construct_func, preinit_func, check_func) \
static GdkAtom _xpp_atom = GDK_NONE; \
static gdouble _xpp_alpha = 1.00; \
@@ -307,7 +501,7 @@ enum /*< skip >*/
return PLUGIN_EXIT_CHECK_FAILED; \
} \
\
- _xpp_atom = gdk_atom_intern_static_string (PANEL_CLIENT_EVENT_ATOM); \
+ _xpp_atom = gdk_atom_intern_static_string (_PANEL_CLIENT_EVENT_ATOM); \
\
socket_id = strtol (argv[PLUGIN_ARGV_SOCKET_ID], NULL, 0); \
plug = gtk_plug_new (socket_id); \
@@ -350,7 +544,33 @@ enum /*< skip >*/
return PLUGIN_EXIT_SUCCESS; \
}
-/* #endif *//* !XFCE_DISABLE_DEPRECATED */
+
+
+/**
+ * XFCE_PANEL_PLUGIN_REGISTER_INTERNAL:
+ * @construct_func : name of a function that can be cast to an
+ * #XfcePanelPluginFunc
+ *
+ * See XFCE_PANEL_PLUGIN_REGISTER() for more information.
+ *
+ * Deprecated: 4.8: Use XFCE_PANEL_PLUGIN_REGISTER() instead.
+ **/
+#define XFCE_PANEL_PLUGIN_REGISTER_INTERNAL(construct_func) \
+ XFCE_PANEL_PLUGIN_REGISTER (construct_func)
+
+/**
+ * XFCE_PANEL_PLUGIN_REGISTER_INTERNAL_WITH_CHECK:
+ * @construct_func : name of a function that can be cast to an
+ * #XfcePanelPluginFunc
+ * @check_func : name of a function that can be cast to an
+ * #XfcePanelPluginCheck or %NULL
+ *
+ * See XFCE_PANEL_PLUGIN_REGISTER() for more information.
+ *
+ * Deprecated: 4.8: use XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK() instead.
+ **/
+#define XFCE_PANEL_PLUGIN_REGISTER_INTERNAL_WITH_CHECK(construct_func ,check_func) \
+ XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK (construct_func, check_func)
G_END_DECLS
diff --git a/libxfce4panel/xfce-panel-macros.h b/libxfce4panel/xfce-panel-macros.h
index f556569b520d0daabb282770dc71417917174148..e85443dd1955d03b2c8000cd1b8011df19e54750 100644
--- a/libxfce4panel/xfce-panel-macros.h
+++ b/libxfce4panel/xfce-panel-macros.h
@@ -25,21 +25,39 @@
#include <glib.h>
#include <libxfce4panel/xfce-panel-plugin.h>
-#include <libxfce4panel/libxfce4panel-deprecated.h>
+#include <libxfce4panel/xfce-panel-macros-46.h>
G_BEGIN_DECLS
/**
- * SECTION: xfce-panel-macros
- * @title: Panel Plugin Macros
- * @short_description: Various macros for registering panel plugin.
+ * SECTION: macros
+ * @title: Commonly used plugin macros
+ * @short_description: Various macros to make life easier for plugin developers.
* @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.
+ * Some commonly used macros in panel plugins.
+ **/
+
+/**
+ * SECTION: register-plugins
+ * @title: Panel Plugin Register Macros
+ * @short_description: Register panel plugins that are compiled as modules.
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Macros to register panel plugins that are compiled as modules. Internal or
+ * external is defined by the boolean key <varname>X-XFCE-Internal</varname>
+ * in the plugin's .desktop file.
+ **/
+
+/**
+ * SECTION: register-gobject-plugins
+ * @title: GObject Oriented Panel Plugin Registers Macros
+ * @short_description: Macros to register panel plugins, written as GObjects.
+ * @include: libxfce4panel/libxfce4panel.h
+ *
+ * Macros to register panel plugin types and custom types inside panel plugins.
**/
@@ -47,9 +65,9 @@ G_BEGIN_DECLS
/**
* XfcePanelTypeModule:
*
- * TODO
+ * Typedef for GTypeModule for possible future expansion.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
typedef GTypeModule XfcePanelTypeModule;
@@ -65,7 +83,7 @@ typedef GTypeModule XfcePanelTypeModule;
* See also: xfce_panel_plugin_xfconf_channel_new,
* xfce_panel_plugin_get_property_base
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_CHANNEL_NAME \
(G_LIKELY (g_getenv ("XFCE_PANEL_CHANNEL_NAME") == NULL) ? \
@@ -84,7 +102,7 @@ typedef GTypeModule XfcePanelTypeModule;
* See also: xfce_panel_plugin_get_property_base,
* XFCE_PANEL_PLUGIN_CHANNEL_NAME
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define xfce_panel_plugin_xfconf_channel_new(plugin) \
xfconf_channel_new_with_property_base (XFCE_PANEL_CHANNEL_NAME, \
@@ -102,7 +120,7 @@ typedef GTypeModule XfcePanelTypeModule;
* Define a new (resident) GObject panel plugin, the parent type of the object
* should be XFCE_TYPE_PANEL_PLUGIN.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_DEFINE_PLUGIN(TypeName, type_name, args...) \
_XPP_DEFINE_PLUGIN (TypeName, type_name, FALSE, args)
@@ -121,7 +139,7 @@ typedef GTypeModule XfcePanelTypeModule;
* a resident plugin will never be unloaded after the first load, avoiding
* those issues.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_DEFINE_PLUGIN_RESIDENT(TypeName, type_name, args...) \
_XPP_DEFINE_PLUGIN (TypeName, type_name, TRUE, args)
@@ -143,7 +161,7 @@ typedef GTypeModule XfcePanelTypeModule;
* The _register_type function should be added to the args in
* #XFCE_PANEL_DEFINE_PLUGIN.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_DEFINE_TYPE(TypeName, type_name, TYPE_PARENT) \
static gpointer type_name##_parent_class = NULL; \
@@ -234,7 +252,7 @@ typedef GTypeModule XfcePanelTypeModule;
* combination with the plugins register/define functions added
* in 4.8.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_DEFINE_PREINIT_FUNC(preinit_func) \
G_MODULE_EXPORT gboolean xfce_panel_module_preinit (gint argc, gchar **argv); \
@@ -257,10 +275,10 @@ typedef GTypeModule XfcePanelTypeModule;
* simplest way to register a panel plugin.
* The @construct_func is called everytime a plugin is created.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_PLUGIN_REGISTER(construct_func) \
- XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, /* foo */)
+ _XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, /* foo */)
@@ -277,10 +295,10 @@ typedef GTypeModule XfcePanelTypeModule;
* you are responsible for showing a dialog why the plugin is not added
* to the panel.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK(construct_func, check_func) \
- XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, \
+ _XFCE_PANEL_PLUGIN_REGISTER_EXTENDED (construct_func, /* foo */, \
if (G_LIKELY ((*check_func) (xpp_screen) == TRUE)))
@@ -298,7 +316,7 @@ typedef GTypeModule XfcePanelTypeModule;
* #XFCE_PANEL_PLUGIN_REGISTER_WITH_CHECK. See those macros
* for more information.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
#define XFCE_PANEL_PLUGIN_REGISTER_FULL(construct_func, preinit_func, check_func) \
XFCE_PANEL_DEFINE_PREINIT_FUNC (preinit_func) \
@@ -307,7 +325,7 @@ typedef GTypeModule XfcePanelTypeModule;
/* <private> */
-#define XFCE_PANEL_PLUGIN_REGISTER_EXTENDED(construct_func, PREINIT_CODE, CHECK_CODE) \
+#define _XFCE_PANEL_PLUGIN_REGISTER_EXTENDED(construct_func, PREINIT_CODE, CHECK_CODE) \
static void \
xfce_panel_module_realize (XfcePanelPlugin *xpp) \
{ \
diff --git a/libxfce4panel/xfce-panel-plugin.c b/libxfce4panel/xfce-panel-plugin.c
index 9b6ce4656034364f089c3f958f6294a173635632..a914932dbd9a4adc935383c9257c3852abacaf67 100644
--- a/libxfce4panel/xfce-panel-plugin.c
+++ b/libxfce4panel/xfce-panel-plugin.c
@@ -319,7 +319,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.0
+ * Since: 4.8
**/
plugin_signals[REMOVED] =
g_signal_new (g_intern_static_string ("removed"),
@@ -413,10 +413,10 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:display-name:
*
- * The display name of the #XfcePanelPlugin. This property is used during plugin
- * construction and can't be set twice. Plugin writer can use it to read the
- * plugin display name, but xfce_panel_plugin_get_display_name() is recommended
- * since that returns a const string.
+ * The translated display name of the #XfcePanelPlugin. This property is set
+ * during plugin construction and can't be set twice. Plugin writer can use
+ * it to read the plugin display name, but xfce_panel_plugin_get_display_name()
+ * is recommended.
**/
g_object_class_install_property (gobject_class,
PROP_DISPLAY_NAME,
@@ -431,9 +431,12 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:comment:
*
- * TODO
+ * The translated description of the #XfcePanelPlugin. This property is set
+ * during plugin construction and can't be set twice. Plugin writer can use
+ * it to read the plugin description, but xfce_panel_plugin_get_comment()
+ * is recommended.
*
- * Since 4.8.0
+ * Since: 4.8
**/
g_object_class_install_property (gobject_class,
PROP_COMMENT,
@@ -448,8 +451,11 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:id:
*
- * The unique id of the #XfcePanelPlugin. Plugin writer can use it to
- * read the unique id, but xfce_panel_plugin_get_unique_id() is recommended.
+ * The unique id of the #XfcePanelPlugin. This property is set during plugin
+ * construction and can't be set twice. Plugin writer can use it to read the
+ * plugin display name, but xfce_panel_plugin_get_unique_id() is recommended.
+ *
+ * Since: 4.8
**/
g_object_class_install_property (gobject_class,
PROP_UNIQUE_ID,
@@ -482,7 +488,8 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:orientation:
*
- * TODO
+ * The #GtkOrientation of the #XfcePanelPlugin. Plugin writer can use it to read the
+ * plugin orientation, but xfce_panel_plugin_get_orientation() is recommended.
**/
g_object_class_install_property (gobject_class,
PROP_ORIENTATION,
@@ -497,7 +504,8 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:size:
*
- * TODO
+ * The size in pixels of the #XfcePanelPlugin. Plugin writer can use it to read the
+ * plugin size, but xfce_panel_plugin_get_size() is recommended.
**/
g_object_class_install_property (gobject_class,
PROP_SIZE,
@@ -511,7 +519,9 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:screen-position:
*
- * TODO
+ * The #XfceScreenPosition of the #XfcePanelPlugin. Plugin writer can use it
+ * to read the plugin's screen position, but xfce_panel_plugin_get_screen_psotion()
+ * is recommended.
**/
g_object_class_install_property (gobject_class,
PROP_SCREEN_POSITION,
@@ -526,7 +536,9 @@ xfce_panel_plugin_class_init (XfcePanelPluginClass *klass)
/**
* XfcePanelPlugin:expand:
*
- * TODO
+ * Wether the #XfcePanelPlugin expands on the panel. Plugin writes can use it
+ * to read or set this property, but xfce_panel_plugin_set_expand()
+ * is recommended.
**/
g_object_class_install_property (gobject_class,
PROP_EXPAND,
@@ -1328,7 +1340,7 @@ xfce_panel_plugin_take_window_notify (gpointer data,
* xfce_panel_plugin_get_name:
* @plugin : an #XfcePanelPlugin.
*
- * TODO
+ * The internal name of the panel plugin.
*
* Returns: the name of the panel plugin.
**/
@@ -1374,6 +1386,8 @@ xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin)
* the .desktop file of the plugin.
*
* Returns: the (translated) comment of the plugin.
+ *
+ * Since: 4.8
**/
G_CONST_RETURN gchar *
xfce_panel_plugin_get_comment (XfcePanelPlugin *plugin)
@@ -1452,7 +1466,7 @@ xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin)
* Returns: the argument vector. The vector is owned by the plugin and
* should not be freed.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
G_CONST_RETURN gchar * G_CONST_RETURN *
xfce_panel_plugin_get_arguments (XfcePanelPlugin *plugin)
@@ -1582,11 +1596,10 @@ xfce_panel_plugin_get_screen_position (XfcePanelPlugin *plugin)
* @plugin : an #XfcePanelPlugin.
* @window : a #GtkWindow.
*
- * 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.
+ * Connect a dialog to a plugin. When the @plugin is closed, it will
+ * destroy the @window.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
void
xfce_panel_plugin_take_window (XfcePanelPlugin *plugin,
@@ -1722,7 +1735,7 @@ xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin)
/**
- * xfce_panel_plugin_remove:
+ * xfce_panel_plugin_get_locked:
* @plugin : an #XfcePanelPlugin.
*
* Whether the plugin is locked (not allowing customization). This
@@ -1738,7 +1751,7 @@ xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin)
* Returns: %TRUE if the user is not allowed to modify the plugin,
* %FALSE is customization is allowed.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
gboolean
xfce_panel_plugin_get_locked (XfcePanelPlugin *plugin)
@@ -1761,7 +1774,7 @@ xfce_panel_plugin_get_locked (XfcePanelPlugin *plugin)
* in case the there are problems with the plugin in the panel. Always
* try to inform the user why this occured.
*
- * Since: 4.8.0
+ * Since: 4.8
**/
void
xfce_panel_plugin_remove (XfcePanelPlugin *plugin)
@@ -1818,7 +1831,7 @@ xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin)
* @plugin : an #XfcePanelPlugin.
* @menu : a #GtkMenu that will be opened
*
- * Register a menu tha is about to popup. This will make sure the panel
+ * Register a menu that 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()).
*
@@ -1827,7 +1840,7 @@ xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin)
* #GtkMenuPositionFunc. This callback function will take care of calling
* xfce_panel_plugin_register_menu() as well.
*
- * See also: xfce_panel_plugin_position_menu().
+ * See also: xfce_panel_plugin_position_menu() and xfce_panel_plugin_block_autohide().
**/
void
xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin,
@@ -2098,9 +2111,15 @@ xfce_panel_plugin_focus_widget (XfcePanelPlugin *plugin,
/**
* xfce_panel_plugin_block_autohide:
* @plugin : an #XfcePanelPlugin.
- * @blocked : TODO
+ * @blocked : new blocking state of this plugin.
+ *
+ * Wether this plugin blocks the autohide functality of the panel. Use
+ * this when you 'popup' something that is visually attached to the
+ * plugin at it will look weird for a user if the panel will hide while
+ * he/she is working in the popup.
*
- * TODO
+ * For menus it there is xfce_panel_plugin_register_menu() which will
+ * take care of this.
**/
void
xfce_panel_plugin_block_autohide (XfcePanelPlugin *plugin,
diff --git a/libxfce4panel/xfce-panel-plugin.h b/libxfce4panel/xfce-panel-plugin.h
index df20626d43c1092f975de9832d2673e0572edcec..4f5a394ecb3fbc2de7e2e8ddf4e618ea13062aa2 100644
--- a/libxfce4panel/xfce-panel-plugin.h
+++ b/libxfce4panel/xfce-panel-plugin.h
@@ -25,7 +25,7 @@
#include <gtk/gtk.h>
#include <libxfce4panel/libxfce4panel-enums.h>
-#include <libxfce4panel/libxfce4panel-deprecated.h>
+#include <libxfce4panel/xfce-panel-macros-46.h>
G_BEGIN_DECLS
@@ -33,8 +33,44 @@ typedef struct _XfcePanelPluginPrivate XfcePanelPluginPrivate;
typedef struct _XfcePanelPluginClass XfcePanelPluginClass;
typedef struct _XfcePanelPlugin XfcePanelPlugin;
+/**
+ * XfcePanelPluginFunc:
+ * @plugin : an #XfcePanelPlugin
+ *
+ * Callback function to create the plugin contents. It should be given as
+ * the argument to the registration macros.
+ **/
typedef void (*XfcePanelPluginFunc) (XfcePanelPlugin *plugin);
-typedef gboolean (*XfcePanelPluginPreInit) (gint argc, gchar **argv);
+
+/**
+ * XfcePanelPluginPreInit:
+ * @argc: number of arguments to the plugin
+ * @argv: argument array
+ *
+ * Callback function that is run in an external plugin before gtk_init(). It
+ * should return %FALSE if the plugin is not available for whatever reason.
+ * The function can be given as argument to one of the registration macros.
+ *
+ * The main purpose of this callback is to allow multithreaded plugins to call
+ * g_thread_init().
+ *
+ * Returns: %TRUE on success, %FALSE otherwise.
+ *
+ * Since: 4.6
+ **/
+typedef gboolean (*XfcePanelPluginPreInit) (gint argc,
+ gchar **argv);
+
+/**
+ * XfcePanelPluginCheck:
+ * @screen : the #GdkScreen the panel is running on
+ *
+ * Callback function that is run before creating a plugin. It should return
+ * %FALSE if the plugin is not available for whatever reason. The function
+ * can be given as argument to one of the registration macros.
+ *
+ * Returns: %TRUE if the plugin can be started, %FALSE otherwise.
+ **/
typedef gboolean (*XfcePanelPluginCheck) (GdkScreen *screen);
#define XFCE_TYPE_PANEL_PLUGIN (xfce_panel_plugin_get_type ())
@@ -46,18 +82,36 @@ typedef gboolean (*XfcePanelPluginCheck) (GdkScreen *screen);
/**
* XfcePanelPluginClass:
+ * @construct : This function is for object orientated plugins and
+ * triggered after the init function of the object.
+ * When this function is triggered, the plugin
+ * information like name, display name, comment and unique
+ * id are available. This is also the place where you would
+ * call functions like xfce_panel_plugin_menu_show_configure().
+ * You can see this as the replacement of #XfcePanelPluginFunc
+ * for object based plugins. Since 4.8.
+ * @screen_position_changed : See #XfcePanelPlugin::screen-position-changed for more information.
+ * @size_changed : See #XfcePanelPlugin::size-changed for more information.
+ * @orientation_changed : See #XfcePanelPlugin::orientation-changed for more information.
+ * @free_data : See #XfcePanelPlugin::free-data for more information.
+ * @save : See #XfcePanelPlugin::save for more information.
+ * @about : See #XfcePanelPlugin::about for more information.
+ * @configure_plugin : See #XfcePanelPlugin::configure-plugin for more information.
+ * @removed : See #XfcePanelPlugin::removed for more information.
+ * @remote_event : See #XfcePanelPlugin::remote-event for more information.
*
- * TODO
+ * Class of an #XfcePanelPlugin. The interface can be used to create GObject based plugin.
**/
struct _XfcePanelPluginClass
{
/*< private >*/
GtkEventBoxClass __parent__;
- /*< object oriented plugins >*/
+ /*< public >*/
+ /* for object oriented plugins only */
void (*construct) (XfcePanelPlugin *plugin);
- /*< signals >*/
+ /* signals */
void (*screen_position_changed) (XfcePanelPlugin *plugin,
XfceScreenPosition position);
gboolean (*size_changed) (XfcePanelPlugin *plugin,
@@ -84,7 +138,8 @@ struct _XfcePanelPluginClass
/**
* XfcePanelPlugin:
*
- * TODO
+ * This struct contain private data only and should be accessed by
+ * the functions below.
**/
struct _XfcePanelPlugin
{
diff --git a/panel/panel-plugin-external-46.c b/panel/panel-plugin-external-46.c
index 55a10d2948d44f04f5b4105426b0a7a9ebe05c14..6adf3091f319897fa4b493fcc472122b5ac39752 100644
--- a/panel/panel-plugin-external-46.c
+++ b/panel/panel-plugin-external-46.c
@@ -199,7 +199,7 @@ panel_plugin_external_46_class_init (PanelPluginExternal46Class *klass)
EXO_PARAM_READWRITE
| G_PARAM_CONSTRUCT_ONLY));
- panel_atom = gdk_atom_intern_static_string (PANEL_CLIENT_EVENT_ATOM);
+ panel_atom = gdk_atom_intern_static_string (_PANEL_CLIENT_EVENT_ATOM);
}
diff --git a/plugins/applicationsmenu/Makefile.am b/plugins/applicationsmenu/Makefile.am
index e97f51847227d8cf4a508979638a5a9e3cea95d1..cd0190069c2142d3601d0ad06f5f8989c1fb0fac 100644
--- a/plugins/applicationsmenu/Makefile.am
+++ b/plugins/applicationsmenu/Makefile.am
@@ -66,10 +66,12 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
EXTRA_DIST = \
applicationsmenu-dialog.glade \
+ xfce4-popup-applicationsmenu.in \
$(desktop_in_files)
DISTCLEANFILES = \
- $(desktop_DATA)
+ $(desktop_DATA) \
+ xfce4-popup-applicationsmenu
if MAINTAINER_MODE
BUILT_SOURCES = \
diff --git a/plugins/directorymenu/Makefile.am b/plugins/directorymenu/Makefile.am
index 2bc0762a76c3692e9a209775c20188e3f9474284..69f02b242ab05a92ad09f58083e15aa4b4d0f927 100644
--- a/plugins/directorymenu/Makefile.am
+++ b/plugins/directorymenu/Makefile.am
@@ -68,10 +68,12 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
EXTRA_DIST = \
directorymenu-dialog.glade \
+ xfce4-popup-directorymenu.in \
$(desktop_in_files)
DISTCLEANFILES = \
- $(desktop_DATA)
+ $(desktop_DATA) \
+ xfce4-popup-directorymenu
if MAINTAINER_MODE
BUILT_SOURCES = \
diff --git a/plugins/windowmenu/Makefile.am b/plugins/windowmenu/Makefile.am
index 78711a2bc49a8f7455e74d9f7434faedd61a8386..6ba845ca71478e33551548b6680d989d862ec2cf 100644
--- a/plugins/windowmenu/Makefile.am
+++ b/plugins/windowmenu/Makefile.am
@@ -67,10 +67,12 @@ desktop_DATA = $(desktop_in_files:.desktop.in=.desktop)
EXTRA_DIST = \
windowmenu-dialog.glade \
+ xfce4-popup-windowmenu.in \
$(desktop_in_files)
DISTCLEANFILES = \
- $(desktop_DATA)
+ $(desktop_DATA) \
+ xfce4-popup-windowmenu
if MAINTAINER_MODE
BUILT_SOURCES = \
diff --git a/po/POTFILES.in b/po/POTFILES.in
index 40c86f68e13f4e6a657e564628b8308ee32edb32..1845f537cc8471a6099e85f731464b072bd7ab07 100644
--- a/po/POTFILES.in
+++ b/po/POTFILES.in
@@ -52,6 +52,8 @@ wrapper/wrapper-module.h
wrapper/wrapper-plug.c
wrapper/wrapper-plug.h
+migrate/main.c
+
plugins/actions/actions-dialog.glade
plugins/actions/actions.c
plugins/actions/actions.desktop.in