# &package_name; Reference Manual

For &package_string;. The latest version of this documentation can be found on-line at https://developer.xfce.org/&package_name;/.
2024
The Xfce development team

## Fundamentals

## Panel Plugins

### Register plugins with the panel

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.

#### Internal or external

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:

- To switch between internal and external you needed to change the build system and registration macros, so this was not very flexible.

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

- Improvements in the panel communication (D-Bus) and transparant backgrounds where either avoided or hard to implement.

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.

Whether a plugin is started internal or external is defined by the boolean in the `X-XFCE-Internal` key in the plugins desktop file. No need to change the macros and the registration macro code can be kept to an absolute minimum.

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.

#### GObject plugins

To handle the difference in 4.6 between internal and external plugins, the plugin API contained 3 different types. There were two objects XfceInternalPanelPlugin and XfceExternalPanelPlugin based on a different parents (resp. GtkEventBox and GtkPlug) that both implemented the XfcePanelPlugin interface.

Because internal and external is handled by the wrapper in 4.8, XfcePanelPlugin is now a single object with GtkEventBox 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 `XFCE_TYPE_PANEL_PLUGIN` as parent type. This brings a couple of new advantages compared to plugins with register functions:

- You can easily cast you plugin to an XfcePanelPlugin, so no need for custom structures. You also get all the GOBject features like type checking.

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.

All the plugins shipped with the panel are written as GObjects, so you can find enough examples in the `plugins/` folder.

## Additional Widgets

This section describes the additional widgets provided by the xfce4-panel library.

## Miscelleanous

## Index of all symbols

## Index of deprecated symbols

## Index of new symbols in 4.20

## Index of new symbols in 4.18

## Index of new symbols in 4.14

## Index of new symbols in 4.10

## Index of new symbols in 4.8

## Index of new symbols in 4.6