====== Human Interface Guidelines for Panel Plugins ======

This page is very much a work-in-progress at the moment. Feel free to contribute. [[panel-hig:discussion|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/21 01:51 I think I like 2 spaces the best, personally. //
    * With GTK+2.12 you can add widgets in a tooltip, and therefore labels with markups, for bold for example.  --- //[[mmassonnet@gmail.com|Mike Massonnet]] 2008/01/06 07:39//
    * Or maybe a \t with a configurable (plus sensible default) tab width? -- //anonymous//


Possibly 4 spaces:
{{http://mitglied.lycos.de/timshome/download/xfce4/mailwatch_tooltip.png}}

No spaces:
{{http://mitglied.lycos.de/timshome/download/xfce4/netload-tooltip.png}}

2 spaces:
{{http://mitglied.lycos.de/timshome/download/xfce4/sensors-tooltip.png}}








==== Context Menu ====
Interface guidelines regarding the right-click menu provided by the panel.

  * [rfc] Help?
    * //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. //
    * [snip] The plugins are simple to use, usually the help is helpless.  We do keep stuff on the goodies website like summary, documenation, latest version, …  --- //[[mmassonnet@gmail.com|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.  --- //[[mmassonnet@gmail.com|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.  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/01/06 01:11//
    *  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 context menu items are discouraged. A Help button inside the properties dialog is optional (see ...)" --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/01/06 01:12//

  * [rfc] 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. //
    * The three plugins fabian pointed out [...] show an About item in their context menu. Each of those about dialogs is rather poor, IMHO. I think the guideline should be "About menu items are discouraged." --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/01/06 01:12//

==== Menus ====
Interface guidelines regarding plugins' menus, usually opened by left-clicking on a button or running a command.

  * [draft] Optionally, display a title \\ If you would like to add a title to your menu, set it insensitive and bold, and place it on top of the menu followed by a separator \\ {{http://img265.imageshack.us/img265/2880/menutitlepj6.png}}
    * I'm not convinced I like this. Perhaps we should discourage menu titles instead. --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/01/06 01:28//






==== Settings Dialog ====
Interface guidelines regarding preferences/properties/setting dialogs.

  * [rfc] When to store (save) altered settings? \\ Moved to [[panel-hig:discussion#when_to_store_altered_settings|discussion page]].

  * [draft] It is highly encouraged for settings modifications to take effect immediately. If this is not at all possible, it should be made clear to the user that settings modifications will take effect when the properties dialog is closed.
    * The sensitive part can be dropped, it just works if the dialog is set modal (see [[http://library.gnome.org/devel/gtk/2.12/GtkDialog.html#GtkDialogFlags|GtkDialogs flags]]).  Btw, I prefer when the modifications are affected immediately, that's the default habit in most xfce settings dialogs. --- mike 2008/01/10 05:58
      * "and the plugin's widgets should be set insensitive while the dialog is open" dropped  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:40//
    * Indeed in Xfce it is very common to apply changes immediately unless you are making more complex changes. Please avoid insensitivity or modality where possible. --- kalikiana 2008/01/26 17:06
      * Reworded draft to emphasize this point.  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:40//
    * I think this one's pretty solid now. Let's allow until 2008/03/16 (two weeks) for further debate. If there are no more negative comments, the "[draft]" tag should be removed at that time.  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:44//







===== Class B: Button =====
<file>Button with [image label], [image] or [label]</file>

sometimes opening a menu

examples: menu, places, launcher, window list, mount, ...

{{http://img112.imageshack.us/img112/384/2007121719272681x40scrojv0.png}}

  * 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.
    * Plugins known to implement this:
      * xfdesktop (4.4.2 and trunk)
      * places (1.0 and trunk)
    * I don't think the box should have a border/spacing, but use as much space as possible.  The only space would be the space between the childs, and 2 pixels may be a good default.   --- //[[mmassonnet@gmail.com|Mike Massonnet]] 2008/01/19 18:55//
      * Are there any plugins that do that now?  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:47//

  * [draft] The image inside the button should be set to the same size as the button (usually the size of the panel) without its padding and border size: \\ <code>  GtkIconTheme *icon_theme;
  GdkPixbuf *pixbuf;

  size = xfce_panel_plugin_get_size (panel_plugin);
  size -= 2 + 2 * MAX (panel_plugin->button->style->xthickness, panel_plugin->button->style->ythickness);

  icon_theme = gtk_icon_theme_get_default ();
  pixbuf = gtk_icon_theme_load_icon (icon_theme, "icon-name", size, 0, NULL);
  if (G_UNLIKELY (NULL == pixbuf))
    return;
  gtk_image_set_from_pixbuf (GTK_IMAGE (panel_plugin->icon), pixbuf);
  g_object_unref (G_OBJECT (pixbuf));
</code>
    * Note: this is more a problem of what to do with the size-changed signal  --- //[[mmassonnet@gmail.com|Mike Massonnet]] 2008/01/19 18:48//
    * Should we really have code snippets in here? And I seem to remember someone (maybe Brian) telling you a better way than hard-coding the 2...  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:47//

  * Use a short label to conserve space
  * On the label, use capitalization like a title (e.g., "My Button")



===== Class I: Input =====
<file>Button with [image] [input field]</file>

database queries, command execution, etc from the panel

examples: verve, dict(ionary)












===== Class M: Monitor =====
<file>[image] [label] [meter] [value reading]</file>

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.

{{http://img406.imageshack.us/img406/3128/2007121719262351x40scrodb7.png}}


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.//
      * {{http://img406.imageshack.us/img406/8415/20071217194919102x40scrkk4.png}}
      * //ongardie 2007/12/21 00:55 Yes, that's a nice effect. Would it work for any monitor? //
  * [draft] 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")
    * //[[mmassonnet@gmail.com|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@xfce.org|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@xfce.org|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. //
    * Do the major plugins work this way now?  --- //[[ongardie@gmail.com|Diego Ongaro]] 2008/03/03 04:51//

===== Class G: Grid =====
<file>array of buttons with [image] or [label] or [image label]</file>

examples: icon box, task list, system tray

{{http://img112.imageshack.us/img112/9873/2007121719312292x31scroar1.png}}

===== 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 ???