Differences
This shows you the differences between two versions of the page.
Both sides previous revisionPrevious revisionNext revision | Previous revisionNext revisionBoth sides next revision | ||
dev:hig:panel-plugins [2009/01/10 06:57] – introduce the general topics mike | dev:hig:panel-plugins [2012/06/03 19:06] – [Size] mike | ||
---|---|---|---|
Line 2: | Line 2: | ||
Find below the HIGs for the panel plugins. | Find below the HIGs for the panel plugins. | ||
+ | |||
+ | For information about strings style please refer to this [[style: | ||
+ | |||
+ | ===== About ===== | ||
+ | |||
+ | ==== Rationale ==== | ||
+ | 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. | ||
+ | |||
+ | ==== Process ==== | ||
+ | We're trying to do this in a wiki fashion, so everyone is welcome to improve this. When you add something new, put " | ||
+ | |||
+ | ==== Plugin Classes ==== | ||
+ | Most guidelines apply differently based on the plugin class. (" | ||
+ | |||
===== General ===== | ===== General ===== | ||
+ | ==== Tooltip ==== | ||
+ | |||
+ | If displaying a value in a tooltip, prefer the GtkTooltip API in favor of the GtkTooltips deprecated API. Using [[http:// | ||
+ | |||
+ | < | ||
+ | | ||
+ | | ||
+ | if (g_object_class_find_property(G_OBJECT_GET_CLASS(settings), | ||
+ | | ||
+ | </ | ||
==== Context Menu ==== | ==== Context Menu ==== | ||
The right click context menu provides items with default actions like " | The right click context menu provides items with default actions like " | ||
- | 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. | + | 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. |
Some plugins add a custom Help item inside this menu, but it is more common to put a Help button inside the properties 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. | ||
Line 19: | Line 43: | ||
If you are using a RC file to store the settings, you will need to save the settings when the dialog closes. | If you are using a RC file to store the settings, you will need to save the settings when the dialog closes. | ||
- | With Xfce 4.6+ you can use Xfconf, in which case the settings are saved as soon as they change. | + | 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 [[http:// | ||
+ | |||
+ | The properties dialog should be created using '' | ||
+ | A subtitle can be set using '' | ||
+ | |||
+ | ===== Main UIs ===== | ||
+ | |||
+ | The main UIs that are often reused between the plugins are described as close as possible below. | ||
+ | |||
+ | ==== Button ==== | ||
+ | |||
+ | 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' | ||
+ | |||
+ | ==== Labels ==== | ||
+ | |||
+ | Labels should be oriented horizontally | ||
+ | |||
+ | (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, | ||
+ | |||
+ | 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 | ||
+ | |||
+ | If multiple labels don't fit in the panel row, then either some of them should be hidden/ | ||
+ | |||
+ | ==== Images or Icons ==== | ||
+ | |||
+ | 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). | ||
+ | |||
+ | ==== Input ==== | ||
+ | |||
+ | 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). | ||
+ | |||
+ | ==== Monitor ==== | ||
+ | |||
+ | Many plugins display a monitor and give the user the option of showing a label with a value reading, or both. | ||
+ | |||
+ | {{http:// | ||
+ | |||
+ | 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. | ||
+ | |||
+ | 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 | ||
+ | * 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): | ||
+ | |||
+ | {{http://img837.imageshack.us/img837/2050/ | ||
+ | |||
+ | In a horizontal panel. | ||
+ | |||
+ | {{http://img85.imageshack.us/ | ||
+ | |||
+ | In a deskbar. | ||
+ | |||
+ | Note that the icons/ | ||
+ | ===== Panel properties ===== | ||
+ | |||
+ | ==== Mode ==== | ||
+ | |||
+ | The panel has three modes: horizontal, vertical, and deskbar. | ||
+ | |||
+ | === Horizontal mode === | ||
+ | * Widgets are placed horizontally | ||
+ | * Progressbars are placed vertically | ||
+ | |||
+ | === Vertical mode === | ||
+ | * Widgets are placed vertically | ||
+ | * Labels are rotated to 90 degrees | ||
+ | * Progressbars are placed horizontally | ||
+ | |||
+ | === Deskbar mode === | ||
+ | * Widgets are placed vertically | ||
+ | * Composited widgets can be packed horizontally | ||
+ | * Labels are not rotated | ||
+ | * Progressbars are placed horizontally | ||
+ | |||
+ | ==== Size ==== | ||
+ | |||
+ | Two category of sizes can be distinguished for the panel: small and large size. | ||
+ | |||
+ | === Padding === | ||
+ | |||
+ | * Plugins that include a padding have to stick to 1px for a size < 28px and 2px otherwise. | ||
+ | * When displaying a frame around the plugin, the padding has to be 0px for a size of < 28px and 1px otherwise. | ||
+ | ==== number of rows ==== | ||
+ | |||
+ | plugins should set the '' | ||
+ | < | ||
+ | size /= xfce_panel_plugin_get_nrows (plugin) | ||
+ | </ | ||
+ | before setting size on the various widgets. | ||
+ | ==== Action widget ==== | ||
+ | The right-click menu should be accessible through all (if possible) widgets of the plugin. Generally you only need to use '' |