GNOME.org
 

[gnome-devel-docs] Added HIG3 pages ported from wiki, plus template for new patterns

commit 99c39b99d534cb48182f843785d73c688271a772
Author: Phil Bull <philbull gmail com>
Date:   Sun Dec 5 01:03:24 2010 +0000

    Added HIG3 pages ported from wiki, plus template for new patterns

 hig3/figures/editable-list-AddRemoveOnly.png     |  Bin 0 -> 7755 bytes
 hig3/figures/editable-list-AllButtons.png        |  Bin 0 -> 9142 bytes
 hig3/figures/editable-list-Empty.png             |  Bin 0 -> 7521 bytes
 hig3/figures/editable-list-InPlace.png           |  Bin 0 -> 9306 bytes
 hig3/figures/progress-display-fileoperations.png |  Bin 0 -> 22941 bytes
 hig3/figures/zooming-buttons.png                 |  Bin 0 -> 14131 bytes
 hig3/figures/zooming-combo.png                   |  Bin 0 -> 13627 bytes
 hig3/figures/zooming-fixed-point.png             |  Bin 0 -> 11827 bytes
 hig3/figures/zooming-menu.png                    |  Bin 0 -> 22960 bytes
 hig3/figures/zooming-slider.png                  |  Bin 0 -> 23322 bytes
 hig3/index.page                                  |   25 +++
 hig3/pattern-configuration.page                  |  161 +++++++++++++++++++
 hig3/pattern-editable-lists.page                 |  184 ++++++++++++++++++++++
 hig3/pattern-handling-errors.page                |  143 +++++++++++++++++
 hig3/pattern-progress-display.page               |   85 ++++++++++
 hig3/pattern-toolbars.page                       |   84 ++++++++++
 hig3/pattern-zooming.page                        |  173 ++++++++++++++++++++
 hig3/pattern.page.stub                           |   63 ++++++++
 hig3/patterns.page                               |   21 +++
 19 files changed, 939 insertions(+), 0 deletions(-)
