Browse Source

Add a lot of API documentation.

Something around 90% symbol coverage. This a lot to do, but a
big step forward.
upstream/xfce4-panel-4.10.1
Nick Schermer 12 years ago
parent
commit
a491436e1c
  1. 1
      docs/references/libxfce4panel-docs.xml
  2. 14
      docs/references/libxfce4panel-sections.txt
  3. 15
      libxfce4panel/libxfce4panel-config.c
  4. 27
      libxfce4panel/libxfce4panel-config.h.in
  5. 19
      libxfce4panel/xfce-arrow-button.c
  6. 26
      libxfce4panel/xfce-hvbox.c
  7. 15
      libxfce4panel/xfce-panel-convenience.c
  8. 16
      libxfce4panel/xfce-panel-image.c
  9. 164
      libxfce4panel/xfce-panel-macros.h
  10. 148
      libxfce4panel/xfce-panel-plugin.c
  11. 11
      libxfce4panel/xfce-panel-plugin.h

1
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">

14
docs/references/libxfce4panel-sections.txt

@ -83,6 +83,19 @@ XFCE_PANEL_IMAGE_GET_CLASS
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>
@ -125,4 +138,3 @@ XFCE_PANEL_PLUGIN_GET_CLASS
<SUBSECTION Private>
xfce_panel_plugin_get_type
</SECTION>

15
libxfce4panel/libxfce4panel-config.c

@ -25,6 +25,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:
*
@ -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;
}

27
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) \

19
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.
*

26
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

15
libxfce4panel/xfce-panel-convenience.c

@ -1,4 +1,3 @@
/* $Id */
/*
* Copyright (C) 2006-2007 Jasper Huijsmans <jasper@xfce.org>
* Copyright (C) 2008-2009 Nick Schermer <nick@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:
*

16
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)

164
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 \

148
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,

11
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 >*/

Loading…
Cancel
Save