![]() |
![]() |
![]() |
Libxfce4panel Reference Manual | ![]() |
---|---|---|---|---|
Top | Description |
#include <libxfce4panel/libxfce4panel.h> XfcePanelPlugin; XfcePanelPluginClass; const gchar * xfce_panel_plugin_get_name (XfcePanelPlugin *plugin); const gchar * xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin); const gchar * xfce_panel_plugin_get_comment (XfcePanelPlugin *plugin); gint xfce_panel_plugin_get_unique_id (XfcePanelPlugin *plugin); const gchar * xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin); const gchar * const * xfce_panel_plugin_get_arguments (XfcePanelPlugin *plugin); gint xfce_panel_plugin_get_size (XfcePanelPlugin *plugin); gboolean xfce_panel_plugin_get_expand (XfcePanelPlugin *plugin); void xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin, gboolean expand); GtkOrientation xfce_panel_plugin_get_orientation (XfcePanelPlugin *plugin); XfceScreenPosition xfce_panel_plugin_get_screen_position (XfcePanelPlugin *plugin); gboolean xfce_panel_plugin_get_locked (XfcePanelPlugin *plugin); void xfce_panel_plugin_take_window (XfcePanelPlugin *plugin, GtkWindow *window); void xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin, GtkWidget *widget); void xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin, GtkMenuItem *item); void xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin); void xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin); void xfce_panel_plugin_remove (XfcePanelPlugin *plugin); void xfce_panel_plugin_block_menu (XfcePanelPlugin *plugin); void xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin); void xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin, GtkMenu *menu); GtkArrowType xfce_panel_plugin_arrow_type (XfcePanelPlugin *plugin); void xfce_panel_plugin_position_widget (XfcePanelPlugin *plugin, GtkWidget *menu_widget, GtkWidget *attach_widget, gint *x, gint *y); void xfce_panel_plugin_position_menu (GtkMenu *menu, gint *x, gint *y, gboolean *push_in, gpointer panel_plugin); void xfce_panel_plugin_focus_widget (XfcePanelPlugin *plugin, GtkWidget *widget); void xfce_panel_plugin_block_autohide (XfcePanelPlugin *plugin, gboolean blocked); gchar * xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin); gchar * xfce_panel_plugin_save_location (XfcePanelPlugin *plugin, gboolean create); #define xfce_panel_plugin_xfconf_channel_new(plugin) #define xfce_panel_plugin_set_panel_hidden (plugin, hidden)
typedef struct { } XfcePanelPlugin;
This struct contain private data only and should be accessed by the functions below.
typedef struct { /* for object oriented plugins only */ void (*construct) (XfcePanelPlugin *plugin); /* signals */ void (*screen_position_changed) (XfcePanelPlugin *plugin, XfceScreenPosition position); gboolean (*size_changed) (XfcePanelPlugin *plugin, gint size); void (*orientation_changed) (XfcePanelPlugin *plugin, GtkOrientation orientation); void (*free_data) (XfcePanelPlugin *plugin); void (*save) (XfcePanelPlugin *plugin); void (*about) (XfcePanelPlugin *plugin); void (*configure_plugin) (XfcePanelPlugin *plugin); void (*removed) (XfcePanelPlugin *plugin); gboolean (*remote_event) (XfcePanelPlugin *plugin, const gchar *name, const GValue *value); } XfcePanelPluginClass;
Class of an XfcePanelPlugin. The interface can be used to create GObject based plugin.
|
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.
|
|
See "screen-position-changed" for more information. |
|
See "size-changed" for more information. |
|
See "orientation-changed" for more information. |
|
See "free-data" for more information. |
|
See "save" for more information. |
|
See "about" for more information. |
|
See "configure-plugin" for more information. |
|
See "removed" for more information. |
|
See "remote-event" for more information. |
const gchar * xfce_panel_plugin_get_name (XfcePanelPlugin *plugin);
The internal name of the panel plugin.
|
an XfcePanelPlugin. |
Returns : |
the name of the panel plugin. |
const gchar * xfce_panel_plugin_get_display_name (XfcePanelPlugin *plugin);
This returns the translated name of the plugin set in the .desktop file of the plugin.
|
an XfcePanelPlugin. |
Returns : |
the (translated) display name of the plugin. |
const gchar * xfce_panel_plugin_get_comment (XfcePanelPlugin *plugin);
This returns the translated comment of the plugin set in the .desktop file of the plugin.
|
an XfcePanelPlugin. |
Returns : |
the (translated) comment of the plugin. |
Since 4.8
gint xfce_panel_plugin_get_unique_id (XfcePanelPlugin *plugin);
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.
|
an XfcePanelPlugin. |
Returns : |
the unique id of the plugin. Since 4.8 |
const gchar * xfce_panel_plugin_get_property_base (XfcePanelPlugin *plugin);
The property base for this plugin in the xfce4-panel XfconfChannel, this name is something like /plugins/plugin-1.
|
an XfcePanelPlugin. |
Returns : |
the property base for the xfconf channel userd by a plugin. See also: xfconf_channel_new_with_property_base. XFCE_PANEL_PLUGIN_CHANNEL_NAME and xfce_panel_get_channel_name |
const gchar * const * xfce_panel_plugin_get_arguments (XfcePanelPlugin *plugin);
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.
|
an XfcePanelPlugin. |
Returns : |
the argument vector. The vector is owned by the plugin and should not be freed. |
Since 4.8
gint xfce_panel_plugin_get_size (XfcePanelPlugin *plugin);
The size of the panel in which the plugin is embedded.
|
an XfcePanelPlugin. |
Returns : |
the current size of the panel. |
gboolean xfce_panel_plugin_get_expand (XfcePanelPlugin *plugin);
Whether the plugin is expanded or not. This set by the plugin using
xfce_panel_plugin_set_expand()
.
|
an XfcePanelPlugin. |
Returns : |
TRUE when the plugin should expand,
FALSE otherwise.
|
void xfce_panel_plugin_set_expand (XfcePanelPlugin *plugin, gboolean expand);
Wether the plugin should expand of not
|
an XfcePanelPlugin. |
|
whether to expand the plugin. |
GtkOrientation xfce_panel_plugin_get_orientation (XfcePanelPlugin *plugin);
The orientation of the panel in which the plugin is embedded.
|
an XfcePanelPlugin. |
Returns : |
the current GtkOrientation of the panel. |
XfceScreenPosition xfce_panel_plugin_get_screen_position (XfcePanelPlugin *plugin);
The screen position of the panel in which the plugin is embedded.
|
an XfcePanelPlugin. |
Returns : |
the current XfceScreenPosition of the panel. |
gboolean xfce_panel_plugin_get_locked (XfcePanelPlugin *plugin);
Whether the plugin is locked (not allowing customization). This is emitted through the panel based on the Xfconf locking of the panel window the plugin is embedded on.
It is however possible to send a fake signal to the plugin to override this propery, so you should only use this for interface elements and (if you use Xfconf) check the locking yourself before you write any values or query the kiosk mode using the api in libxfce4util.
|
an XfcePanelPlugin. |
Returns : |
TRUE if the user is not allowed to modify the plugin,
FALSE is customization is allowed.
|
Since 4.8
void xfce_panel_plugin_take_window (XfcePanelPlugin *plugin, GtkWindow *window);
Connect a dialog to a plugin. When the plugin
is closed, it will
destroy the window
.
|
an XfcePanelPlugin. |
|
a GtkWindow. |
Since 4.8
void xfce_panel_plugin_add_action_widget (XfcePanelPlugin *plugin, GtkWidget *widget);
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.
|
an XfcePanelPlugin. |
|
a GtkWidget that receives mouse events. |
void xfce_panel_plugin_menu_insert_item (XfcePanelPlugin *plugin, GtkMenuItem *item);
Insert a custom menu item to the plugin's right click menu. This item is packed below the "Move" menu item.
|
an XfcePanelPlugin. |
|
a GtkMenuItem. |
void xfce_panel_plugin_menu_show_configure (XfcePanelPlugin *plugin);
Show the "Properties" item in the menu. Clicking on the menu item will emit the "configure-plugin" signal.
|
an XfcePanelPlugin. |
void xfce_panel_plugin_menu_show_about (XfcePanelPlugin *plugin);
Show the "About" item in the menu. Clicking on the menu item will emit the "about" signal.
|
an XfcePanelPlugin. |
void xfce_panel_plugin_remove (XfcePanelPlugin *plugin);
Remove this plugin from the panel and remove all its configuration.
Plugins should not use this function to implement their own menu item or button to remove theirselfs from the panel, but only in case the there are problems with the plugin in the panel. Always try to inform the user why this occured.
|
an XfcePanelPlugin. |
Since 4.8
void xfce_panel_plugin_block_menu (XfcePanelPlugin *plugin);
Block configuring the plugin. This will make the "Properties" menu item insensitive.
|
an XfcePanelPlugin. |
void xfce_panel_plugin_unblock_menu (XfcePanelPlugin *plugin);
Unblock configuring the plugin. This will make the "Properties" menu item sensitive.
|
an XfcePanelPlugin. |
void xfce_panel_plugin_register_menu (XfcePanelPlugin *plugin, GtkMenu *menu);
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()
).
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()
and xfce_panel_plugin_block_autohide()
.
|
an XfcePanelPlugin. |
|
a GtkMenu that will be opened |
GtkArrowType xfce_panel_plugin_arrow_type (XfcePanelPlugin *plugin);
Determine the GtkArrowType for a widget that opens a menu and uses
xfce_panel_plugin_position_menu()
to position the menu.
|
an XfcePanelPlugin. |
Returns : |
the GtkArrowType to use. |
void xfce_panel_plugin_position_widget (XfcePanelPlugin *plugin, GtkWidget *menu_widget, GtkWidget *attach_widget, gint *x, gint *y);
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()
).
See also: xfce_panel_plugin_position_menu()
.
|
an XfcePanelPlugin. |
|
a GtkWidget that will be used as popup menu. |
|
a GtkWidget relative to which the menu should be positioned. |
|
return location for the x coordinate. |
|
return location for the x coordinate. |
void xfce_panel_plugin_position_menu (GtkMenu *menu, gint *x, gint *y, gboolean *push_in, gpointer panel_plugin);
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.
Example 2.
For a custom widget that will be used as a popup menu, use
xfce_panel_plugin_position_widget()
instead.
See also: gtk_menu_popup()
.
|
a GtkMenu. |
|
return location for the x coordinate. |
|
return location for the y coordinate. |
|
keep inside the screen (see GtkMenuPositionFunc) |
|
an XfcePanelPlugin. |
void xfce_panel_plugin_focus_widget (XfcePanelPlugin *plugin, GtkWidget *widget);
Grab the focus on widget
. Asks the panel to allow focus on its items
and set the focus to the requested widget.
|
an XfcePanelPlugin. |
|
a GtkWidget inside the plugins that should be focussed. |
void xfce_panel_plugin_block_autohide (XfcePanelPlugin *plugin, gboolean blocked);
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.
For menus it there is xfce_panel_plugin_register_menu()
which will
take care of this.
|
an XfcePanelPlugin. |
|
new blocking state of this plugin. |
gchar * xfce_panel_plugin_lookup_rc_file (XfcePanelPlugin *plugin);
Looks for the plugin resource file. This should be used to get the plugin read location of the config file. You should only use the returned path to read information from, since it might point to a not-writable file (in kiosk mode for example).
See also: xfce_panel_plugin_save_location()
and xfce_resource_lookup()
|
an XfcePanelPlugin. |
Returns : |
The path to a config file or NULL if no file was found.
The returned string must be freed using g_free()
|
gchar * xfce_panel_plugin_save_location (XfcePanelPlugin *plugin, gboolean create);
Returns the path that can be used to store configuration information.
Don't use this function if you want to read from the config file, but
use xfce_panel_plugin_rc_location()
instead.
See also: xfce_panel_plugin_rc_location()
and xfce_resource_save_location()
|
an XfcePanelPlugin. |
|
whether to create missing directories. |
Returns : |
The path to a config file or NULL if no file was found.
The returned string must be freed u sing g_free() .
|
#define xfce_panel_plugin_xfconf_channel_new(plugin)
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 and xfce_panel_get_channel_name
|
An XfcePanelPlugin. |
Since 4.8
#define xfce_panel_plugin_set_panel_hidden(plugin, hidden)
xfce_panel_plugin_set_panel_hidden
has been deprecated since version 4.8 and should not be used in newly-written code. Use xfce_panel_plugin_block_autohide()
instead.
See xfce_panel_plugin_block_autohide()
for more information.
|
an XfcePanelPlugin. |
|
new blocking state of this plugin. |