---
diff --git a/hig3/figures/editable-list-AddRemoveOnly.png b/hig3/figures/editable-list-AddRemoveOnly.png
new file mode 100644
index 0000000..424c3b9
Binary files /dev/null and b/hig3/figures/editable-list-AddRemoveOnly.png differ
diff --git a/hig3/figures/editable-list-AllButtons.png b/hig3/figures/editable-list-AllButtons.png
new file mode 100644
index 0000000..9745e8a
Binary files /dev/null and b/hig3/figures/editable-list-AllButtons.png differ
diff --git a/hig3/figures/editable-list-Empty.png b/hig3/figures/editable-list-Empty.png
new file mode 100644
index 0000000..aed532b
Binary files /dev/null and b/hig3/figures/editable-list-Empty.png differ
diff --git a/hig3/figures/editable-list-InPlace.png b/hig3/figures/editable-list-InPlace.png
new file mode 100644
index 0000000..8faa3e8
Binary files /dev/null and b/hig3/figures/editable-list-InPlace.png differ
diff --git a/hig3/figures/progress-display-fileoperations.png b/hig3/figures/progress-display-fileoperations.png
new file mode 100644
index 0000000..6ba8e46
Binary files /dev/null and b/hig3/figures/progress-display-fileoperations.png differ
diff --git a/hig3/figures/zooming-buttons.png b/hig3/figures/zooming-buttons.png
new file mode 100644
index 0000000..99036c5
Binary files /dev/null and b/hig3/figures/zooming-buttons.png differ
diff --git a/hig3/figures/zooming-combo.png b/hig3/figures/zooming-combo.png
new file mode 100644
index 0000000..c943286
Binary files /dev/null and b/hig3/figures/zooming-combo.png differ
diff --git a/hig3/figures/zooming-fixed-point.png b/hig3/figures/zooming-fixed-point.png
new file mode 100644
index 0000000..561bd92
Binary files /dev/null and b/hig3/figures/zooming-fixed-point.png differ
diff --git a/hig3/figures/zooming-menu.png b/hig3/figures/zooming-menu.png
new file mode 100644
index 0000000..02c27b1
Binary files /dev/null and b/hig3/figures/zooming-menu.png differ
diff --git a/hig3/figures/zooming-slider.png b/hig3/figures/zooming-slider.png
new file mode 100644
index 0000000..5fa26e3
Binary files /dev/null and b/hig3/figures/zooming-slider.png differ
diff --git a/hig3/index.page b/hig3/index.page
new file mode 100644
index 0000000..69dd324
--- /dev/null
+++ b/hig3/index.page
@@ -0,0 +1,25 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="index">
+
+  <info>
+    <desc>Advice on user interface design and a collection of patterns</desc>
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+  <title>GNOME Human Interface Guidelines</title>
+
+<section id="guidelines">
+ <title>Guidelines</title>
+</section>
+  
+<section id="patterns">
+ <title>Pattern Library</title>
+</section>
+	
+</page>
diff --git a/hig3/pattern-configuration.page b/hig3/pattern-configuration.page
new file mode 100644
index 0000000..3b1c728
--- /dev/null
+++ b/hig3/pattern-configuration.page
@@ -0,0 +1,161 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-configuration">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>Allan Day</name>
+    </credit>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Configuration</title>
+
+<p>Configuration allows users to modify the behaviour and appearance of their software.</p>
+
+<!-- Tags: settings, preferences, customisation, menus, assistants -->
+
+<section>
+ <title>When to Use</title>
+
+ <quote>
+  <p>Using preferences as a band-aid is the root of much UI evil.</p>
+  <cite>Havoc Pennington</cite>
+ </quote>
+ 
+ <p>As far as possible, applications should be designed in order to not require manual configuration. Generally, a well-designed interface does not require configuration and will operate effectively with no modification of preferences for both different use cases and users. That said, configuration options can be presented for a number of different reasons:</p>
+
+ <list>
+  <item>
+  <p>Essential settings, e.g. email account details.</p>
+  <p>Some applications require user configuration in order to operate. This may require configuration options to be presented when an application is first run.</p>
+  </item>
+  <item>
+  <p>Personalisation, e.g. wallpaper.</p>
+  <p>This kind of configuration allows users to develop a personal relationship with their systems and can also be used to make a UI interface fun to use. This kind of configuration should be used extremely sparingly, if at all.</p>
+  </item>
+  <item>
+  <p>To cater for different user groups and varieties of usage.</p>
+  <p>This reason for adding configuration options should be treated with caution - ideally, software should work for virtually all kinds of users without the need for configuration. Nevertheless, this kind of configuration may sometimes be unavoidable.</p>
+  </item>
+ </list>
+</section>
+
+<section>
+ <title>Description</title>
+ <p>Configuration options can be provided via a number of kinds of interface components:</p>
+ <terms>
+  <item>
+   <title>Menu items</title>
+   <p>Menus can contain check boxes and radio buttons for configuration options.</p>
+  </item>
+  <item>
+   <title>Toolbars</title>
+   <p>Configuration options can be provided via toggle buttons and combo boxes in toolbars.</p>
+  </item>
+  <item>
+   <title>Preferences windows</title>
+   <p>...</p>
+  </item>
+  <item>
+   <title>Configuration tools</title>
+   <p>e.g. toolbar editors</p>
+  </item>
+  <item>
+   <title>Assistants</title>
+   <p>See Assistants.</p>
+  </item>
+ </terms>
+</section>
+
+<section>
+ <title>Guidelines</title>
+ <list>
+  <item>
+  <p>Configuration should be done automatically wherever possible.</p>
+  </item>
+  <item>
+  <p>Configuration options should be kept to a minimum: the more options that are added, the more likely it will be for a user to ignore them.</p>
+  </item>
+  <item>
+  <p>It is vital to provide a good set of default options which work for the vast majority of use cases.</p>
+  </item>
+  <item>
+  <p>Preferences should be saved between sessions.</p>
+  </item>
+ </list>
+
+ <section>
+  <title>Preferences Windows</title>
+  <p>It is not always necessary to provide a preference window, and they should be avoided if possible. Only use one when the number of necessary configuration options cannot be contained within other interface elements.</p>
+  <p>Preferences windows should be accessed through the <gui>Preferences</gui> entry in the <gui>Edit</gui> menu, should one be provided.</p>
+  <p>Only configuration options which are infrequently changed should be contained within a preferences window.</p>
+  <p>Options should be grouped into sections and/or tabs in order to make the interface easy to understand. These groups should be organized by topic rather than level of ability or frequency of use. <gui>Advanced</gui>, <gui>Options</gui> and <gui>General</gui> are common group and tab labels which are uninformative and should be avoided.</p>
+  <p>Where possible, the most commonly used options should be displayed towards the top of the window and in the first tab.</p>
+  <p>Avoid nested tabs like the plague.</p>
+ </section>
+ 
+ <section>
+  <title>Instant Apply</title>
+  <p>Update values or settings immediately to reflect the changes made in the window. This is known as <em>instant apply</em>. Do not make the user press an <gui>OK</gui> or <gui>Apply</gui> button to make the changes happen unless either:</p>
+  <list>
+   <item>
+   <p>the change will take more than about one second to apply, in which case applying the change immediately could make the system feel slow or unresponsive, or</p>
+   </item>
+   <item>
+   <p>the changes in the window have to be applied simultaneously to prevent the system entering a potentially unstable state. For example, the hostname and proxy fields in a network properties window.</p>
+   </item>
+  </list>
+  
+  <p>If either of these conditions affect only a few of the controls in your window, arrange those controls together into one or more groups, each with its own <gui>Apply</gui> button. Leave the rest of the controls as instant apply.</p>
+
+  <list>
+   <item>
+   <p>Do not attempt to validate or apply changes caused by editing a text field control until the user has moved focus to a different control in the window, or the window is closed. Validating after each keypress is usually annoying and unnecessary.</p>
+   <p>Exception: if the field accepts only a fixed number of characters, such as a hexadecimal color code, validate and apply the change as soon as that number of characters have been entered.</p>
+   </item>
+   <item>
+   <p>When the user moves focus to a different control, do not indicate an invalid entry by displaying an alert or undoing the change the user made. Both of these methods are particularly disruptive for focus-follows-mouse users, for whom focus may leave the control more often than it does for a click-to-focus user.</p>
+   </item>
+  </list>
+ </section>
+ 
+ <section>
+  <title>Explicit Apply</title>
+
+  <p>If most of the controls in your window are not suitable for instant apply, consider making the whole window <em>explicit apply</em>. An explicit apply window has these three buttons in its button box, plus an optional <gui>Help</gui> button:</p>
+  
+  <terms>
+   <item>
+   <title>Apply</title>
+   <p>Applies all the settings in the window, but does not close the window in case the user wishes to change their mind.</p>
+   </item>
+   <item>
+   <title>Cancel</title>
+   <p>Resets all settings in the window to those that were in force when the window was opened.</p>
+   <p>Note: this must undo the effects of all applications of the <gui>Apply</gui> since the window was opened, not just the most recent one.</p>
+   </item>
+   <item>
+   <title>OK</title>
+   <p>Applies all settings in the window and closes the window.</p>
+   </item>
+  </terms>
+ </section>
+ 
+</section>
+
+<section>
+ <title>Current Usage</title>
+ <p>Evince provides an excellent example of minimal configuration options.</p>
+</section>
+
+</page>
diff --git a/hig3/pattern-editable-lists.page b/hig3/pattern-editable-lists.page
new file mode 100644
index 0000000..589a808
--- /dev/null
+++ b/hig3/pattern-editable-lists.page
@@ -0,0 +1,184 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-editable-lists">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>Calum Benson</name>
+    </credit>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Editable Lists</title>
+
+<p>Allows user to add, remove, edit, and/or re-order items in a single or multi-column list.</p>
+<!-- Tags: list, table, edit, duplicate, reorder -->
+
+<section>
+ <title>Description</title>
+ <figure>
+  <title>List with only <gui>Add</gui> and <gui>Remove</gui> buttons</title>
+  <media type="image" mime="image/png" src="figures/editable-list-AddRemoveOnly.png" />
+ </figure>
+ <figure>
+  <title>List with all six standard buttons</title>
+  <media type="image" mime="image/png" src="figures/editable-list-AllButtons.png" />
+ </figure> 
+ <figure>
+  <title>List with only <gui>Add</gui>, <gui>Remove</gui>, <gui>Duplicate</gui> and <gui>Edit</gui> buttons, shown during in-place edit</title>
+  <media type="image" mime="image/png" src="figures/editable-list-InPlace.png" />
+ </figure>
+
+ <p><gui>Add</gui> and <gui>Remove</gui> buttons allow user to add new rows of information. <gui>Edit</gui> button (optional) allows user to edit selected row, either inline or in a separate frame or window, as appropriate. Duplicate button (optional) duplicates the selected item, giving the new item a unique name. If the list item represents an object with properties, all of that object's properties are also duplicated.</p>
+
+ <p>Up/Down buttons (optional) move selected item up or down in the list.</p>
+
+ <p>Different from GNOME 2.x: Use of icon-only buttons, rather than 'Add', 'Remove', 'Duplicate' and 'Edit...' buttons.</p>
+</section>
+
+<section>
+ <title>When to Use</title>
+
+ <p>Wherever the user is allowed to add to, remove from or edit arbitrary items in a list. The list may have more than one column.</p>
+
+ <p>Do not use if there is not enough vertical space to display at least five(?) rows, or enough horizontal space to display items of typical length without truncation. If space is limited, consider using one of the following patterns instead:</p>
+ <list>
+  <item>
+  <p>Editable Dropdown Menu pattern (TBD)</p>
+  </item>
+  <item>
+  <p>Others?</p>
+  </item>
+ </list>
+ 
+ <p>Do not use where the task is to create one list from another list of available items. Use the Add Remove List pattern (TBD) instead.</p>
+ 
+</section>
+
+<section>
+ <title>Current Usage</title>
+ <p>No current applications are known to use this version of the pattern.</p>
+</section>
+
+<section>
+ <title>User Guide</title>
+ <p>To add a new row to the list, click the <gui>Add</gui> button, or double-click anywhere in any empty row.</p>
+
+ <terms>
+  <item>
+  <title>For lists that allow inline editing</title>
+  <p>When a row is added, an inline input control is shown overlaying the first cell in the first available row. The new row may be populated with default information, or may be initially blank. The inline control will be appropriate to the type of information required, for example a text field, a combo box or a popup menu.</p>
+  <p>After entering or selecting the required information, press <key>Tab</key> or <key>Enter</key> to confirm the edit and move focus to the next editable column or row, or <key>Esc</key> to cancel the edit. If you cancel while you are still adding the first column of a row, that row will be removed again.</p>
+  </item>
+  <item>
+  <title>For lists that require external editing</title>
+  <p>When a row is added, a new window is opened in which to enter the necessary information. Click <gui>OK</gui> in the window to add the new item to the list, or <gui>Cancel</gui> to close the window without adding.</p>
+  <p>(TBD: Controls could also be in the same window, I guess... in which case they could be used to both view and edit the 'properties' of the selected list item. Sounds like a separate pattern though...)</p>
+  </item>
+ </terms>
+
+ <p>To edit an existing cell, click the <gui>Edit</gui> button or double-click the item.</p>
+
+ <p>An entire row can be removed in two ways:</p>
+ <list>
+  <item>
+  <p>Select the row, then click the <gui>Remove</gui> button. A row is selected by clicking any cell in the row, causing the entire row to be highlighted. Multiple row selection is allowed in the usual way (using <key>Ctrl</key> and/or <key>Shift</key>) unless otherwise specified for a particular table. Empty rows cannot be selected.</p>
+  </item>
+  <item>
+  <p>Click the <gui>Remove</gui> button while any cell is being edited. The entire row will be removed.</p>
+  </item>
+ </list>
+
+ <p>The <gui>Remove</gui> button is disabled at all other times.</p>
+
+ <section>
+  <title>Keyboard Navigation</title>
+  <p>When focus is inside the table, use arrow keys to move between rows and columns. Press <key>Space</key> to edit the focused item. Press <key>Tab</key> to move focus to the <key>Add</key> button. Press <keyseq><key>Shift</key><key>Tab</key></keyseq> to move the focus to the list header (if present), or to the previous control in the dialog.</p>
+
+  <p>While editing: Pressing <key>Tab</key>/<key>Enter</key> while editing a cell confirms the edit and moves focus to next column in the row, if any. If there is only column, or focus is on the last column in the row, focus <em>may</em> move to the next row, depending on the application. Otherwise, focus returns to the <gui>Edit</gui> button (or <gui>Add</gui> button if <gui>Edit</gui> button is omitted).</p>
+
+  <p>Pressing <key>Esc</key> cancels any pending changes to the cell and returns focus to the <gui>Edit</gui> button (or <gui>Add</gui> button if <gui>Edit</gui> button is omitted). When adding a row, pressing <key>Esc</key> while still editing the first column of the row will also remove the row.</p>
+
+  <p>(Would be nice to have keyboard shortcuts for up/down, but not sure we have any left--drawback of using icon-only buttons...)</p>
+ </section>
+</section>
+
+<section>
+ <title>Related Guidelines</title>
+ <p>Link to any guidelines in the latest version of the HIG that the developer may need to bear in mind when implementing this pattern. Also link to any guidelines that the pattern deliberately flaunts, if any, and explain why.</p>
+ <p>Handling Errors - for input validation.</p>
+</section>
+
+<section>
+ <title>Specification</title>
+ <p>(Bit of a jumble at the moment... still working on it...)</p>
+ <p>The list is packed into a 2-item <code>VBox</code> above a <code>GtkToolbar</code>. Key properties:</p>
+ <list>
+  <item><p><code>VBox spacing = 0</code></p></item>
+  <item><p><code>Toolbar Style = Icons Only</code></p></item>
+  <item><p><code>Toolbar Show Arrow = False</code></p></item>
+  <item><p><code>Toolbar Icon Size = 1</code></p></item>
+ </list>
+ 
+ <p>Labels for toolbar buttons (not shown, but used for accelerator and screenreader access):</p>
+ <list>
+  <item><p><gui>Add</gui></p></item>
+  <item><p><gui>Remove</gui></p></item>
+  <item><p><gui>Duplicate</gui></p></item>
+  <item><p><gui>Edit</gui></p></item>
+  <item><p><gui>Move Up</gui></p></item>
+  <item><p><gui>Move Down</gui></p></item>
+ </list>
+ 
+ <p>Default tooltips for the toolbar are:</p>
+ <list>
+  <item><p>Add new <var>object type</var></p></item>
+  <item><p>Remove selected <var>object type</var></p></item>
+  <item><p>Duplicate selected <var>object type</var></p></item>
+  <item><p>Edit selected <var>object type</var></p></item>
+  <item><p>Move item up</p></item>
+  <item><p>Move item down</p></item>
+ </list>
+ <p>The <gui>Duplicate</gui>, <gui>Edit</gui>, <gui>Move Up</gui> and <gui>Move Down</gui> buttons are optional. <gui>Move Up</gui> and <gui>Move Down</gui> always appear together, i.e. you can't show the <gui>Move Up</gui> button, but not the <gui>Move Down</gui> button.</p>
+ 
+ <p>The first toolbar separator is shown if the <gui>Duplicate</gui> and <gui>Edit</gui> buttons are present. If only one of those two buttons is present, no separator is required.</p>
+
+ <p>The second toolbar separator is shown if the Move Up and Move Down buttons are present.</p>
+
+ <p>Where possible, allow the user to add and edit list items using inline controls. (a11y concerns?)</p>
+
+ <p>The <gui>Add</gui> button is enabled at all times, except while a row is already being added.</p>
+
+ <p>Table cells whose contents are not fully visible are ellipsised, and given a tooltip that shows the entire cell contents.</p>
+
+ <p>When the list is empty, it is preferable to show some italicized text indicating that this is the case:</p>
+ 
+ <media type="image" mime="image/png" src="figures/editable-list-Empty.png">
+  <p>Showing italicized text when the list is empty.</p>
+ </media>
+
+ <p>Where required, input validation is performed whenever focus leaves a cell that is being edited, either explicitly (e.g. by pressing <key>Enter</key>) or implicitly (e.g. by clicking the dialog's <gui>OK</gui> button whilst editing a cell).</p>
+
+ <p>For guidelines on preventing and automatically correcting validating errors, see Error Handling. If a validation error cannot be corrected automatically, use (TBD: some standard way to show validation errors inline -- InfoBar), and move focus back to the cell that caused the error.</p>
+</section>
+
+<section>
+ <title>Source Code</title>
+ <p>GtkBuilder (.ui) file</p>
+</section>
+
+<section>
+ <title>Terminology</title>
+ <p>Verbs and actions associated with the pattern, to be used by (and possibly provided by) documentation team.</p>
+</section>
+
+</page>
diff --git a/hig3/pattern-handling-errors.page b/hig3/pattern-handling-errors.page
new file mode 100644
index 0000000..28702f2
--- /dev/null
+++ b/hig3/pattern-handling-errors.page
@@ -0,0 +1,143 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-handling-errors">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>Matthew Paul Thomas</name>
+    </credit>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Errors</title>
+
+<quote>
+ <p>Donâ??t ever make the same mistake twice, unless it pays.</p>
+ <cite>Mae West</cite>
+</quote>
+
+<p>Errors show how crude your software is. Smart software accepts human errors, prevents them, allows undo, or - as a last resort - explains them in a way that lets us understand and fix them ourselves. The better your software is at doing these things, the more efficient and satisfied we will be when using it.</p>
+
+<section>
+ <title>Accepting errors</title>
+
+ <p>The best way to handle input errors is, whenever possible, to <em>accept unambiguous input</em>. For example:</p>
+ <list>
+  <item>
+  <p>In a field for a phone number, credit card number, or similar, donâ??t complain about characters like spaces, dashes, or brackets. Instead, just accept these characters, and ignore them internally when using the data.</p>
+  <p>Further reading: Steve Friedl, <link href="http://unixwiz.net/ndos-shame.html";>"No dashes or spaces" hall of shame</link>.</p>
+  </item>
+  <item>
+  <p>In a field for naming something new, where some characters are prohibited, consider automatically replacing them with equivalent allowed characters. For example, if spaces are not allowed when registering a new login name, the field might replace spaces with dashes as they are typed.</p>
+  </item>
+  <item>
+  <p>If compulsory data is missing from a customer record or similar item, consider accepting the record provisionally, but reminding us to complete it later.</p>
+  </item>
+ </list>
+</section>
+
+<section>
+ <title>Preventing errors</title>
+ 
+ <p>The next best way to handle errors is to <em>prevent errors from happening</em>.</p>
+ 
+ <p>If people often trigger a particular command accidentally, make it more difficult to trigger. A confirmation alert is the least polite way of doing this. One example of a better method is changing a keyboard equivalent to require two keys instead of one (or three keys instead of two). Another example is physically separating dangerous commands from more common ones â?? in a menu using separators or submenus, and elsewhere using spacing or an expandable section. [right: something]</p>
+
+ <p>Use the appropriate control for the task, and give it a reasonable default value. For example, if a setting has only a few useful values, consider radio buttons or an option menu instead of a text field. And if asking for a date or time, use a datepicker or timepicker rather than a text field. [wrong: text field used for date, with format caption] [right: datepicker]</p>
+
+ <p>If a button, menu item, or other control canâ??t be used successfully right now, donâ??t show an error when it is invoked. Instead, make the control insensitive. Usually, itâ??s obvious why a control is insensitive. If it isnâ??t:</p>
+ <list>
+  <item>
+  <p>If there is available space, include a caption giving the reason. [right: â??Not connected to the Internet.â?? next to insensitive â??Sign Inâ??]</p>
+  </item>
+  <item>
+  <p>As a last resort, add a temporary tooltip for the control (or extend the existing tooltip for a toolbar button) explaining that it is "Not available because" or "Not available until" something. For example: "Sorts cells alphabetically. Not available until you select some cells."</p>
+  </item>
+  <item>
+   <p>Further reading: Lukas Mathis, <link href="http://ignorethecode.net/blog/2008/07/01/disabling-inactive-menu-items/";>"Disabling inactive menu items"</link>.</p>
+   <note>
+    <p>On other platforms, insensitive menu items sometimes change their wording when insensitive - for example, <gui>Can't Undo Partitioning</gui> or <gui>Nothing to Redo</gui>. Donâ??t do this in Gnome software; it may disorient people who were looking for the original item wording.</p>
+   </note>
+  </item>
+ </list>
+
+<p>If a field has a minimum or maximum length or value, don't let me submit a value with a length outside that range.</p>
+
+<p>Consider including an error caption or similar element next to the field, describing whether the value is too short or too long. (For example, microblogging clients often feature a count showing the number of possible characters left, and this number becomes negative when there are too many characters.)</p>
+
+<p>Don't ignore excess characters as they are typed, because the characters I will want to remove aren't necessarily the last ones I typed. Instead, highlight excess characters with the theme's error color, so that I can see how many I need to remove before submission.</p>
+
+ <p>Before saving or copying files, check that the device is writable and has enough free space.</p>
+
+ <p>Before doing anything requiring an Internet connection, check that there is one.</p>
+
+ <p>If a dialog opened automatically to perform a particular task, close the dialog automatically if the task has since been performed a different way, or otherwise rendered irrelevant.</p>
+
+ <p>Occasionally, your desire to prevent errors may conflict with our efficiency. Donâ??t go overboard.</p>
+
+ <p>Further reading: Janko Jovanovic, <link href="http://www.jankoatwarpspeed.com/post/2010/05/10/Poka-Yoke-in-UI-design.aspx";>"Poka-Yoke in UI design"</link></p>
+
+ <p>Heuristic tagging: Use the <code>ux-error-prevention</code> tag in bug reports about preventable errors.</p>
+</section>
+
+<section>
+ <title>Allowing undo</title>
+</section>
+
+<section>
+ <title>Presenting errors</title>
+
+ <p>If you cannot correct or prevent an error, you will need to explain it. Make clear, near to the error in space in time, what went wrong, why it went wrong, and what we should do next.</p>
+
+ <section>
+  <title>Near in space and time</title>
+  
+  <p>Describe an error as close as possible to the place where it occurred, and as soon as possible after it occurred, without being distracting.</p>
+  
+  <p>If one item in a list has a non-urgent error condition, show an error icon at the trailing end of that item, where activating the icon displays more information and troubleshooting options.</p>
+  
+  <p>Similarly, if one field in a form is incorrect once it loses focus, highlight that field with the error background color, and describe the error next to the field. (Occasionally, it may be helpful to do the opposite, using a success icon to confirm valid values for difficult fields.) Further reading: Luke Wroblewski, <link href="http://www.alistapart.com/articles/inline-validation-in-web-forms/";>"Inline validation in Web forms"</link></p>
+  
+  <p>If you cannot know which of a dialogâ??s fields are incorrect - for example, in a login dialog where the login name and/or the password are incorrect - consider keeping the dialog open, but changing its primary text to describe the error.</p>
+  
+  <p>As a last resort, use a separate error alert.</p>
+ </section>
+ 
+ <section>
+  <title>What went wrong</title>
+  
+  <p>If the error is in the software or hardware itself, be apologetic, because you have let us down. Even if the error is in the hardware, say sorry - though it's not your fault - because many of us do not distinguish between software and hardware.</p>
+  
+ </section>
+
+ <section>
+  <title>Why it went wrong</title>
+ </section>
+
+ <section>
+  <title>What we should do next</title>
+  <terms>
+   <item>
+    <title>Bad example</title>
+    <p><gui>Print error: Out of paper. (( OK ))</gui></p>
+   </item>
+   <item>
+    <title>Good example</title>
+    <p><gui>The printer "Printasonic 4850" is out of paper. Only 4 of 7 pages in "Gaming roster" have printed. ( Stop ) (( Resume ))</gui></p>
+   </item>
+  </terms>
+ <p>Further reading: David Travis, <link href="">"Communicating errors"</link></p>
+ </section>
+ 
+</section>
+
+</page>
diff --git a/hig3/pattern-progress-display.page b/hig3/pattern-progress-display.page
new file mode 100644
index 0000000..51693d3
--- /dev/null
+++ b/hig3/pattern-progress-display.page
@@ -0,0 +1,85 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-progress-display">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>Kirk Bridger</name>
+    </credit>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Progress Display</title>
+
+<p>The user should always be able to ascertain the state of the computer they are working with, to the extent that they are able to determine if it is currently working to accomplish a task the user specified for it, or it is frozen and unresponsive, for example. This information can be displayed to the user in a number of ways, including progress bars, spinners/throbbers, text and label updates for example.</p>
+<!-- Tags: progress, feedback, operations -->
+
+<section>
+ <title>Description</title>
+ <p>Typically a user will begin to wonder if a machine is still responsive after about 3 seconds of no visible action. It is important to provide some kind of feedback to the user within this timeframe. For operations that will take longer than 7 seconds it may be desirable to provide additional information to the user about the operations underway. Anything under 7 seconds and the user won't be able to read and understand the extra information, so it should not be displayed.</p>
+</section>
+
+<section>
+ <title>Progress Dialogs</title>
+
+ <p>Progress Dialogs as a term encompasses the various graphical bars that can be displayed onscreen to indicate the progress of an operation. The progress bar begins at 0% complete (empty) and moves to the right, filling up, until it reaches 100% complete. The extent of the filling of the bar reflects the degree of completeness of the operation. If there are multiple operations that are underway and each needs to be separately represented then a single window can be displayed with the various progress bars contained within it.</p>
+
+ <p>Typically a progress bar will also provide some rudimentary controls, provided the underlying operation supports the controls. For example if the operation can be cancelled then a cancel operation should be displayed for the user. If the operation cannot be cancelled then the user should not be given the option to try to cancel it. Other operations include pause.</p>
+
+ <p>Something about the text included on the bar, as well as info in addition to the bar.</p>
+
+ <media type="image" mime="image/png" src="figures/progress-display-fileoperations.png">
+  <p>A file operation progress dialog</p>
+ </media>
+
+ <section>
+  <title>When to Use</title>
+ </section>
+
+ <section>
+  <title>Current Usage</title>
+ </section> 
+</section>
+
+<section>
+ <title>Spinners/Throbbers</title>
+
+ <p>These progress displays are shown to the user when there is very little information to give the user other than that things are progressing and being worked on. They do not provide any means for the user to interact with them directly.</p>
+
+ <section>
+  <title>When to Use</title>
+ </section>
+ 
+ <section>
+  <title>Current Usage</title>
+
+  <p>Gnome changes the mouse cursor to a spinning circle to indicate that work is occurring in the background.</p>
+  <p>Mozilla Firefox and nautilus used to have throbbers - don't think they do now.</p>
+  <p>Some webpages use spinners to indicate working in the background.</p>
+ </section>
+</section>
+
+<section>
+ <title>Label and Textual Updates</title>
+
+ <p>Some applications provide updates to displayed text as an indicator to progress, typically through some numerical value such as percentage complete. There is no other graphical display like a progress bar.</p>
+
+ <section>
+  <title>When to Use</title>
+ </section>
+ 
+ <section>
+  <title>Current Usage</title>
+ </section>
+</section>
+
+</page>
diff --git a/hig3/pattern-toolbars.page b/hig3/pattern-toolbars.page
new file mode 100644
index 0000000..7ecd735
--- /dev/null
+++ b/hig3/pattern-toolbars.page
@@ -0,0 +1,84 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-toolbars">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-05" status="stub"/>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Toolbars</title>
+
+<p>A strip of graphical interface components that allows convenient access to commonly-used functions. Toolbars typically contain the principle actions provided by an application's graphical interface.</p>
+<!-- Tags: toolbar, buttons, controls -->
+
+<section>
+ <title>When to Use</title>
+
+ <p>Toolbars can be used when there are a limited number of commonly-used operations associated with your application, or to advertise the presence of functionality that is either important or might not be anticipated by users. A toolbar is not always necessary however, and should be considered within the overall design of your interface. gcalctool is a good example of an interface which does not use a toolbar.</p>
+</section>
+
+<section>
+ <title>Description</title>
+ 
+ <!-- FIXME -->
+ <media type="image" mime="image/png" src="figures/toolbars-evince.png">
+  <p>Evince Toolbar Screenshot</p>
+ </media>
+ <media type="image" mime="image/png" src="figures/toolbars-epiphany.png">
+  <p>Epiphany Toolbar Screenshot</p>
+ </media>
+ 
+ <p>Most toolbars only contain buttons, but in more complex applications other types of controls, such as dropdown lists, can also be useful.</p>
+ 
+ <p>Toolbars should only contain the most important or commonly-used functions. Having too many toolbar controls reduces their efficiency by making them harder to find, and too many rows of toolbars reduces the amount of screen space available to the rest of the application. Avoid populating toolbars with many items.</p>
+ 
+ <p>Avoid using multiple toolbars at all costs, since vertical screen space is more valuable than horizontal.</p>
+ 
+ <p>When possible, the contents of toolbars should be consistent with existing GNOME applications. Common toolbar items include <gui>New</gui>, <gui>Open</gui>, <gui>Save</gui>, <gui>Back</gui>, <gui>Forward</gui> and <gui>Stop</gui>/<gui>Reload</gui>. Don't add buttons for <gui>Help</gui>, <gui>Close</gui> or <gui>Quit</gui>, as these are rarely used and the space is better used for more useful controls. Similarly, only provide buttons for <gui>Undo</gui>, <gui>Redo</gui> and the standard clipboard functions if there is space on the toolbar to do so without sacrificing more useful, application-specific controls. The first priority in deciding the General principles regarding layout and alignment should be followed in arranging the contents of toolbars.</p>
+ 
+ <p>Grouping the contents of a toolbar makes them easier to understand. Separate groups of toolbar items with spacing rather than separators, since this creates a cleaner interface. Groups can be separated using additional padding or different justification (with some controls on the left and some on the right, for example).</p>
+</section>
+
+<section>
+ <title>Placement</title>
+
+<!-- FIXME -->
+ <media type="image" mime="image/png" src="figures/toolbars-totem.png">
+  <p>Totem Toolbar Screenshot</p>
+ </media>
+ 
+ <p>Toolbars are typically placed directly below the main menu bar. This is not always appropriate, however. Since interfaces tend to be "read" from top to bottom, applications which prioritise content over functionality (such as video and music players) should place their toolbars below the content that is being displayed, typically along the bottom of the window.</p>
+ <p>Toolbars should almost always be horizontally aligned. The eye does not scan vertically as well as it does horizontally, groups of mutually exclusive buttons are less obvious when arranged vertically, and showing button labels is more awkard and less space-efficient. Also, some toolbar controls just cannot be used vertically, such as dropdown lists.</p>
+ <p>Only consider using a vertical toolbar if the size of the application window means there would be a lot of wasted space if a horizontal toolbar was used instead, or your application would otherwise require three or more rows of toolbars to appear below the main menu bar by default. Note however that in this situation, the better alternative is usually to display fewer toolbars by default.</p>
+</section>
+
+<section>
+ <title>Configurability</title>
+
+ <p>The display of main toolbars should not be configurable, since this creates an unnecessary configuration option and introduces the requirement to reproduce the operations available via the toolbar elsewhere in the interface.</p>
+ 
+ <p>In some cases, optional toolbars are useful as a means of allowing users to modify which functionality is quickly accessible. Options to control the display of optional toolbars should be available in a View menu or preferences window. Note that the the limitations relating to configuration applies to the use of optional toolbars.</p>
+</section>
+
+<section>
+ <title>Current Usage</title>
+
+ <p>Most GNOME applications: Nautilus, Gedit, Evince, EoG, Totem, etc.</p>
+</section>
+
+<section>
+ <title>Specification</title>
+
+ <p>Toolbar buttons are displayed as icons only by default. The most important or potentially unclear menu entries should be set in order to provide a text label as well as an icon.</p>
+</section>
+
+</page>
diff --git a/hig3/pattern-zooming.page b/hig3/pattern-zooming.page
new file mode 100644
index 0000000..a38fe0e
--- /dev/null
+++ b/hig3/pattern-zooming.page
@@ -0,0 +1,173 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="pattern-zooming">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>Federico Mena-Quitero</name>
+    </credit>
+    <credit type="author">
+      <name>Calum Benson</name>
+    </credit>
+    <credit type="author">
+      <name>Allan Day</name>
+    </credit>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Zooming</title>
+
+<p>Zooming allows the size and number of items being displayed to be adjusted.</p>
+
+<!-- Tags: zoom, scale, image, slider, combobox -->
+
+<section>
+ <title>When to Use</title>
+
+ <p>Zooming can be used to enlarge images and documents to aid viewing or to increase the number of pages displayed when viewing a multi-page document. It can also be used in order to change the number of items displayed in a viewing area.</p>
+</section>
+
+<section>
+ <title>Description</title>
+
+ <p>Zoom controls can consist of menu items and/or graphical controls. They typically consist of actions to increase and decrease the zoom level as well as a number of automatically adjusted zoom levels, such as <gui>Best Fit</gui> or <gui>Fit Page Width</gui>. Zoom menu items should be placed in the <gui>View</gui> menu.</p>
+</section>
+
+<section>
+ <title>Guidelines</title>
+ 
+ <p>The number and variety of automatic zoom levels should be selected according to the kind of content being displayed. <gui>Fit Page Width</gui> and <gui>Fit Page Height</gui> may be more appropriate for a document viewer than <gui>Best Fit</gui>, for example.</p>
+ 
+ <p>Automatic zoom level controls should indicate whether they are active or not: <gui>Best Fit</gui> buttons should toggle and their menu items should be check boxes.</p>
+ 
+ <p>Zoom in and zoom out buttons and menu items should become insensitive when the limit of a zoom range has been reached.</p>
+ 
+ <p>Graphical zoom controls:</p>
+ <list>
+  <item>
+  <p>should only be used if modifying the zoom level is a common operation for your application</p>
+  </item>
+  <item>
+  <p>can be placed either in the toolbar or status bar, but should be located close to or in alignment with the content display area</p>
+  </item>
+  <item>
+  <p>can consist of buttons or a slider. Buttons should have a zoom in and zoom out button, with the zoom out button placed on the left. A combobox or best fit toggle buttons can be placed in between (see below).</p>
+  </item>
+ </list>
+
+ <media type="image" mime="image/png" src="figures/zooming-buttons.png">
+  <p>Choosing zoom levels with <gui>Zoom In</gui> and <gui>Zoom Out</gui> buttons</p>
+ </media>
+ 
+ <p>This arrangement is excellent for a wide range of scenarios and is appropriate appropriate for cases where there is no maximum or minimum zoom level.</p>
+
+ <media type="image" mime="image/png" src="figures/zooming-slider.png">
+  <p>Choosing zoom levels using a slider</p>
+ </media>
+
+ <p>Sliders can enable finer grained control of the zoom level, though they need to be carefully implemented (see <link xref="#specification" />). This kind of control is appropriate for cases where the zoom level has predefined maximum and minimum levels.</p>
+
+ <media type="image" mime="image/png" src="figures/zooming-combo.png">
+  <p>Choosing zoom levels using a combo box</p>
+ </media>
+
+ <p>Displaying the zoom level as a percentage is appropriate for professional image editing software, but is otherwise not recommended.</p>
+
+ <media type="image" mime="image/png" src="figures/zooming-menu.png">
+  <p>Using menu items to change the zoom level</p>
+ </media>
+
+ <p>Zoom menu entries should be placed within the <gui>View</gui> menu.</p>
+</section>
+
+<section>
+ <title>Current Usage</title>
+ <p>Nautilus, EOG, F-spot, Evince.</p>
+</section>
+
+<section>
+ <title>User Guide</title>
+
+ <p>To zoom in or out of the image using the toolbar, do one of the following:</p>
+ <list>
+  <item>
+  <p>Click the <gui>plus</gui> button once to zoom in one step, or click the <gui>minus</gui> button once to zoom out one step.</p>
+  </item>
+  <item>
+  <p>Type a percentage into the text field, and press <key>Return</key>. For example, type <input>100%</input> to see the image actual size, or <input>50%</input> for half size.</p>
+  </item>
+  <item>
+  <p>Click the drop-down button beside the text field, and select a pre-defined zoom value from the drop-down list that appears.</p>
+  </item>
+  <item>
+  <p>To zoom in or out of the image using the mouse, move the mouse pointer to the area of the image on which you wish to zoom. Then: move the scrollwheel upwards to zoom in; or rotate the scrollwheel downwards to zoom out.</p>
+  </item>
+ </list>
+ 
+ <section>
+  <title>Keyboard Navigation</title>
+  <p>To zoom in or out of the image using the keyboard, do one of the following:</p>
+  <list>
+   <item>
+   <p>Press <keyseq><key>Ctrl</key><key>Equals</key></keyseq> once to zoom in one step, or press <keyseq><key>Ctrl</key><key>Minus</key></keyseq> once to zoom out one step.</p>
+   </item>
+   <item>
+   <p>Press <keyseq><key>Ctrl</key><key>0</key></keyseq> to set the zoom level to 100%.</p>
+   </item>
+   <item>
+   <p>Press <keyseq><key>Shift</key><key>Ctrl</key><key>0</key></keyseq> to adjust the zoom level so that the entire image is visible in the window.</p>
+   </item>
+  </list>
+ </section>
+</section>
+  
+
+<section>
+ <title>Toolbars</title>
+</section>
+
+<section id="specification">
+ <title>Specification</title>
+ <p>Set a useful default zoom level, such as <gui>Best Fit</gui>.</p>
+
+ <section>
+  <title>Zoom Factor</title>
+  <p>Do not use a fixed set of available zoom factors, since this causes the zoom level to "jump" in a dramatic and uneven fashion.</p>
+
+  <p>Instead, change the zoom level gradually by multiplying or dividing the current zoom level by a constant factor. For example, if you start at 1.0x and make the constant factor be 1.05, then your successive zoom levels would be:</p>  
+  <list style="compact">
+   <item><p>1.05^1</p></item>
+   <item><p>1.05^2</p></item>
+   <item><p>1.05^3</p></item>
+   <item><p>1.05^4</p></item>
+   <item><p>etc.</p></item>
+  </list>
+
+  <p>Choosing the correct factor is a matter of experimentation. Eye of Gnome uses a factor of 1.05, which is comfortable when a mouse's scrollwheel is used to zoom up and down. This factor should be chosen so that the change between successive levels is not too big nor too small. The following example shows successive zoom levels, each with 1.2x multiplication. Note how each level appears to "zoom in the same amount", instead of some steps seeming bigger than others.</p>
+ </section>
+
+ <section>
+  <title>Point of Transformation</title>
+  <p>When zooming with the mouse, make sure the fixed point of the transformation is at the mouse cursor, so the user can retain his point of focus on the zoomed image.</p>
+  <media type="image" mime="image/png" src="figures/zooming-fixed-point.png">
+   <p>The fixed point of the zoom transformation should be at the same point as the mouse cursor</p>
+  </media>
+ </section>
+ 
+</section>
+
+<section>
+ <title>Source Code</title>
+ <p>Sample implementation in Eye of Gnome's <link href="http://git.gnome.org/browse/eog/tree/src/eog-scroll-view.c#n208";><code>eog/src/eog-scroll-view.c:compute_center_zoom_offsets()</code></link>.</p>
+</section>
+
+</page>
diff --git a/hig3/pattern.page.stub b/hig3/pattern.page.stub
new file mode 100644
index 0000000..ee4fe12
--- /dev/null
+++ b/hig3/pattern.page.stub
@@ -0,0 +1,63 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="topic"
+      id="XXXXX">
+
+  <info>
+    
+    <link type="guide" xref="patterns"/>
+    <desc>XXXXX</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-05" status="stub"/>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>XXXXX</title>
+
+<p>Brief overview of what the pattern is for.</p>
+
+<section id="description">
+ <title>Description</title>
+ 
+ <p>Description of the pattern.</p>
+ 
+ <media type="image" mime="image/png" src="figures/figure.png">
+  <p>Image caption</p>
+ </media>
+ 
+</section>
+
+<section id="when">
+ <title>When to use</title>
+ <p>Situations in which the pattern should be used.</p>
+</section>
+
+<section id="current">
+ <title>Current usage</title>
+ <p>Places where this pattern is currently used.</p>
+</section>
+
+<section id="userguide">
+ <title>User guide</title>
+ <p>How a user should use the pattern in question; what they can do with the user interface that the pattern presents.</p>
+</section>
+
+<section id="spec">
+ <title>Specification</title>
+ <p>The detailed layout of the widgets which make up the pattern. May be provided as a UI definition file, or may be given explicity.</p>
+</section>
+
+<section id="related">
+ <title>Related Guidelines</title>
+ <p>A list of HIG guidelines which are related to the current pattern.</p>
+</section>
+
+<section id="terms">
+ <title>Terminology</title>
+ <p>Verbs and actions that are associated with the pattern, for use by the docs team.</p>
+</section>
+
+</page>
diff --git a/hig3/patterns.page b/hig3/patterns.page
new file mode 100644
index 0000000..445c7a4
--- /dev/null
+++ b/hig3/patterns.page
@@ -0,0 +1,21 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      type="guide"
+      id="patterns">
+
+  <info>
+    <link type="guide" xref="index"/>
+    <desc>A library of user interface patterns</desc>
+    
+    <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+    <credit type="author">
+      <name>GNOME Documentation Project</name>
+      <email>gnome-doc-list gnome org</email>
+    </credit>
+    
+  </info>
+
+<title>Pattern Library</title>
+
+
+
+</page>
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]