[gnome-devel-docs] refine patterns pages
- From: Allan Day <allanday src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [gnome-devel-docs] refine patterns pages
- Date: Tue, 12 Aug 2014 18:37:53 +0000 (UTC)
commit 2c8ecdbecd1054d19c155dc6c35224b8a24a42e1
Author: Allan Day <allanpday gmail com>
Date: Tue Aug 12 19:37:20 2014 +0100
refine patterns pages
hig3/C/application-menus.page | 19 +++++++++++++------
hig3/C/dialogs.page | 37 +++++++++++++++++++++++++------------
hig3/C/header-bar-menus.page | 25 ++++++++++++++++++-------
hig3/C/header-bars.page | 24 ++++++++++++++----------
hig3/C/menu-bars.page | 21 +++++++++++++++++++++
hig3/C/search.page | 26 ++++++++++++++++++--------
hig3/C/selection-mode.page | 39 +++++++++++++++++++++++++++------------
hig3/C/view-switchers.page | 33 +++++++++++++++++++++++----------
8 files changed, 159 insertions(+), 65 deletions(-)
---
diff --git a/hig3/C/application-menus.page b/hig3/C/application-menus.page
index 4653ce3..0c75848 100644
--- a/hig3/C/application-menus.page
+++ b/hig3/C/application-menus.page
@@ -21,17 +21,24 @@
<p>Application menus provide access to global, top level actions and options for your application. These
include standard items for accessing documentation and information about the application.</p>
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>Application menus are a standard part of GNOME 3, and every application that runs under GNOME 3 should
have one.</p>
+
+</section>
+
<section id="menu-items">
-<title>Menu Items</title>
+<title>Menu items</title>
<p>Only include menu items that relate to the application as a whole, such as application preferences.
Actions that are specific to a particular window or view, or which act on content within an application
window, should not be included.</p>
<p>Common application menu items include New Window, Preferences, Help, About and Quit.</p>
<list>
-<item><p>If your application has user help, you should include a Help item.</p></item>
-<item><p>Every application menu should include About and Quit.</p></item>
-<item><p>If there are items other than Help, About and Quit, separate them into their own group at the
bottom of the menu.</p></item>
+<item><p>If your application has user help, you should include a <gui>Help</gui> item.</p></item>
+<item><p>Every application menu should include <gui>About</gui> and <gui>Quit</gui>.</p></item>
+<item><p>If there are items other than <gui>Help</gui>, <gui>About</gui> and <gui>Quit</gui>, separate them
into their own group at the bottom of the menu.</p></item>
</list>
</section>
@@ -40,8 +47,8 @@
<title>Additional Guidance</title>
<list>
-<item><p>Follow the standard design guidance for menus.</p></item>
-<item><p>If an item from the application menu is frequently used, consider moving (or duplicating) it to a
more accessible location.</p></item>
+<item><p>Follow the standard <link xref="menus">design guidance for menus</link>.</p></item>
+<item><p>If an item from the application menu is frequently used, consider moving it to a more accessible
location.</p></item>
</list>
</section>
diff --git a/hig3/C/dialogs.page b/hig3/C/dialogs.page
index f765f71..137f21d 100644
--- a/hig3/C/dialogs.page
+++ b/hig3/C/dialogs.page
@@ -16,31 +16,44 @@
<p>Dialogs are secondary windows that appear over a primary, parent window. They are used to present
additional information or controls, including preferences, properties, or to present messages or
questions.</p>
-<p>Dialogs are a commonly recognized design pattern, and there are established conventions for the different
types of dialogs that you might want to use.</p>
+<p>GNOME 3 provides a number of stock dialogs that you can be used, such as for printing or color
selection.</p>
+
+<p>There are three basic types of dialog in GNOME 3.</p>
+
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>Dialogs are a commonly recognized design pattern, and there are established conventions for the different
types of dialogs that you might want to use. The guidelines on each type of dialog provides further
information on this.</p>
<p>While dialogs can be an effective way to disclose additional controls or information, they can also be a
source of interruption for the user. For this reason, always question whether a dialog is necessary, and work
to avoid the situations in which they are required.</p>
-<p>GNOME 3 provides a number of stock dialogs that you can be used, such as for printing or color
selection.</p>
+<p>There are many ways to avoid using dialogs. Examples include:</p>
-<p>There are three basic types of dialog in GNOME 3.</p>
+<list>
+<item><p>Inline composition for new messages, records or contacts.</p></item>
+<item><p>In-application notifications are an alternative to message dialogs.</p></item>
+<item><p><link xref="popovers">Popovers</link> can be a way to display additional controls or options in a
less disruptive manner.</p></item>
+</list>
+
+</section>
<section id="message-dialogs">
<title>Message Dialogs</title>
<media type="image" mime="image/png" src="figures/message-dialog.png"/>
-<p>Message dialogs are the simplest type of dialog. They present a message or question, along with 1-3
buttons with which to respond. They are always modal, meaning that they prevent access to their parent
window. They are an appropriate choice when it is essential that the user sees and responds to a message.</p>
+<p>Message dialogs are the simplest type of dialog. They present a message or question, along with 1-3
buttons with which to respond. They are always modal, meaning that they prevent access to their parent
window. Message dialogs are an appropriate choice when it is essential that the user sees and responds to a
message.</p>
<section id="message-dialog-examples">
<title>Examples</title>
<p>Confirmation dialogs use a message dialog to check - or confirm - that the user wants to carry out an
action. They have two buttons: one to confirm that the action should be carried out and one to cancel the
action.</p>
-<note><p>Confirmation dialogs will often be accidentally or automatically acknowledged, and will not always
prevent mistakes from happening. It is often better to provide undo functionality instead.</p></note>
+<note style="tip"><p>Confirmation dialogs will often be accidentally or automatically acknowledged, and will
not always prevent mistakes from happening. It is often better to provide undo functionality
instead.</p></note>
-<p>Error dialogs simply present an error message to the user. They often include a single button that allows
the user to acknowledge and close the dialog.</p>
+<p>Error dialogs present an error message to the user. They often include a single button that allows the
user to acknowledge and close the dialog.</p>
-<note><p>Error dialogs should generally be a last resort. You should design your application so that errors
do not occur, and to automatically recover if something does go wrong.</p></note>
+<note style="tip"><p>Error dialogs should generally be a last resort. You should design your application so
that errors do not occur, and to automatically recover if something does go wrong.</p></note>
</section>
</section>
@@ -72,9 +85,9 @@
<section id="presentation-dialog-examples">
<title>Examples</title>
-<p>Preferences and Properties are both examples of presentation dialogs, and both present information and
settings in relation to a specific entity (either an application or a content item). Properties dialogs are a
good example of how dialogs can be used to disclose additional information which is not always needed in the
main application window.</p>
+<p>Preferences and properties are both examples of presentation dialogs, and both present information and
settings in relation to a specific entity (either an application or a content item). Properties dialogs are a
good example of how dialogs can be used to disclose additional information which is not always needed in the
main application window.</p>
-<note><p>Resist the temptation to provide a preference window for your application. Always question whether
additional settings are really necessary. Most people will not bother to investigate the preferences that you
provide, and configuration options will contribute to the complexity of your application. Make an effort to
ensure that your application design works for everybody without the need to change its settings.</p></note>
+<note style="tip"><p>Resist the temptation to provide a preference window for your application. Always
question whether additional settings are really necessary. Most people will not bother to investigate the
preferences that you provide, and configuration options will contribute to the complexity of your
application. Make an effort to ensure that your application design works for everybody without the need to
change its settings.</p></note>
</section>
@@ -96,10 +109,10 @@
<list>
<item><p>Dialog windows should never pop up unexpectedly, and should only ever be displayed in immediate
response to a deliberate user action.</p></item>
<item><p>Dialogs should always have a parent window.</p></item>
-<item><p>Follow the layout guidelines when designing the content of windows.</p></item>
-<item><p>You can use view switchers in dialogs to break up controls and information.</p></item>
+<item><p>Follow the <link xref="visual-layout">layout guidelines</link> when designing the content of
windows.</p></item>
+<item><p>Use <link xref="view-switchers">view switchers</link> or <link xref="tabs">tabs</link> to break up
controls and information.</p></item>
<item><p>Avoid stacking dialog windows on top of one another. Only one dialog window should be displayed at
a time.</p></item>
-<item><p>When an affirmative button is included, label it with its actual action. Print is a better label
thanOK or Done, for example.</p></item>
+<item><p>When an affirmative button is included, label it with its actual action. <gui>Print</gui> is a
better label than <gui>OK</gui> or <gui>Done</gui>, for example.</p></item>
<item><p>When opening a dialog, provide initial keyboard focus to the component that you expect users to
operate first.</p></item>
</list>
diff --git a/hig3/C/header-bar-menus.page b/hig3/C/header-bar-menus.page
index ce05e50..8b3c208 100644
--- a/hig3/C/header-bar-menus.page
+++ b/hig3/C/header-bar-menus.page
@@ -12,22 +12,33 @@
</info>
-<title>Header Bar Menus</title>
+<title>Header bar menus</title>
<media type="image" mime="image/png" src="figures/header-bar-menu.png"/>
-<p>Header bars can include a menu which contains actions and options for the current view. These menus are
located at the far right side of the header bar.</p>
+<p><link xref="header-bars">Header bars</link> can include a menu which contains actions and options for the
current view. These menus are located at the far right side of the header bar.</p>
-<p>The most frequently used actions for a view should be placed directly in the header bar. The gear menu
provides access to lesser-used actions, without overwhelming the header bar with less interesting or useful
controls. In this way, the gear menu helps to create focused views that guide the user towards the most
interesting and useful functionality.</p>
+<p>While the most frequently used actions for a view should be placed directly in the header bar, a header
bar menu provides access to lesser-used actions. This ensures that the header bar isn't overwhelmed with less
interesting or useful controls.</p>
+
+<p>In this way, the header bar menus help to create focused views that guide the user towards the most
interesting and useful functionality.</p>
+
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>Use a header bar menu to present additional actions or options for the current view. They are best used
when those actions or options are not used the majority of the time - if there is a set of actions which
deserve more prominence in the view, an <link xref="action-bar">action bar</link> might be a better
choice.</p>
+
+<p>Header bar menus are not a good choice for performing actions on selected content: when content hasn't
been selected, the menu will contain unhelpful insensitive menu items, when it has been selected, possible
actions will not be advertised. <link xref="selection-mode">Selection mode</link> or <link>popovers</link>
are a better choice for this situation.</p>
+
+</section>
<section id="guidance">
<title>Guidance</title>
<list>
-<item><p>Gear menus should only contain actions for the current view or window - this differentiates their
content from application menus.</p></item>
-<item><p>Follow the standard guidelines for menus.</p></item>
-<item><p>A header bar menu is contained within a popover. As such, a header bar menu can include a variety
of controls, such as groups of buttons.</p></item>
-<item><p>Gear menus shouldn't include a close menu item, since this a close action is already provided by
the header bar. It can also be ambiguous as to what a close menu item refers to.</p></item>
+<item><p>Header bar menus should only contain actions for the current view or window - this differentiates
their content from application menus.</p></item>
+<item><p>Follow the <link xref="menus">standard guidelines for menus</link>.</p></item>
+<item><p>A header bar menu is contained within a <link xref="popovers">popover</link>. As such, a header bar
menu can include a variety of controls, such as groups of buttons.</p></item>
+<item><p>Header bar menus shouldn't include a close menu item, since this action is already provided by the
header bar. It can also be ambiguous as to what a close menu item refers to.</p></item>
</list>
</section>
diff --git a/hig3/C/header-bars.page b/hig3/C/header-bars.page
index 8f45ce4..2d5f2c8 100644
--- a/hig3/C/header-bars.page
+++ b/hig3/C/header-bars.page
@@ -24,10 +24,12 @@
<item><p>Controls - header bars provide a place for key controls, typically in the form of
buttons.</p></item>
</list>
-<section id="context">
-<title>Use Your Header Bar to Provide Context</title>
+<section id="when-to-use">
+<title>When to use</title>
-<p>Header bars should provide context for the window content below. This can either be done by placing a
heading in the center of the header bar, or by including a view switcher. Providing context in this way aids
navigation, and clarifies what is displayed in the window itself.</p>
+<p>Header bars are recommended for all application windows. They provide a number of advantages over the
traditional combination of title bars, menu bar and toolbar, including a smaller vertical footprint, and
dynamic navigation and mode changes (such as with <link xref="selection-mode">selection mode</link>).</p>
+
+<p>Header bars are incompatible with menu bars. If your application already incorporates a menu bar, you
should evaluate the alternatives suggested in these guidelines. See the <link xref="menu-bars">menu bar
guidelines</link> for more details on this.</p>
</section>
@@ -43,22 +45,24 @@
</section>
<section id="dynamic">
-<title>Header Bars are Dynamic</title>
+<title>Header bars are dynamic</title>
<p>A header bar can - and should - update along with view or mode changes. This ensures that header bar
controls are always relevant to the current context.</p>
-<p>If the window includes multiple views (accessed through a view switcher), the header bar can include
different controls for each view.</p>
+<p>If the window includes multiple views (accessed through a <link xref="view-switchers">view
switcher</link>), the header bar can include different controls for each view.</p>
+
+<p>If the window incorporates navigation, different controls can be shown depending on the location
displayed in the window itself. It is common to show a back button on the left side of the header bar when
navigating.</p>
</section>
<section id="additional-guidance">
-<title>Additional Guidance</title>
+<title>Additional guidance</title>
<list>
-<item><p>Arrange controls within the header bar according to the three alignment points described in the
Visual Layout guidelines - left, centre and right.</p></item>
-<item><p>New and back buttons should be placed on the left side of the header bar.</p></item>
-<item><p>View selectors should always be placed in the center of the header bar.</p></item>
-<item><p>Follow the lead of the core GNOME 3 applications and repeat the conventions that they
establish.</p></item>
+<item><p>A header bar should always provide context for the window it belongs to. This aids window
identification, and clarifies what is displayed in the window itself. This can either be done by placing a
heading in the center of the header bar, or by including a <link xref="view-switchers">view
switcher</link>.</p></item>
+<item><p>Arrange controls within the header bar according to the three alignment points described in the
<link xref="visual-layout">visual layout guidelines</link> - left, centre and right.</p></item>
+<item><p><gui>New</gui> and back buttons should be placed on the left side of the header bar.</p></item>
+<item><p>Always ensure that there is room for a header bar to be dragged. This is necessary to enable
windows to be moved or resized.</p></item>
</list>
</section>
diff --git a/hig3/C/menu-bars.page b/hig3/C/menu-bars.page
new file mode 100644
index 0000000..b48895c
--- /dev/null
+++ b/hig3/C/menu-bars.page
@@ -0,0 +1,21 @@
+<page xmlns="http://projectmallard.org/1.0/";
+ type="topic"
+ id="menu-bars">
+
+ <info>
+ <credit type="author">
+ <name>Allan Day</name>
+ <email>aday gnome org</email>
+ </credit>
+ <license href="http://creativecommons.org/licenses/by-sa/4.0/";>
+ <p>This work is licensed under a
+ <link href="http://creativecommons.org/licenses/by-sa/4.0/";>Creative
+ Commons Attribution-Share Alike 4.0 International License</link>.</p>
+ </license>
+ </info>
+
+<title>Menu Bars</title>
+
+<p>Alternatives to menu bars include <link xref="header-bar-menus">header bar menus</link>, <link
xref="selection-mode">selection mode</link>, <link xref="application-menus">application menus</link>, and
<link xref="action-bars">action bars</link>.</p>
+
+</page>
diff --git a/hig3/C/search.page b/hig3/C/search.page
index a5ef535..7a6c76b 100644
--- a/hig3/C/search.page
+++ b/hig3/C/search.page
@@ -16,28 +16,38 @@
<media type="image" mime="image/png" src="figures/search.png"/>
-<p>Search allows a content items to be found, by filtering content that is displayed on screen. It is
distinct from find, which allows someone to jump to a particular point in a document.</p>
+<p>Search allows a content items to be located by filtering content that is displayed on screen. It is
distinct from find, which involves moving or highlighting the content that is being searched for, rather than
filtering.</p>
-<p>Search can be a fast and effective way to find content, and applications should ensure that search is
always available when presenting large collections of content.</p>
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>Provide search whenever a large collection of content is presented, and those content items have a
textual component. This could be a collection of actual content items, such as documents, contacts or videos,
or a list of options.</p>
+
+<p>Search is a great way to make it easy for users to find what it is they are looking for, and its
consistent availability means that users can rely on and expect it to be present.</p>
+
+<p>However, while search can be highly effective, and some users will use it, others will not. Therefore,
try to supplement other means for finding content items with search, rather than relying on it
exclusively.</p>
+
+</section>
<section id="search-bar">
-<title>The Search Bar</title>
+<title>The search bar</title>
-<p>Search bars should be placed above the content which is to be searched.</p>
+<p>The standard pattern for search in GNOME 3 utilises a special search bar which slides down from beneath
the header bar.
-<p>In primary windows, the search bar is typically hidden until it is activated by the user. There are three
common ways to activate search in this context:</p>
+In primary windows, the search bar is typically hidden until it is activated by the user. There are three
common ways to activate search in this context:</p>
<list>
-<item><p>Typing when a text entry field is not focused should activate search, and the entered text should
be added to the search field. This is called "Type to search".</p></item>
+<item><p>Typing when a text entry field is not focused should activate search, and the entered text should
be added to the search field. This is called "type to search".</p></item>
<item><p>The keyboard shortcut for search (Ctrl+F).</p></item>
<item><p>A search button in the header bar should allow the search bar to be displayed (the search button
should toggle).</p></item>
-<item><p>If search is a primary method for finding content in your application, you can make the search bar
permanently visible, or visible when the application is first started.</p></item>
</list>
+<p>If search is a primary method for finding content in your application, you can make the search bar
permanently visible, or visible when the application is first started.</p>
+
</section>
<section id="search-results">
-<title>Search Results</title>
+<title>Search results</title>
<list>
<item><p>Search should be 'live' wherever possible - the content view should update to display search
results as they are entered.</p></item>
diff --git a/hig3/C/selection-mode.page b/hig3/C/selection-mode.page
index 61b3f2b..e36763f 100644
--- a/hig3/C/selection-mode.page
+++ b/hig3/C/selection-mode.page
@@ -4,33 +4,49 @@
<info>
<link type="guide" xref="patterns" group="selection-mode"/>
- <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>
+ <name>Allan Day</name>
+ <email>aday gnome org</email>
</credit>
-
+ <license href="http://creativecommons.org/licenses/by-sa/4.0/";>
+ <p>This work is licensed under a
+ <link href="http://creativecommons.org/licenses/by-sa/4.0/";>Creative
+ Commons Attribution-Share Alike 4.0 International License</link>.</p>
+ </license>
</info>
-<title>Selection Mode</title>
+<title>Selection mode</title>
<media type="image" mime="image/png" src="figures/selection-mode.png"/>
-<p>Selection mode is used in conjunction with lists and grids. It allows actions to be performed on items of
content.</p>
+<p>Selection mode is a design pattern for allow actions to be performed on items of content. It is typically
used in conjunction with lists and grids.</p>
-<p>When selection mode is active, check boxes allow items to be selected. Additionally, an action bar is
shown at the bottom of the view. This contains the various actions that can be made on selected content
items.</p>
+<p>When selection mode is active, check boxes allow items to be selected, and an action bar is shown at the
bottom of the view. This contains the various actions that can be made on selected content items.</p>
+
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>Selection mode is appropriate when:</p>
+
+<list>
+<item><p>It is common to perform actions simultaneously on multiple content items.</p></item>
+<item><p>Multiple actions are available to be performed on content items.</p></item>
+<item><p>It is helpful for users to be able to perform actions on content items without opening
them.</p></item>
+</list>
+
+<p>If it is more typical for users to perform actions on single content items, you might want to consider
another design pattern, such as a context menu. Likewise, if there is only one action that can be performed
on content items, a varient of selection mode can be used (an overlaid button could allow the action to be
performed on items directly, rather than requiring them to be selected first, for example).</p>
+
+</section>
<section id="activating-selection-mode">
-<title>Activating Selection Mode</title>
+<title>Activating selection mode</title>
<p>The primary way of activating selection mode is through the selection mode button, which is located in
the header bar and which is identified by a check mark icon. Selection mode can also be activated by rubber
band selection, or by holding Ctrl or Shift and clicking/pressing content items.</p>
</section>
<section id="action-bar">
-<title>Action Bar</title>
-
-<p>An action bar is displayed when selection mode is activated.</p>
+<title>The action bar</title>
<list>
<item><p>Controls in the action bar should be insensitive when no items have been selected. Sometimes
actions may only be applied to multiple content items; in this case the relevant controls should only be
sensitive when multiple items are selected.</p></item>
@@ -39,5 +55,4 @@
</list>
</section>
-
</page>
diff --git a/hig3/C/view-switchers.page b/hig3/C/view-switchers.page
index 9d8fe20..28a4db1 100644
--- a/hig3/C/view-switchers.page
+++ b/hig3/C/view-switchers.page
@@ -3,32 +3,45 @@
id="view-switchers">
<info>
- <link type="guide" xref="patterns" group="view-switchers"/>
- <revision pkgversion="3.0" version="0.1" date="2010-12-04" status="stub"/>
+ <link type="guide" xref="patterns" group="view-switchers"/>
<credit type="author">
- <name>GNOME Documentation Project</name>
- <email>gnome-doc-list gnome org</email>
+ <name>Allan Day</name>
+ <email>aday gnome org</email>
</credit>
-
+ <license href="http://creativecommons.org/licenses/by-sa/4.0/";>
+ <p>This work is licensed under a
+ <link href="http://creativecommons.org/licenses/by-sa/4.0/";>Creative
+ Commons Attribution-Share Alike 4.0 International License</link>.</p>
+ </license>
</info>
-<title>View Switchers</title>
+<title>View switchers</title>
<media type="image" mime="image/png" src="figures/view-switcher.png"/>
<p>A view switcher is a control that allows switching between a number of predefined views. It appears as a
set of toggle buttons that are placed in the center of a header bar.</p>
-<p>View switchers can be used to expose different sets of functionality, as can be seen in the Clocks app.
Alternatively, they can be used to display different sets or sub-sets of content (see the content overview
pattern). A view switcher can be used to change between Artist, Album and Track views in a Music application,
for example.</p>
+<section id="when-to-use">
+<title>When to use</title>
+
+<p>There are two primary cases when a view switcher is appropriate:</p>
+
+<list>
+<item><p>When presenting content, and it is useful to be able to view different sets or sub-sets of content.
For example, a music application could show different views for artists, albums and playlists.</p></item>
+<item><p>If your application provides discrete groups of functionality which are typically used
independently.</p></item>
+</list>
+
+<p>As a rule of thumb, a view switcher should contain between three and five views. If you have more views,
a <link xref="sidebars">sidebar</link> list might be a more appropriate view switching control.</p>
+
+</section>
<section id="additional-guidelines">
-<title>Additional Guidelines</title>
+<title>Additional guidelines</title>
<list>
-<item><p>As a rule of thumb, a view switcher should contain between three and five views. If you have more
views, a sidebar list might be a more appropriate view switching control.</p></item>
<item><p>Each view should have a short and clear title.</p></item>
<item><p>Buttons in the view switcher widget can indicate when there is activity in a view.</p></item>
</list>
</section>
-
</page>
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
