Human Interface Guidelines for Panel Plugins

Find below the HIGs for the panel plugins. Keep in mind that those are here for reference and most probably for new plugins. There is a secondary page with proposed HIGs where you are free to add any HIGs you find useful to be noted.

For information about strings style please refer to this page.

UI consistency is an important aspect of a mature desktop like Xfce. On the other hand, there are tons of panel plugins out there, developed by many different people. A written set of UI guidelines will help those developers ensure their plugins maintain some basic level of consistency.

We're trying to do this in a wiki fashion, so everyone is welcome to improve this. When you add something new, put “[draft]” before it. This way, plugin developers know to keep an eye on it, and people can provide their comments. If you aren't sure how something should be handled but think it should be discussed, put “[rfc]” (request for comments) before it.

Most guidelines apply differently based on the plugin class. (“Class” here means bin or category - it is not used in the GObject sense). The document is split into sections for each of these classes. The guidelines that apply generally are listed in the “General” section.

If displaying a value in a tooltip, prefer the GtkTooltip API in favor of the GtkTooltips deprecated API. Using ''gtk_widget_set_tooltip_text()'' should be enought in most cases. If you need to update the tooltip more often than every 500ms (gtk default) you might need to set gtk-tooltip-timeout property on a GtkSettings instance.

 GtkSettings *settings;
 settings = gtk_settings_get_default();
 if (g_object_class_find_property(G_OBJECT_GET_CLASS(settings), "gtk-tooltip-timeout"))
   g_object_set(settings, "gtk-tooltip-timeout", update-interval - 10, NULL);

The right click context menu provides items with default actions like “Move”, “Delete”, and “Configure the panel”. It is possible to add predefined items like “About” and “Properties”.

The About item is seldomly used, which makes it recommended to not include it at all. But that option is left open to the plugin writer. In any case use

gtk_show_about_dialog()

Some plugins add a custom Help item inside this menu, but it is more common to put a Help button inside the properties dialog. Usually the user will want to open the properties dialog to have a better idea of the plugin. If you don't provide a properties dialog, you can have a reason to add a custom item.

In all Xfce applications it is common to apply the settings as they are changed in the dialog. Unless you are making more complex changes, avoid removing the sensitivity or to set the properties dialog modal.

If you are using a RC file to store the settings, you will need to save the settings when the dialog closes. This makes sure the user gets his settings back at any time when he has to restart the panel.

With Xfce 4.6+ you can use Xfconf, in which case the settings are saved as soon as they change. The Xfce 4.8+ Panel provides the macro xfce_panel_plugin_xfconf_channel_new() to acquire the Xfconf channel.

On a completely different note, when the properties dialog is open, the context menu must be blocked with xfce_panel_plugin_block_menu(). When the properties dialog is closed, it can then be unblock again with xfce_panel_plugin_unblock_menu().

The properties dialog should be created using xfce_titled_dialog_new_with_buttons() A subtitle can be set using xfce_titled_dialog_set_subtitle(), and a window icon reflecting the plugin should be set using gtk_window_set_icon_name().

The main UIs that are often reused between the plugins are described as close as possible below. So far there are 3 main UIs for a plugin: the button, the input and the monitor. Currently each plugin is written with custom Gtk+ widgets, and to make this more common it will be good to write GObjects at least for a common button and monitor.

Example of plugins using a button as their main UI: menu, places, notes, launcher, window list, mount, …

The main purpose of the button is to open an external window or to display a menu. In the case of a menu, it must be a toggle button and keep the state pressed as long as the menu is displayed.

Usually an image is put inside the button but it can have a label put besides it. The label has to be short to conserve space and it must be properly capitalized (e.g. “My Button”).

The button has to display the image at the left or at the top given the panel's orientation.

Labels should be oriented horizontally in the horizontal and deskbar mode and vertically (rotated clockwise) in the vertical mode.

(RFC) For consistency with other panel plugins and for good aligning of plugins in the panel, I'd suggest aligning all labels to the left edge of the plugin, or icon, if present. Currently many plugins center their labels, which looks poorly in the deskbar mode, or if multiple rows are used in other modes.

