This is an old revision of the document!
Human Interface Guidelines for Panel Plugins
This page is very much a work-in-progress at the moment. Feel free to contribute. Discussion page.
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 “[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.
Plugin Classes
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.
General
Tooltips
- [rfc] Indentation for sublevel entries should be: 2 spaces? 4 spaces? \t?
- ongardie 2007/12/18 05:51 Screenshots would be helpful [added below]
- ongardie 2007/12/21 01:51 I think I like 2 spaces the best, personally.
Context Menu
- [rfc] Help/About?
- ongardie 2007/12/18 05:51 The current trend is to not include these at all but to put information on the plugin web site.
- fabian 2007/12/18 22:47 GMT Well, some plugins just run the opposite trend: Disk Performance Monitor, Quiklauncher, Genmon.
- I wouldn't say that just because 3 plugins are providing quick help that we should annoy every devs freedom to add something like that. The plugins are simple to use, usually the help is helpless. We do keep stuff on the goodies website like summary, documenation, latest version, … — Mike Massonnet 2007/12/30 05:32
- Some plugins have a dialog with a Help button which opens a webpage. I think this is best you can do in your plugins. — Mike Massonnet 2008/01/02 07:37
- To clarify, Mike meant to say they display a Help button in their preferences/properties dialog. See battery monitor or clipman. — Diego Ongaro 2008/01/06 01:11
- The three plugins fabian pointed out just show an About item in their context menu. Each of those about dialogs is rather poor, IMHO. Help has to be added manually to the context menu, and I agree with Mike in that its almost always unnecessary. I think the guideline here should be “Help and About context menu items are discouraged. A Help button inside the properties dialog is optional (see …)” — Diego Ongaro 2008/01/06 01:12
- [draft] Display a title
If you had like to add a title in your menu, set it insensitive and bold on top of the menu followed by a separator
Settings Dialog
- [rfc] When to store altered settings?
Moved to discussion page.
- [draft] Set sensitivity of panel plugin to false
Plugins that don't may be touched while the properties dialog is open may set the sensitivity of their widgets to false during that time.
Class B: Button
Button with [image label], [image] or [label]
sometimes opening a menu
examples: menu, places, launcher, window list, mount, …
- The widget(s) should be contained in a box, preferably an XfceHVBox for convenience.
- The order of the widget(s), top-to-bottom or left-to-right should be:
- image
- label
- fabian 2007/12/17 19:22 GMT. Regard other languages such as arabic, they will most probably want the opposite order.
- The box should have a default border (1px).
- [draft] The box should have a spacing of 4px.
- [draft] The image should have a size of
size of button - MAX (GtkWidget->style->xthickness, GtkWidget->style->ythickness)
- Use a short label to conserve space
- On the label, use capitalization like a title (e.g., “My Button”)
Class I: Input
Button with [image] [input field]
database queries, command execution, etc from the panel
examples: verve, dict(ionary)
Class M: Monitor
[image] [label] [meter] [value reading]
the resource monitoring ones. Many plugins display a monitor and give the user the option of showing a label, a value reading, or both. For example, the systemload plugin can show labels and monitors for CPU, memory, and swap usage.
examples: system load monitor, battery monitor, sensors plugin
- The widget(s) should be contained in a box, preferably an XfceHVBox for convenience.
- [draft] The order of the widget(s), top-to-bottom or left-to-right should be:
- Icon
- Label
- Monitor
- Value Reading
- fabian 2007/12/17 19:22 GMT. Regard other languages such as arabic, they will most probably want the opposite order.
- kalikiana 2007/12/17 19:50 I'm not convinced that the Value must be at the very right. The Free Space Checker shows nicely how you can save space by joining Name and Value.
- ongardie 2007/12/21 00:55 Yes, that's a nice effect. Would it work for any monitor?
- The box should have a default border (1px).
- [draft] The box should have a spacing of 2px.
- kalikiana 2007/12/17 19:39 Space between labels was discussed before and the argument against it was that you can add space via 'whitespace' characters and separators. Some people are tight on real screen estate. However this is good if we explicitly address the space between different monitors.
- ongardie 2007/12/21 00:58 Using whitespace is an unclean hack. If 2px is too much, maybe it should be only 1px. Screenshots might help.
- Use a short label to conserve space. Abbreviations are acceptable
- [draft] Use all lowercase letters (e.g., “cpu”)
- Mike Massonnet 2007/12/16 07:13 at some point I liked to modify the systemload to show Cpu and Mem instead
- ongardie 2007/12/21 00:59 CPU is an acronym, so “Cpu” would be incorrect, and “CPU” takes too much space. “Mem” just looks bad, IMO.
- I don't like lowercase either. It depends on what the monitor stands for. — Jannis Pohlmann 2007/12/23 13:57
- On the label, omit punctuation in acronyms and abbreviations (e.g., “mem” instead of “mem.”)
- On the value reading, don't include too much precision (e.g., “95.324234%” is bad)
- [draft] On the value reading, include units if they add no more than 3 characters to the string (e.g., “30min”)
- fabian 2007/12/17 19:26 GMT Not possible – “rpm” is “U/min” in German, so depends too much on locale again.
- ongardie 2007/12/21 01:47 So should we just say “keep it short”?
- [rfc] space between monitor bars? (some plugins combine multiple monitors)
- ongardie 2007/12/21 01:49 Probably about double the spacing we decide on inside the monitor.
- [draft] use a -90° angle for monitor labels in horizontal panels and 0° angle for monitor labels in vertical panels. That might save a lot of space. — Jannis Pohlmann 2007/12/23 14:10
- ongardie 2007/12/14 06:17 I entirely agree. To clarify, the bar should be vertical and progress upwards for horizontal panels, and it should be horizontal and progress rightwards for vertical panels.
Class G: Grid
array of buttons with [image] or [label] or [image label]
examples: icon box, task list, system tray
Class O: Other
examples: pager, xfapplet
- [rfc] Border with other plugins (left/right for horiz. panels) should be ???
- [rfc] Border with panel edge (top/bottom for horiz. panels) should be ???