If plugin displays multiple rows of labels, it should preserve their native spacing (e.g. vbox with labels should be wrapped with a GtkAdjustment widget to prevent expanding the box).

If multiple labels don't fit in the panel row, then either some of them should be hidden/rearranged, or “small” property should be disabled.

If the plugin displays an icon-sized image, it should be aligned with the left edge (or top edge in the vertical mode) of the plugin. The size of the icon should match the size of icons embedded in buttons (launchers etc.). If all image sizes are same, the user may be able to set the size of the plugin in such a way that the images are not resized (resizing leads to smoothing the icon).

There are not many plugins using an input field for their main UI (for example verve and the dictionary).

The main UI is composed of an optional button (refer to the button class above) with only an image, and an input field (usually a GtkEntry widget).

Many plugins display a monitor and give the user the option of showing a label with a value reading, or both. The more “complete” plugin displaying as a monitor is the FS Guard plugin, it can display up to an image, a label with a value and a meter.

Plugin examples: system load monitor, battery monitor, sensors plugin, …

The different elements are contained inside a box, the border width of the box is 0, and the spacing between the children is 2 pixels. For the comments about the labels refer to the button class.

Some comments on the above design:

• IMHO it would be better to flush all labels to the left (align them with the icon) and to stop them expand vertically.
• It would be really nice to get rid of the progress bars. What if we could replace all the progress bars with custom indicators drawn on top of the icon itself?
  • They will never be properly aligned across rows (we could try putting them between the icon and the labels but what if there is no icon?).
  • It would be nice to use the above design in the deskbar mode as well, but currently if the number of rows is 1, labels and progress bars wouldn'd fit next to the icon.
  • It would be nice if the monitor plugin could display only an icon and still be useful (have the gauge displayed on it) - not too different from the mixer plugin.

The above would result in the following layout (mockup):

In a horizontal panel.

In a deskbar.

Note that the icons/labels are aligned wrt. each other, and that the monitor is still usable even if only icon is displayed.

The panel has three modes: horizontal, vertical, and deskbar.

• Widgets are placed horizontally
• Progressbars are placed vertically

• Widgets are placed vertically
• Labels are rotated to 90 degrees
• Progressbars are placed horizontally

• Widgets are placed vertically
• Composited widgets can be packed horizontally
• Labels are not rotated
• Progressbars are placed horizontally

The panel can be made from 16px tall to 128px tall, multiplied by the amount of rows : that makes a lot of combinations to test when designing an UI for a plugin, and one should try to make its UI consistent and usable in most sizes.

Widgets padding/size is important for consistency :

• Plugins have to set their container border width with gtk_container_set_border_width() to 1px for a panel size < 26px and 2px otherwise. Adjust it in the size-changed callback, which is called anyway in the panel creation.
• When displaying a frame around the plugin, the border has to be 0px for a size of < 26px and 1px otherwise.
• Plugins can set a default spacing between children in the container via the spacing parameter to xfce_hvbox_new()
• Labels should be packed (via gtk_box_pack_start() or gtk_container_add()) with a 2px padding.
• Progressbars, images and buttons should be packed with a 0px padding
• Progressbars should be 8px wide (when vertical, 8px tall when horizontal), use -1 for the other size to let the parent widget set the size.

If the plugin has an eventbox (to receive clicks or such), it should be made invisible to avoid problems with transparent/coloured panels. It should also be above its childs to actually receive events.

gtk_event_box_set_visible_window(GTK_EVENT_BOX(ebox), FALSE);
gtk_event_box_set_above_child(GTK_EVENT_BOX(ebox), TRUE);

plugins should set the small property (using xfce_panel_plugin_set_small()) only if they are intended to render on a single row, and not in deskbar mode. size-changed callback should take care of setting the widgets size taking into account the amount of rows. A common construct is to use

size /= xfce_panel_plugin_get_nrows (plugin)

before setting size on the various widgets.

The right-click menu should be accessible through all (if possible) widgets of the plugin. Generally you only need to use xfce_panel_plugin_add_action_widget() on the containing XfceHVBox to achieve that.