gnome-devel-docs 3.8.1-1 / usr / share / help / sl / hig-book / hig-ch-windows.xml

<?xml version="1.0" encoding="utf-8"?>
<chapter id="windows" lang="sl">
  <title>Windows</title>

  <sect1 id="windows-properties">
    <title>Parts of Windows and System Interaction</title>

    <sect2 id="window-props-titles">
      <title>Titles</title>

      <para>Give every window a title (with the exception of <link linkend="windows-alert">alerts</link> and <link linkend="toolbox-windows">toolboxes</link>). A good window title
      contains information that is relevant to the user, and distinguishes a
      particular window from other open windows. Omit information that does
      not assist in this selection, for example the application's version
      number or vendor name.</para>

      <figure>
        <title>Example of a window title</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="28" fileref="images/windows-titlebar.png" format="PNG" width="379"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-titlebar.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing a window title bar with title
            "Parts of Windows and System Interaction - Mozilla Firefox"</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <para>See the description of each particular window type for title
      formats.</para>
    </sect2>

    <sect2 id="window-props-borders">
      <title>Borders and Window Commands</title>

      <para>Most windows have borders, except certain shaped windows and some
      torn-off windows. Do not attempt to draw your own window borders, but
      instead provide hints to the window manager for the desired border type.</para>

      <para>Different window commands are appropriate to different types of
      window. See the description of each particular window type for a list of
      appropriate window commands. These are the possible window commands:</para>

      <itemizedlist>
        <listitem>
          <formalpara>
            <title>Close</title>

            <para>Closes the window. <emphasis>Always</emphasis> draw this as
            a button on the window border when relevant to the window type.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Maximize</title>

            <para>Causes the window to use all unused screen space.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Minimize</title>

            <para>Causes the window to be temporarily hidden. It will continue
            to appear on the desktop window list.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Roll-up/Unroll</title>

            <para>Shows only the title bar of the window, as if it has been
            "rolled up".</para>
          </formalpara>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="window-props-modality">
      <title>Modality</title>

      <para>A <emphasis role="bold">non-modal</emphasis> window does not
      restrict the user's interaction with other open windows on the
      desktop in any way. Using non-modal windows gives the user maximum
      flexibility to perform tasks within your application in any order and by
      whichever means they choose.</para>

      <para>An <emphasis role="bold">application modal</emphasis> window,
      while it is open, prevents the user from interacting with other windows
      in the same application.</para>

      <para>A <emphasis role="bold">system modal</emphasis> window, while it
      is open, prevents the user from interacting with any other window in any
      application, including the desktop itself.</para>

      <itemizedlist>
        <title>Guidelines</title>

        <listitem>
          <para>Use an application modal window only if allowing interaction
          with other parts of the application while the window is open could
          cause data loss or some other serious problem. Provide a clear way
          of leaving the modal window, such as a <guibutton>Cancel</guibutton>
          button in an alert.</para>
        </listitem>

        <listitem>
          <para>Do not use system modal windows.</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="window-props-focus">
      <title>Focus</title>

      <para>Focus is the means by which the user designates which window
      should receive data from the keyboard, mouse or other input device. If
      using a screen reader or similar assistive technology, focus may also
      designate the window that the user wants to receive information about.
      The focused window is considered the window the user is currently
      "working with".</para>

      <para>Ensure your application functions properly with the three
      different mechanisms by which windows can receive focus in GNOME:</para>

      <itemizedlist>
        <listitem>
          <formalpara>
            <title>Click-to-focus</title>

            <para>A window is focused by clicking in it.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Point-to-focus</title>

            <para>A window is focused by moving the mouse pointer into it.
            Sometimes known as "sloppy focus".</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Keyboard focus</title>

            <para>A window is focused by using a keyboard shortcut such as
            <keycombo><keycap>Alt</keycap><keycap>Tab</keycap></keycombo>.</para>
          </formalpara>
        </listitem>
      </itemizedlist>

      <note>
        <title>Special restrictions for point to focus</title>

        <para>Note that point-to-focus places a number of restrictions on
        GNOME applications that are not present in environments such as MacOS
        or Windows. For example, utility windows shared between multiple
        document windows, like the toolbox in the GIMP Image Editor, cannot be
        context-sensitive— that is, they cannot initiate an action such as
        <guibutton>Save</guibutton> on the current document. This is because
        while moving the mouse from the current document to the utility
        window, the user could inadvertantly pass the pointer over a different
        document window, thus changing the focus and possibly saving the wrong
        document.</para>
      </note>
    </sect2>

    <sect2 id="windows-show-hide">
	<title>Showing and Hiding Windows</title>
	<para>How your application shows and hides windows can greatly affect the user's perception of your application, particularly its performance.</para>
	<itemizedlist><title>Guidelines</title>
		<listitem><para>Always show a window as soon as possible, but make sure your window is the correct size before displaying it. Resizing a window after it is visible is disorienting and gives an unpolished look to your application.</para></listitem>
		<listitem><para>If a window contains information that takes a few seconds to compute or display, it is often better not to fill it in completely before displaying the window.  For example, a window containing a large text area can be shown
quickly, and then the text can be filled in afterwards (provided this does not result in the window resizing).  This will make your application feel more responsive than if you had not shown the window until its content was complete.</para></listitem>
		<listitem><para>Hide a window as soon as possible after it is
closed. Unless an alert might be shown, immediately hide a window that the user has closed by clicking the Close button in the window border--  
your application can still perform any internal clean-up operations afterwards. Besides making the
system appear slow, not doing this can cause the window manager to think the application is not responding, and display an unnecessary alert to the user.</para></listitem>
	</itemizedlist> 

    </sect2>

  </sect1>

  <sect1 id="windows-primary">
    <title>Primary Windows</title>

    <para>A primary window usually presents a view of the user's data,
    such as a text document in a word processor application, an image in a
    drawing program, or calculations in a calculator or spreadsheet
    application. It may also be a view of something more abstract, like a
    game. A single instance of an application may have more than one primary
    window, and more than one kind of primary window.</para>

    <para>A primary window is always shown on the panel window list.</para>

    <figure>
      <title>A typical primary window (gedit)</title>

      <mediaobject>
        <imageobject>
          <imagedata depth="372" fileref="images/windows-primary.png" format="PNG" width="397"/>
        </imageobject>

        <imageobject>
          <imagedata fileref="images/windows-primary.eps" format="EPS"/>
        </imageobject>

        <textobject>
          <phrase>A typical primary window: the gedit document view</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <para>A primary application window normally has a border, a menubar and a
    statusbar, and may also contain one or more toolbars.</para>

    <sect2 id="primary-window-titles">
      <title>Title</title>

      <para>The most important element of a document-based application's 
	      window title is the name of the open document.  For other
	      applications, it is usually the name of the application.
      </para>

      <itemizedlist><title>Guidelines</title>

	<listitem><para>Use <replaceable>Filename</replaceable>
	as the window title for document-based applications. 
	Do not use the full pathname, as
	the filename alone is easier to distinguish amongst
	other open window titles, for example on the window list.</para>
      	<example>
        <title>Using document names as window titles</title>

        <informaltable frame="all">
          <tgroup align="left" cols="2">
            <thead>
              <row>
                <entry>Application</entry>

                <entry>Example window title</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>AbiWord</entry>

                <entry>My Report.abw</entry>
              </row>

              <row>
                <entry>Evolution</entry>

                <entry>Inbox</entry>
              </row>

              <row>
                <entry>Music player</entry>

                <entry>U2 - Better Than the Real Thing</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      	</example>
	<para>If the
      	pathname is important, for example the user has opened two documents
      	with the same name from different directories in the same application,
      	show the full pathname in the statusbar.</para>
	</listitem>
	
	<listitem><para>Before a new document has been saved for the first time, set
	the window title to <replaceable>Unsaved &lt;document type&gt;</replaceable>.
	For example, 	
	<replaceable>Unsaved Drawing</replaceable>, 
	<replaceable>Unsaved Spreadsheet</replaceable>, or the more
	generic <replaceable>Unsaved Document</replaceable>.</para>
	</listitem>



      	<listitem><para>When a document has pending changes, insert an asterisk 
      (*) at the beginning of the window title.
      For example, <replaceable>*Unsaved Drawing</replaceable>,
      <replaceable>*AnnualReport</replaceable>.</para></listitem>
      
	<listitem><para>For non-document-based applications, use 
		<replaceable>Application Name</replaceable>
      		as the window title.</para>

      	<example>
        <title>Using application names as window titles</title>

        <informaltable frame="all">
          <tgroup align="left" cols="2">
            <thead>
              <row>
                <entry>Application</entry>

                <entry>Window title</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Dictionary</entry>

                <entry>Dictionary</entry>
              </row>

              <row>
                <entry>Calculator</entry>

                <entry>Calculator</entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>
      </example>
      </listitem>

      <listitem><para>Do not place version numbers, company names, or other information
      that is of no immediate use to the user in the window title. These
      consume space, making titles in limited spaces such as the system window
      list less useful, and add more text the user has to scan to find useful
      information. In a "beta" product, where version numbers are
      critical for bug information, placing version numbers can be useful, but
      remove them from stable releases. Place version information in the about
      box instead.</para></listitem>

     </itemizedlist>

      <para>While document names are most pertinent to users, we understand
      that application developers may want to increase recognition of their
      application. If you plan to include your application's name in the
      title of a primary window, use the following format:
      <replaceable>Document Name</replaceable> - <replaceable>Application Name</replaceable>.
      This will ensure that the document name appears in limited space
      situations such as the system window list.</para>

      <warning><para>Including the application name in the title of a document-based application is <emphasis role="bold">not</emphasis> recommended.</para></warning>

      <tip><para>Think about naming windows in the context of the panel window list. On a typical screen with a relatively small number of windows open, a window will have 20-30 characters of text and an icon. Consider which text will provide the most immediately obvious clues to a user looking for a particular window.</para></tip>

    </sect2>

    <sect2 id="primary-window-commands">
      <title>Window Commands</title>

      <para>Close, Maximize/Restore, Minimize, Roll-up/Unroll</para>
    </sect2>

    <sect2 id="document-interface-types">
      <title>Relation between Documents and Windows</title>

      <sect3 id="sdi">
        <title>Single Document Interface (SDI)</title>

        <para>A single document interface places each document in its own
        primary window. Toolboxes and other utility windows may be shared
        between multiple SDI documents, but closing them should have no effect
        on the document windows. Use SDI for your GNOME application unless
        there is a compelling reason not to.</para>

        <figure>
          <title>A typical SDI application (Eye of GNOME)</title>

          <mediaobject>
            <imageobject>
              <imagedata depth="226" fileref="images/windows-sdi.png" format="PNG" width="268"/>
            </imageobject>

            <imageobject>
              <imagedata fileref="images/windows-sdi.eps" format="EPS"/>
            </imageobject>

            <textobject>
              <phrase>A typical SDI application: Eye of GNOME being used to
              inspect an icon</phrase>
            </textobject>
          </mediaobject>
        </figure>
      </sect3>

      <sect3 id="mdi">
        <title>Multiple Document Interface (MDI)</title>

        <para>A multiple document interface presents a paned, tabbed or
        similar presentation of two documents<!--, or two views of the same document-->
        within a single window.</para>

        <figure>
          <title>A typical MDI application (gedit) showing three open
          documents on tabbed pages</title>

          <mediaobject>
            <imageobject>
              <imagedata depth="349" fileref="images/windows-mdi.png" format="PNG" width="372"/>
            </imageobject>

            <imageobject>
              <imagedata fileref="images/windows-mdi.eps" format="EPS"/>
            </imageobject>

            <textobject>
              <phrase>A typical MDI application: gedit with three open
              documents in the same window</phrase>
            </textobject>
          </mediaobject>
        </figure>

        <para>MDI has several inherent usability problems, so its use is
        discouraged in applications. It is better to open each document in a
        new primary window, with its own menubar, toolbars and statusbar, or
        allow multiple instances of your application to be run simultaneously.
        In either case, this leaves it for the window manager (acting on the
        user's preferences) rather than your application to decide how to
        group and present document windows from the same application.</para>
      </sect3>

      <sect3 id="csdi">
        <title>Controlled Single Document Interface (CSDI)</title>
        <para>In a typical SDI application, document windows are treated as
        primary. For example, when all document windows have been closed, the 
        application (including utility windows) exits as well. In CSDI a utility
        window is treated as the primary window. For example, closing this
        utility window will close all document windows and exit the application.</para>

        <warning><para>Using CSDI is <emphasis role="bold">not</emphasis> recommended</para></warning>

        <para>CSDI is sometimes used because document windows might be too
        small to have menu bars. Typically this is not the normal use case for the
        application, but does represent a significant minority use case. For
        example, an image editor being used to edit small web page elements will
        often result in very small document windows that cannot accomodate
        a title bar.</para>

        <remark>We should really have a way of doing overflow automatically
                in GTK+.</remark>

        <para>A better way to address this problem is to allow menu bars to "collapse"
        into an overflow button, in much the same way toolbars operate when the window
        shrinks to below the toolbar width. This allows for small windows, but also
        provides an opportunity for people to figure out where their menus have gone.</para>

        <tip><para>Note that if very small documents are the <emphasis>primary</emphasis> use 
        case for your application, you should consider finding a means to avoid windows
        altogether. Windows are not an effective interface for dealing with large
        numbers of small items. Consider looking for a fixed/automated layout system
        for presenting the "documents". Also consider if the "documents" will be primarily
        used in a higher level grouping, in which case that grouping could become the
        document instead.</para></tip>
      </sect3>

    </sect2>
  </sect1>

  <sect1 id="windows-utility">
    <title>Utility Windows</title>

    <para>Utility windows, such as palettes and toolboxes, normally have
    borders. They do not contain a menu bar, a toolbar, or a statusbar.</para>
    <para>
	A utility window should not appear in the panel window list unless
	it is, or may be, the only window shown by an application.
	<!-- Can't think of an example just now! CFB
	For example, a BLAH window  may be shown after
	the main BLAH application window has been closed.
    </para>
    <para> -->
	Otherwise, the utility window should be raised above the application when
	the application window itself is selected from the window list.
    </para>

    <sect2 id="windows-instant-apply">
      <title>Instant apply windows</title>

      <para>For windows that allow the user to change values or settings, such
      as property and preference windows, update those values or settings
      immediately to reflect the changes made in the window. This is known as
      "instant apply". Do not make the user press an
      <guibutton>OK</guibutton> or <guibutton>Apply</guibutton> button to make
      the changes happen, unless either:</para>

      <itemizedlist>
        <listitem>
          <para>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</para>
        </listitem>

        <listitem>
          <para>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.</para>
        </listitem>
      </itemizedlist>

      <para>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 <guibutton>Apply</guibutton> button. Leave the rest of
      the controls as instant apply.</para>

      <remark>FIXME: screenshot of such a window here</remark>

	<itemizedlist>
		<title>Guidelines</title>
		
        	<listitem><para>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. 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.
	</para></listitem>
		<listitem><para>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.</para></listitem>
	</itemizedlist>
	<remark>We need to suggest what to do here, instead of just saying what not to do.</remark>
      </sect2>

	<sect2 id="windows-explicit-apply">
		<title>Explicit apply windows</title>
      <para>If most of the controls in your window are not suitable for
      instant apply, consider making the whole window "explicit
      apply". An explicit apply window has these three buttons in its
      button box, plus an optional <guibutton>Help</guibutton> button:</para>

      <itemizedlist>
        <listitem>
          <formalpara>
            <title>Apply</title>

            <para>Applies all the settings in the window, but does not close
            the window in case the user wishes to change their mind.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Cancel</title>

            <para>Resets all settings in the window to those that were in
            force when the window was opened. Note: this must undo the effects
            of all applications of the <guibutton>Apply</guibutton> since the
            window was opened, not just the most recent one.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>OK</title>

            <para>Applies all settings in the window, and closes the window.</para>
          </formalpara>
        </listitem>
      </itemizedlist>

      <figure id="explicit-apply-figure">
        <title>Buttons in an explicit apply window</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="55" fileref="images/windows-explicit-apply.png" format="PNG" width="387"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-explicit-apply.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing correct positions for Help, Apply,
            Cancel and OK buttons in a dialog</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <remark>FIXME: better example of such a window here</remark>
    </sect2>

    <sect2 id="default-buttons">
      <title>Default Buttons</title>

      <para>When designing a dialog or utility window, you can assign the
      <keycap>Return</keycap> key to activate a particular button in the
      window. GNOME indicates this button to the user by drawing a different
      border around it. For example, the <guibutton>Help</guibutton> button in
      <xref linkend="explicit-apply-figure"/>.</para>

      <para>Choose the default button to be the most likely action, such as a
      confirmation action or an action that applies changes in a utility
      window. Do not make a button the default if its action is irreversible,
      destructive or otherwise inconvenient to the user. If there is no
      appropriate button in your window, to designate as the default button,
      do not set one.</para>

      <para>In particular, it is currently <emphasis>not</emphasis>
      recommended to make the <guibutton>Close</guibutton> button the default
      in an <link linkend="windows-instant-apply">instant apply</link> window, as this
      can lead to users closing the window accidentally before they have
      finished using it.</para>
    </sect2>

    <sect2 id="property-windows">
      <title>Property Windows</title>

      <para>Property windows allow the user to view and change the
      characteristics of an object such as a document, file, drawing, or
      application launcher.</para>

      <figure>
        <title>Example of a property window</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-properties.png" format="PNG" width="302" depth="335"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-properties.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing the "file properties" window
            from Nautilus</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <formalpara>
        <title>Title Format:</title>

        <para><replaceable>Object Name</replaceable> Properties</para>
      </formalpara>

      <formalpara>
        <title>Window Commands:</title>

        <para>Close, Minimize, Roll-up/Unroll</para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para>Place a <guibutton>Close</guibutton> button in the lower right
        corner. A <guibutton>Help</guibutton> may be placed in the lower left
        corner.</para>
      </formalpara>
    </sect2>

    <sect2 id="preference-windows">
      <title>Preferences Windows</title>

      <para>Preferences windows allow the user to change the way an
      application looks or behaves.</para>
      <remark>Much more information needed here!</remark>

      <figure>
        <title>Example of a preferences window</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="249" fileref="images/windows-preferences.png" format="PNG" width="354"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-preferences.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing the Gnibbles preferences window</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <formalpara>
        <title>Title Format:</title>

        <para><replaceable>Application Name</replaceable> Preferences</para>
      </formalpara>

      <formalpara>
        <title>Window Commands:</title>

        <para>Close, Minimize, Roll-up/Unroll</para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para>Place a <guibutton>Close</guibutton> button in the lower right
        corner. A <guibutton>Help</guibutton> may be placed in the lower left
        corner.</para>
      </formalpara>

      <sect3 id="preference-windows-overriding-colors">
        <title>Customizing Fonts and Colors</title>

	<para>If your preferences window allows the user to customize fonts or colors, use the following wording and layout as a guide for these controls:</para>
	
	<example>
		<title>Recommended wording for overriding theme elements- replace with screenshot</title>	
		<programlisting>
	(o) Use font from theme
	(o) Use this font: [ Font selector ]

	(o) Use colors from theme
	(o) Use these colors:
		Background: [ color selector ]
		Foreground: [ color selector ]
		</programlisting>
	</example>

	<para>The wording of the radio buttons may be more specific where required, for example, "Use monospace font from theme", or "Use background color from theme".</para>
      </sect3>

    </sect2>

    <sect2 id="toolbox-windows">
      <title>Toolboxes</title>

      <para>A toolbox provides convenient access to a set of actions and
      toggles through a set of small toolbar-like buttons. Toolboxes can be
      used to provide a specialized group of tools to augment a toolbar
      containing more universal items such as <guibutton>Save</guibutton> and
      <guibutton>open</guibutton>. A single toolbox can be shared between
      multiple documents to save screen space.</para>

      <figure id="toolbox-figure">
        <title>An example of a toolbox</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="89" fileref="images/windows-toolbox-small.png" format="PNG" width="136"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-toolbox-small.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>A screenshot of a toolbox with eight buttons arranged into
            two rows</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <formalpara>
        <title>Title Format:</title>

        <para>Toolboxes have no title</para>
      </formalpara>

      <remark>How then does a screenreader user differentiate between
      toolboxes? --Calum.</remark>

      <remark>ATK hints? How does Windows do this (or does it) ? There's
      not room for a title bar. Maybe we can have apps set the title bar but
      teach the WM to not draw it or something. In any case, for sighted users
      there's not even *room* for a titlebar in a toolbox. -Seth</remark>

      <remark>A toolbox still needs to have an appropriate accessible
      description, so a screenreader user hears some information about its
      content when they focus it. -Calum</remark>

      <remark>I think having the title set but having the WM ignore it might
      be the best way to do this? I'll talk to Havoc. -Seth</remark>

      <formalpara>
        <title>Window Commands:</title>

        <para>Close, Roll-up/Unroll</para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para>Toolboxes have no buttons</para>
      </formalpara>

      <formalpara>
        <title>Resizing:</title>

        <para>Make toolboxes resizable, but only resize by discrete toolbox
        item widths. In other words, the user can resize the toolbox to be one
        item wide, two items wide, three items wide, etc. but not one and a
        half items wide.</para>
      </formalpara>

      <itemizedlist>
        <title>Guidelines</title>

        <listitem>
          <para>Only place buttons in a toolbox that do not open another
          window.</para>
        </listitem>

        <listitem>
          <para>Toolboxes are best used for modal toggle buttons that affect
          the operation of the mouse on the document, such as a set of buttons
          for choosing between paintbrush, eraser, and fill modes in a drawing
          application. Buttons that initiate actions upon clicking (such as a
          save button) are better placed in toolbars.</para>
        </listitem>

        <listitem>
          <para>Ensure that closing a toolbox does not close or otherwise
          alter any primary window with which it is associated.</para>
        </listitem>

        <listitem>
          <para>Do not place toolboxes in the system window list. Toolboxes 
          should always remain above all primary windows with
          which they are associated.</para>
        </listitem>

        <listitem>
          <para>If all primary windows associated with a toolbox are closed or
          minimized, hide the toolbox as well. Show the toolbox again when one
          of the primary windows is opened or restored.</para>
        </listitem>

        <listitem>
          <para>Make a toolbox two items wide by default, unless it is broken
          into <link linkend="toolbox_windows_categories">categories</link>.
          Make categorized toolboxes four items wide by default.</para>
        </listitem>
      </itemizedlist>

      <sect3 id="toolbox_windows_categories">
        <title>Toolbox Categories</title>

        <para>While categories may not be as visually appealing as a toolbox
        homogenously filled with beautiful icons, they make an unwieldy large
        toolbox more managable. Picking a small icon from more than fifteen
        other items is a difficult task. Additionally, categories allow users
        to hide sets of tool items that are not relevant to their current
        task.</para>

        <figure id="example-toolbox-figure">
          <title>A large toolbox broken into categories</title>

          <mediaobject>
            <imageobject>
              <imagedata depth="156" fileref="images/windows-toolbox-large.png" format="PNG" width="136"/>
            </imageobject>

            <imageobject>
              <imagedata fileref="images/windows-toolbox-large.eps" format="EPS"/>
            </imageobject>

            <textobject>
              <phrase/>
            </textobject>
          </mediaobject>
        </figure>

        <itemizedlist>
          <title>Guidelines</title>

          <listitem>
            <para>Break toolboxes with more than sixteen items into
            categories. The best size for a category is between four and ten
            items.</para>
          </listitem>

          <listitem>
            <para>Give each category a label (in title caps) and a collapsing
            arrow. Clicking the label or the arrow toggles the category
            between a collapsed and uncollapsed state.</para>
          </listitem>
        </itemizedlist>
      </sect3>
    </sect2>

    <!-- FIXME - should eventually give general guidelines for other sorts of utility window
    <sect2 id="other-windows">
      <title>Other</title>
      <para>FIXME</para>
    </sect2>
    -->
  </sect1>

  <sect1 id="windows-alert">
    <title>Alerts</title>

    <para>An alert provides information about the state of the application
    system, or asks for essential information about how to proceed with a
    particular task. It is distinct from other types of window in that it is
    not directly requested by the user, and usually contains a message or a
    question rather than editable controls. Since alerts are an unwelcome
    intrusion into the user's work, do not use them except where necessary
    to avoid potential data loss or other serious problems.</para>

    <para>
 	An alert has a border similar to that of a dialog, and is object modal. 
    </para>
    <para>
	An alert should not appear in the panel window list unless
	it is, or may be, the only window shown by an application. For
	example, an appointment reminder alert may be shown after
	the main calendar application window has been closed.
    </para>
    <para>
	Otherwise, an alert should be raised above the application when
	the application window itself is selected from the window list.
    </para>

    <figure id="example-alert-figure">
      <title>An example of an alert</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/windows-alert-information.png" width="251" depth="123" format="PNG"/>
        </imageobject>

        <imageobject>
          <imagedata fileref="images/windows-alert-information.eps" format="EPS"/>
        </imageobject>

        <textobject>
          <phrase>An example of an alert, showing the text "You have an
          appointment with George Wells in 15 minutes", and with an OK
          button to dismiss the window.</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <!--<remark>FIXME: need to redo the spacing and icons in the alert shots. I think I have a glade file for these somewhere. -Seth</remark>-->

    <formalpara>
      <title>Title Format</title>

      <para>Alert windows have no titles, as the title would usually
      unnecessarily duplicate the alert's primary text. This way, users
      can read and respond to alerts more quickly as there is less visual
      noise and confounding text.</para>
    </formalpara>

    <remark>Without a title, how does a screenreader user identify an alert
    window? -Calum</remark>

    <remark>The screen-reader finds out its an alert (do we need a WM
    mechanism for this?) and reads the primary text to identify the alert. The
    whole point for removing the title is that its redundant with the primary
    text, and puts more crap on the screen to be read. This problem applies
    double to users with screenreaders (i.e. reducing extra crap helps them
    even more). -Seth</remark>

    <remark>An alert still needs to have an appropriate accessible description
    (perhaps the primary text of the alert itself?), so a screenreader user
    hears some information about its content when they focus it. -Calum</remark>

    <remark>I'll talk to Havoc about this. -Seth</remark>

    <formalpara>
      <title>Resizing</title>

      <para>Alert windows are not resizable. If the user needs to resize your
      alert, the text is probably not concise enough.</para>
    </formalpara>

    <formalpara>
      <title>Window Commands:</title>

      <para>None</para>
    </formalpara>

    <caution>
      <title>Alerts must stay above their parent</title>

      <para>Alerts do not appear in the system window list. Consequently, take
      care to ensure that alerts stay above their parent window. Otherwise,
      users will be likely to lose the alert and find your application
      unresponsive for no apparent reason. Modal windows should always stay
      above the window(s) they block.</para>
    </caution>

    <!--    
    <para role="library-problem">Buttons in GTK dialogues end up the same size (sized to the button with the longest text label). This is wrong, and looks bad.</para>
    <para role="library-problem">Automatic wrapping of labels happens at funny places and ends up looking wrong. Labels should wrap before the last whole word that does not fit in the allotted space.</para> 
      -->

    <!--
  <para>FIXME - reduced or no frame; one or two buttons: <guibutton>OK</guibutton> for informing alerts, and effectively <guibutton>Cancel</guibutton> and <guibutton>OK</guibutton> for confirmation. No other controls: especially not the "Do not show this again" checkbutton. Perhaps locally modal, rarely globally modal.</para>
    -->

    <sect2 id="alert-text">
      <title>Alert Text</title>

      <para>An alert may contain both primary and secondary text. The primary
      text briefly summarizes the situation. The secondary text provides
      additional information.</para>

	<para>Make both the primary and secondary text selectable. This
	makes it easy for the user to copy and paste the text to another
	window, such as an email message.
	</para>

      <figure id="alert-text-figure">
        <title>Primary and Secondary Text Placement</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-text.png" width="446" depth="178" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-text.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot of an alert showing example of primary text in
            bold, and secondary text in a smaller font underneath.</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <formalpara>
        <title>Primary Text</title>

        <para>The primary text provides the user with a one sentence summary
        of the information or suggested action. This summary should concisely
        contain the essential details of the problem or suggestion. Every
        alert has primary text, displayed in a bold font slightly larger than
	the default. The primary text is punctuated in 'newspaper headline'
	style, that is, it has no terminating period, but it may have a 
	terminating question mark.</para>
      </formalpara>

      <para role="technical-note">Denote primary text with the pango markup:
      <programlisting>&lt;span weight="bold"
      size="larger"&gt;<replaceable>Primary Text</replaceable>&lt;/span&gt;</programlisting></para>

      <formalpara>
        <title>Secondary Text</title>

        <para>Secondary text provides a more in-depth description of the
        problem and suggested action, including possible side effects.
        Secondary text can also provide information that may be helpful in
        allowing the user to make an informed decision. In most situations the
        user should only need the primary text to make a quick decision, but
        they may read the secondary text if they are unsure of the proper
        course of action, or require extra details. Secondary text is
        optional, but if used, place it one text line height beneath the
        primary text using the default font size and weight.</para>
      </formalpara>
    </sect2>

    <sect2 id="alert-button-order">
      <title>Alert Buttons</title>

      <para>Give all alerts an affirmative button that dismisses the alert and
      performs the action suggested in the primary text. Provide a
      <guibutton>Cancel</guibutton> button for all alerts displayed in
      response to a user actions, such as <guimenuitem>Quit</guimenuitem>. If
      the alert warns of a technical problem or other situation that could
      result in data loss, provide a <guibutton>Help</guibutton> button that
      provides more information on the particular situation and explains the
      user's options. You may also provide buttons to perform alternate
      actions that provide another possible solution, fix potential problems,
      or launch related dialogs or programs.</para>

      <figure id="alert-buttons-figure">
        <title>Button ordering and placement for alerts</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-buttons.png" format="PNG" width="425" depth="62"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-buttons.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing ordering and placement of alert
            buttons: Help button in bottom left, and Alternate, Cancel and
            Affirmative buttons in bottom right.</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <formalpara>
        <title>Button Phrasing</title>

        <para>Write button labels as imperative verbs, for example
        <guibutton>Save</guibutton>, <guibutton>Print</guibutton>. This allows
        users to select an action with less hesitation. An active phrase also
        fits best with the button's role in initiating actions, as
        contrasted with a more passive phrase. For example
        <guibutton>Find</guibutton> and <guibutton>Log In</guibutton> are
        better buttons than <guibutton>Yes</guibutton> and
        <guibutton>OK</guibutton>.</para>
      </formalpara>

      <itemizedlist>
        <listitem>
          <formalpara>
            <title>Affirmative Button</title>

            <para>Place the affirmative button in the lower right corner of
            the alert. The affirmative button accepts the action proposed by
            the alert, or simply dismisses the alert if no action is suggested
            (as is the case with an <link linkend="alerts-information">information
            alert</link>).</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Cancel Button</title>

            <para>If the alert was produced in response to a user's action,
            place a <guibutton>Cancel</guibutton> button immediately to the
            left of the affirmative button. This provides an escape route for
            users to stop an action in response to new information, or just if
            they clicked accidentally. Clicking the <guibutton>Cancel</guibutton>
            button reverts the application to its state prior to the user
            action.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Help Button</title>

            <para>A <guibutton>Help</guibutton> button may be used to clarify
            alerts that present potentially destructive options. Place the
            <guibutton>Help</guibutton> button in the lower left corner of the
            alert. When clicked, launch a help window clarifying the
            situation, detailing the actions performed by the other buttons,
            and explaining any side-effects that each action may have.</para>
          </formalpara>
        </listitem>

        <listitem>
          <formalpara>
            <title>Alternate Buttons</title>

            <para>Extra buttons may be used to provide alternates to the
            primary action proposed by the alert text. Place these buttons to
            the left of the <guibutton>Cancel</guibutton> button, or the
            affirmative button if <guibutton>Cancel</guibutton> is not
            present. An example of a common alternate action would be a
            <guibutton>Quit without Saving</guibutton> button in a save
            confirmation alert. This is an alternative to the primary
            suggested action <guibutton>Save</guibutton> and the
            <guibutton>Cancel</guibutton> button.</para>
          </formalpara>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="alert-spacing">
      <title>Spacing and Positioning Inside Alerts</title>

      <para>Using clear, consistent spacing in alerts makes the message easier
      to digest and the available responses more obvious.</para>

      <figure id="alert-spacing-figure">
        <title>Spacing inside an alert</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-spacing.png" format="PNG" width="530" depth="250"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-spacing.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Diagram showing correct spacing to use between controls
            and buttons in an alert window. This is detailed in the guidelines
            below.</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <itemizedlist>
        <title>Guidelines</title>

        <listitem>
          <para>The border around all edges of the alert, and the space
          between the icon and the text, is 12 pixels.</para>
        </listitem>

        <listitem>
          <para>The horizontal spacing between the buttons is 6 pixels.</para>
        </listitem>

        <listitem>
          <para>Add one line break at the standard font size below both the
          primary and secondary text, or 24 pixels if you are using Glade.</para>
        </listitem>

        <listitem>
          <para>Align the top of the icon with the top of the primary text.</para>
        </listitem>

        <listitem>
          <para>Left-align the message text, for western locales.</para>
        </listitem>
      </itemizedlist>

      <tip>
        <title>Technical Details for Proper Layout</title>

        <para>Create a new GtkDialog window specifying the number of buttons
        you wish the alert to contain (and a help button if appropriate). The
        GtkDialog will contain a GtkVBox with an empty upper row, and a lower
        row containing a GtkButtonBox with buttons in it. In the empty upper
        row, place a new GtkHBox. In the left column of the GtkHBox place a
        GtkImage. In the right column of the GtkHBox place a GtkLabel. Inside
        the GtkLabel place <replaceable>Primary Text</replaceable> first
        (using the appropriate Pango markup, see <xref linkend="alert-text"/>),
        then put two linebreaks (return), then place
        <replaceable>Secondary Text</replaceable>. Now change the properties
        for each control according to these tables:</para>

        <table frame="topbot" pgwide="0">
          <title>Properties for the GtkDialog</title>

          <tgroup align="left" cols="2" colsep="0" rowsep="0">
            <thead>
              <row valign="top">
                <entry>Property</entry>

                <entry>Value</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Title</entry>

                <entry>(none)</entry>
              </row>

              <row>
                <entry>Border Width</entry>

                <entry>6</entry>
              </row>

              <row>
                <entry>Type</entry>

                <entry>Top Level</entry>
              </row>

              <row>
                <entry>Resizable</entry>

                <entry>No</entry>
              </row>

              <row>
                <entry>Has Separator</entry>

                <entry>No</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="topbot" pgwide="0">
          <title>Properties for the GtkVBox (included in the dialog by
          default)</title>

          <tgroup align="left" cols="2" colsep="0" rowsep="0">
            <thead>
              <row valign="top">
                <entry>Property</entry>

                <entry>Value</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Spacing</entry>

                <entry>12</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="topbot" pgwide="0">
          <title>Properties for the GtkHBox</title>

          <tgroup align="left" cols="2" colsep="0" rowsep="0">
            <thead>
              <row valign="top">
                <entry>Property</entry>

                <entry>Value</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Spacing</entry>

                <entry>12</entry>
              </row>

              <row>
                <entry>Border Width</entry>

                <entry>6</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="topbot" pgwide="0">
          <title>Properties for the GtkImage</title>

          <tgroup align="left" cols="2" colsep="0" rowsep="0">
            <thead>
              <row valign="top">
                <entry>Property</entry>

                <entry>Value</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Y Align</entry>

                <entry>0.00</entry>
              </row>

              <row>
                <entry>Icon Size</entry>

                <entry>Dialog</entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="topbot" pgwide="0">
          <title>Properties for the GtkLabel</title>

          <tgroup align="left" cols="2" colsep="0" rowsep="0">
            <thead>
              <row valign="top">
                <entry>Property</entry>

                <entry>Value</entry>
              </row>
            </thead>

            <tbody>
              <row>
                <entry>Use Markup</entry>

                <entry>Yes</entry>
              </row>

              <row>
                <entry>Wrap Text</entry>

                <entry>Yes</entry>
              </row>

              <row>
                <entry>Y Align</entry>

                <entry>0.00</entry>
              </row>
            </tbody>
          </tgroup>
        </table>
      </tip>
    </sect2>

    <sect2 id="alerts-information">
      <title>Information Alerts</title>

      <para>Use an information alert when the user must know the information
      presented before continuing, or has specifically requested the
      information. Present less important information by other means such as a
      statusbar message.</para>

      <figure id="information-alert-figure">
        <title>An information alert</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="123" fileref="images/windows-alert-information.png" format="PNG" width="251"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-information.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase/>
          </textobject>
        </mediaobject>
      </figure>

      <itemizedlist>
        <title>An information alert...</title>

        <listitem>
          <para>uses the stock information icon.</para>
        </listitem>

        <listitem>
          <para>presents a selectable message and an <guibutton>OK</guibutton>
          button. The button is placed in the bottom right corner of the
          alert. Pressing <keysym>Enter</keysym> or <keysym>Escape</keysym>
          dismisses the alert.</para>
        </listitem>

        <listitem>
          <para>may present a convenience button to give access to a relevant
          object. For example, a <guibutton>Details</guibutton> button in an
          appointment reminder alert that opens the appointment's property
          window. Place this button to the left of the affirmative button.</para>

          <!-- FIXME: Reword -->
        </listitem>
      </itemizedlist>

      <formalpara>
        <title>Window Commands:</title>

        <para>Roll-up/Unroll, Minimize (if the alert has no parent window),
        Close</para>
      </formalpara>
    </sect2>

    <sect2 id="alerts-error">
      <title>Error Alerts</title>

      <para>Display an error alert when a user-requested operation cannot be
      sucessfully completed. Present errors caused by operations not requested
      by the user by another means, unless the error could result in data loss
      or other serious problems. For example, an error encountered during an
      email check initiated by the user clicking a toolbar button should
      present an error alert. However, an error encountered in an automated
      periodic email check would more appropriately report failure with a
      statusbar message.</para>

      <figure id="error-alert-figure">
        <title>An error alert</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-error.png" width="287" depth="156" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-error.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase/>
          </textobject>
        </mediaobject>
      </figure>

      <itemizedlist>
        <title>An error alert...</title>

        <listitem>
          <para>uses the stock error icon.</para>
        </listitem>

        <listitem>
          <para>presents a selectable message and an <guibutton>OK</guibutton>
          button. The button is placed in the bottom-right corner of the
          alert. Pressing <keysym>Enter</keysym> may dismiss the error alert.</para>
        </listitem>

        <listitem>
          <para>may present a convenience button to allow immediate handling
          of the error. For example, a <guibutton>Format...</guibutton> button
          in a "This disk is not formatted" alert. Place this button
          to the left of the affirmative button.</para>
        </listitem>
      </itemizedlist>

      <formalpara>
        <title>Window Commands:</title>

        <para><!-- Minimize, ??? -->Roll-up/Unroll</para>
      </formalpara>
    </sect2>

    <sect2 id="alerts-confirmation">
      <title>Confirmation Alerts</title>

      <para>Present a confirmation alert when the user's command may
      destroy their data, create a security risk, or take more than 30 seconds
      of user effort to recover from if it was selected in error.</para>

      <figure id="confirmation-alert-figure">
        <title>A confirmation alert</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-confirmation.png" contentwidth="450" contentdepth="162" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-confirmation.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase/>
          </textobject>
        </mediaobject>
      </figure>

      <itemizedlist>
        <title>A confirmation alert...</title>

        <listitem>
          <para>uses the stock warning icon.</para>
        </listitem>

        <listitem>
          <para>presents a selectable message and a button labelled with 
          a verb or verb phrase
          describing the action to be confirmed, or labelled
          <guilabel>OK</guilabel> if such a phrase would be longer than three
          words. This button is placed in the bottom right corner of the
          alert.</para>
        </listitem>

        <listitem>
          <para>presents a <guibutton>Cancel</guibutton> button that will
          prevent execution of the user's command. This button is placed
          to the immediate left of the <guibutton>OK</guibutton> or equivalent
          button.</para>
        </listitem>

        <listitem>
          <para>may present an alternate action button or a convenience
          button. Place this button to the left of the <guibutton>Cancel</guibutton>
          button.</para>
        </listitem>
      </itemizedlist>


      <formalpara>
        <title>Window Commands:</title>

        <para><!-- Minimize, ??? -->Roll-up/Unroll</para>
      </formalpara>

      <sect3 id="save-confirmation-alerts">
        <title>Save Confirmation Alerts</title>

        <para>Save confirmation alerts help ensure that users do not lose
        document changes when they close applications. This makes closing
        applications a less dangerous operation.</para>

        <figure id="save-alert-figure">
          <title>A save confirmation alert</title>

          <mediaobject>
            <imageobject>
              <imagedata fileref="images/windows-alert-save.png" width="500" depth="194" format="PNG"/>
            </imageobject>

            <imageobject>
              <imagedata fileref="images/windows-alert-save.eps" format="EPS"/>
            </imageobject>

            <textobject>
              <phrase>Save confirmation alert: "[ Close without Saving] [
              Cancel ] [[ Save ]] "</phrase>
            </textobject>
          </mediaobject>
        </figure>

        <formalpara>
          <title>Primary Text</title>

          <para>Save changes to document <replaceable>Document Name</replaceable>
          before closing?</para>
        </formalpara>

        <para>You may replace <quote>document</quote> with a more appropriate
        description, for example <quote>image</quote> or <quote>diagram</quote>
        if the document in question is not primarily text.</para>

        <formalpara>
          <title>Secondary Text</title>

          <para>If you close without saving, changes from the last
          <replaceable>Time Period</replaceable> will be discarded</para>
        </formalpara>

        <para role="explanation">The secondary text provides the user with
        some context about the number of changes that might be unsaved.</para>

        <formalpara>
          <title>Buttons</title>

          <para><guibutton>Close without Saving</guibutton>,
          <guibutton>Cancel</guibutton>, <guibutton>Save</guibutton></para>
        </formalpara>
      <para>
When a confirmation alert is needed,
present it immediately. If the user confirms closing without saving,
hide the alert and the document or application  window immediately, 
before doing any necessary internal clean-up.
If the user chooses to save before
closing, hide the alert immediately but show the document window until the document is
saved, in case an error occurs.  Then hide the document window immediately after it has been saved successfuly.
	</para>
      </sect3>
    </sect2>

    <sect2 id="alerts-authentication">
      <title>Authentication Alerts</title>

      <para>Authentication alerts prompt the user for information necessary to
      gain access to protected resources, such as their username or password.
      Authentication alerts are a special kind of alert because they are both
      routine and largely unavoidable. Every attempt should be made to retain
      information entered into an authentication alert as long as is possible
      within security constraints.</para>

      <figure id="authentication-alert-figure">
        <title>An authentication alert</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-alert-authentication.png" width="460" depth="279" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-alert-authentication.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase/>
          </textobject>
        </mediaobject>
      </figure>

      <para><itemizedlist><title>Guidelines</title><listitem><para>Use the
      stock authentication icon.</para></listitem><listitem><para>Show
      a labelled field for each required item of information. Suggested fields
      are <guilabel>Username</guilabel> and <guilabel>Password</guilabel> (in
      that order) where appropriate.</para></listitem><listitem><para>If it is
      secure to retain the username longer than the password, pre-fill the
      username field and give focus to the password field when the alert is
      displayed.</para></listitem><listitem><para>Show a button labelled with
      a verb or verb phrase describing the authentication action, or
      <guilabel>OK</guilabel> if there is no appropriate phrase or such a
      phrase would be longer than three words. Place this button in the bottom
      right corner of the alert.</para></listitem><listitem><para>Do not
      enable the <guibutton>OK</guibutton> or equivalent button until all
      fields that require input have been attended to by the user. Remember
      that not all fields may require input however, for example an empty
      password may be acceptable in some applications.</para></listitem><listitem><para>Show
      a <guibutton>Cancel</guibutton> button that will prevent authentication
      and close the alert. Place this button to the immediate left of the
      <guibutton>OK</guibutton> or equivalent button.</para></listitem><listitem><para>Place
      any alternative action or convenience button to the left of the
      <guibutton>Cancel</guibutton> button.</para></listitem><listitem><para>When
      the user presses <keycap>Return</keycap> in the last field, activate the
      default button. When the user presses <keycap>Return</keycap> in any
      other field, move focus to the next field.</para></listitem></itemizedlist></para>

      <formalpara>
        <title>Window Commands:</title>

        <para><!-- Minimize, ??? -->Roll-up/Unroll</para>
      </formalpara>
    </sect2>
  </sect1>

  <sect1 id="windows-progress">
    <title>Progress Windows</title>

    <para>A progress window can be used to provide <link linkend="feedback">feedback</link>
    during an operation that takes more than a few seconds. See <xref linkend="controls-progress-bars"/> for more details about proper use of
    progress bars.</para>
		
    <para>A progress window should always appear as an independent window in a window list.
	If progress of a task makes a window temporarily unusable, do not present a modal dialog-like progress window in front of it.
	Instead, present progress somewhere in the original window, making all its other elements temporarily insensitive.
	This helps reduce visual clutter.</para>

    <figure id="example-progress-figure">
      <title>An example of a progress window</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/windows-progress.png" width="425" depth="159" format="PNG"/>
        </imageobject>

        <imageobject>
          <imagedata fileref="images/windows-progress.eps" format="EPS"/>
        </imageobject>

        <textobject>
          <phrase>An example of a progress window</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <formalpara>
      <title>Title Format</title>

      <para>Progress windows should have a title representing the overall
      operation: for example <guilabel>Copying Files</guilabel>, <guilabel>Installing</guilabel>, or <guilabel>Calling</guilabel>.
      As with other window titles, do not end progress window titles with an ellipsis.</para>
    </formalpara>

    <formalpara>
      <title>Resizing</title>

      <para>Progress windows should be resizable if they contain non-static
      information the user may want to copy (for example, the source URL in a
      download progress window). Otherwise they should not be resizable.</para>
    </formalpara>

    <itemizedlist>
      <title>Guidelines</title>

      <listitem>
        <para>It is often better to use the progress bar contained in many
        primary windows' statusbar rather than a progress window. See
        <xref linkend="progress-windows-vs-status-bar"/> for details on
        choosing between the two.</para>
      </listitem>

      <listitem>
        <para>Progress windows should use primary and secondary text like an
        alert. See <xref linkend="alert-text"/></para>
      </listitem>

      <listitem>
        <para>The progress bar text should provide an idea of how much work
        has been completed. It is better to provide specific information
        rather than a unitless percentage. For example, "13 of 19 images
        rotated" or "12.1 of 30 MB downloaded" rather than
        "13% complete".</para>
      </listitem>

      <listitem>
        <para>If possible, an estimate of the time left until the operation is
        complete should also be included in the progress bar text. Indicate
        that the "time left" is an estimate using the word
        "about".</para>
      </listitem>

      <listitem>
        <para>Immediately beneath the progress bar, place italicized text
        indicating the current sub-operation being performed. This might be a
        step in a sequence, "Contacting control tower for permission to
        land", or it could be the current object being operated on in a
        bulk operation, "Rotating MonaLisa.png", "Rotating
        StarryNight.png".</para>
      </listitem>

      <listitem>
        <para>If the operation in progress is potentially hazardous
        (destructive, costly, etc) or heavily taxes a limited resource for
        more than ten seconds (network bandwidth, hard disk, CPU, etc),
        consider placing a <guibutton>Pause</guibutton> <link linkend="controls-toggle-buttons">toggle button</link> to the right of
        the <guibutton>Cancel</guibutton> button. When paused, the italicized
        current sub-operation text should have " (Paused)" appended.
        This will allow users to perform important tasks requiring that
        resource, or give them time to think whether they want to procede with
        a dangerous operation they inadvertantly triggered.</para>
      </listitem>
    </itemizedlist>

    <figure id="example-complex-progress-figure">
      <title>A progress window for a file copy operation</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/windows-progress-copy-file.png" width="408" depth="227" format="PNG"/>
        </imageobject>

        <imageobject>
          <imagedata fileref="images/windows-progress-copy-file.eps" format="EPS"/>
        </imageobject>

        <textobject>
          <phrase>A progress window for a copy operation</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <sect2 id="progress-window-checklists">
      <title>Checklist Windows</title>

      <para>Occasionally a procedure is comprised of a series of user
      performable actions. In these cases, particularly when it is desirable
      that the user acquire some familiarity with the actions involved in a
      procedure, checklist windows may be used.</para>

      <example>
        <title>Firewall Setup Wizard</title>

        <para>A personal firewall setup wizard might install the firewall
        package, add entries for the firewall to /etc/xinetd.conf, restart the
        internet super-daemon, and configure the user's web browser to
        operate through the firewall. It may be desirable that the user is
        exposed to the series of actions involved in setting up the firewall to
        increase the chances that they will be sucessful in making
        modifications later, if they so desire.</para>
      </example>

      <figure id="example-checklist-start-figure">
        <title>An example checklist window (Ready to Start)</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-progress-checklist-start.png" width="422" depth="249" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-progress-checklist-start.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>A checklist window</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <figure id="example-checklist-in-progress-figure">
        <title>An example checklist window (In Progress)</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-progress-checklist.png" width="336" depth="220" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-progress-checklist.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>A checklist window</phrase>
          </textobject>
        </mediaobject>
      </figure>
      
      <figure id="example-checklist-done-figure">
        <title>An example checklist window (Completed)</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-progress-checklist-done.png" width="356" depth="223" format="PNG"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-progress-checklist-done.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>A checklist window</phrase>
          </textobject>
        </mediaobject>
      </figure>

      <itemizedlist>
        <title>Guidelines</title>

        <listitem>
          <para>If knowing the series of steps in an operation isn't that
          useful to the user, just use a regular progress window. Remember
          that you are probably more interested in the information than most
          users, many of whom will find the technical steps confusing rather
          than helpful.</para>
        </listitem>

        <listitem>
          <para>Unlike regular progress windows, checklist windows should not
          close automatically when the operation is complete and should
          require explicit user input before they begin. This is because one
          of their purposes is to inform the user concerning an
          operation's contingent steps.</para>
        </listitem>

        <listitem>
          <para>The progress bar indicates progress in the overall operation,
          not each step. While this is more difficult to program, it is the
          information most useful to the user. Just estimate how long each of
          the steps takes relative to each other and assign each step a fixed
          ratio of the progress bar's progress accordingly.</para>
        </listitem>

        <listitem>
          <para>Do <emphasis>not</emphasis> use a checklist window for a
          series of internal programmatic steps, use a regular progress
          window. For example "Connect to mail server",
          "Authenticate with mail server", "Download
          messages", "Disconnect" would <emphasis>not</emphasis>
          be an appropriate series of steps for a checklist window, but would
          be appropriate sub-operation steps for a regular progress window.</para>
        </listitem>
      </itemizedlist>
    </sect2>
  </sect1>

  <sect1 id="windows-dialog">
    <title>Dialogs</title>

    <para>A dialog provides an exchange of information, or dialog, between the
    user and the application. Use a dialog to obtain additional information
    from the user that is needed to carry out a particular command or task.</para>
	<para>A dialog should not appear in the panel window list.
	Any open dialogs should be raised above the application when
	the application window itself is selected from the window list.</para>

    <figure>
      <title>An example of a dialog</title>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/windows-dialog-tabbed.png" width="357" depth="322" format="PNG"/>
        </imageobject>

        <imageobject>
          <imagedata fileref="images/windows-dialog-tabbed.eps" format="EPS"/>
        </imageobject>

        <textobject>
          <phrase>An example of a tabbed dialog: the GNOME print dialog</phrase>
        </textobject>
      </mediaobject>
    </figure>

    <formalpara>
      <title>Title Format:</title>

      <para><replaceable>Name of command that opened the dialog</replaceable>
      (without any trailing ellipsis)</para>
    </formalpara>

    <formalpara>
      <title>Window Commands:</title>

      <para>Minimize, Roll-up/Unroll</para>
    </formalpara>

    <formalpara>
      <title>Buttons:</title>

      <para>Follow the guidelines for Alert buttons, see <xref linkend="alert-button-order"/>.</para>
    </formalpara>

    <para>Your dialog may specify a default button, that is activated when the
    user presses the <keycap>Return</keycap> key. See <xref linkend="default-buttons"/> for guidance on choosing an appropriate
    default button.</para>

    <sect2 id="dialog-buttons">
      <title>Additional Buttons</title>

      <para>You can include other buttons in a dialog's main button area
      in addition to the affirmative button and <guibutton>Cancel</guibutton>,
      but any more than one or two such buttons will make the dialog appear
      complicated and difficult to use. As with any other button, keep the
      labels as concise as possible to minimize this effect.</para>

      <itemizedlist>
        <title>Guidelines</title>

        <listitem>
          <para>Place buttons that apply to the dialog as a whole in the main
          button area row at the bottom of the dialog, to the left of the
          <guibutton>Cancel</guibutton> button.</para>
        </listitem>

        <listitem>
          <para>Place buttons that apply to one or a few controls next to
          their associated controls. For instance, place a
          <guibutton>Browse...</guibutton> button at the trailing edge of the
          text field it fills in.</para>
        </listitem>
      </itemizedlist>
    </sect2>

    <sect2 id="dialog-layout">
      <title>Layout</title>

      <para>A clean, logical dialog layout helps the user to quickly
	understand what information is required from them.</para>

      <itemizedlist><title>Guidelines</title>

      <listitem><para>
      Arrange controls in your dialog in the direction that people read.
      In western locales, this is generally left-to-right, top-to-bottom.
      Position the main controls with which the user will interact as close to
      the upper left corner as possible. Follow similar guidelines for
      arranging controls within groups in the dialog, and for specifying the
      order in which controls are traversed using the <keycap>Tab</keycap>
      key.</para></listitem>

      <listitem><para>
    	When opening a dialog, provide initial keyboard focus to the
      component that you expect users to operate first. This focus is
      especially important for users who must use a keyboard to navigate your
      application.</para></listitem>

      <listitem><para>Provide and show sensible default values for as many of the
      controls in your dialog as possible when it is opened, so the user does
      not have to generate the information from scratch. These defaults may
      come from system settings (for example, hostname or IP address), or from
      information that the user has previously entered in this or another
      application (for example, email address or network proxy).</para></listitem>
	</itemizedlist>

      <para>See <xref linkend="design"/> for more detailed information on
      arranging controls in dialogs.</para>

      <para>See <xref linkend="controls-notebooks"/> for information on using
      tabbed notebook controls in dialogs.</para>
    </sect2>

    <sect2 id="common-dialogs">
      <title>Common Dialogs</title>

      <para>The gtk and GNOME libraries provide standard dialogs for many
      common tasks, including opening and saving files, choosing fonts and
      colors, and printing. Always use these when the user is performing one
      of these tasks. You may modify the dialogs to reflect the needs of your
      particular application (for example, adding preview
      <guibutton>Play</guibutton> and <guibutton>Stop</guibutton> buttons to
      the Open File dialog in an audio application), but do not change or
      remove features so much as to make them unrecognizable.</para>
    </sect2>
  </sect1>

  <sect1 id="windows-assistant">
    <title>Assistants</title>

    <!--<remark>FIXME: need to finish this section</remark>-->

    <para>An assistant is a secondary window that guides the user through an
    operation by breaking it into sequential steps. Assistants are useful for
    making complex operations less intimidating, as they restrict the
    information visible to the user at any given moment.</para>

    <para>Because assistants provide a relatively small number of controls on
    the screen at any given time, they have sufficient space for inline
    documentation. Therefore, do not include a <guibutton>Help</guibutton>
    button in an assistant window. If you cannot make an operation
    sufficiently clear in an assistant without resorting to a
    <guibutton>Help</guibutton> button, you need to simplify it further.</para>

    <para>Assistants do have major downsides. After using an assistant
    it is often hard to figure out where the individual settings aggregated
    into the assistant are stored. Often people will resort to re-running
    the assistant, re-entering many settings that they don't want to change.
    <remark>Why do they need to re-enter anything? The assistant should
	be populated with the exisiting settings whenever it is run.</remark>
    </para>

    <warning><para>Assistants are often used in situations where a better
    solution would be to simplify, or even better automate, the process.
    Before using an assistant to step people through a complex operation,
    consider if the operation can be fundamentally simplified so an
    assistant is unnecessary.</para></warning>
    

    <formalpara>
      <title>Window Commands:</title>

      <para>Close, Minimize/Unminimize, Roll-up/Unroll</para>
    </formalpara>

    <sect2 id="assistant-first-page">
      <title>Introductory Page</title>

      <para>The first page provides the user with the "big picture".
      Place the title of the assistant in the window's title bar and the
      assistant's title area, along with an optional picture. Beneath
      this, state the goal of the assistant, and, if it is not obvious, where
      the user can find the information the assistant will be asking for.</para>

      <formalpara>
        <title>Title Format:</title>

        <para><replaceable>Assistant Title</replaceable></para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para><guibutton>Cancel</guibutton>, <guibutton>Forward</guibutton></para>
      </formalpara>

      <figure>
        <title>Example of the first page of an assistant</title>

        <mediaobject>
          <imageobject>
            <imagedata fileref="images/windows-assistant-first-page.png" format="PNG" width="502" depth="318"/>
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-assistant-first-page.eps" format="EPS"/>
          </imageobject>

          <textobject>
            <phrase>Screenshot showing the first page of an assistant for
            creating a new email account</phrase>
          </textobject>
        </mediaobject>
      </figure>
    </sect2>

    <sect2 id="assistant-middle-page">
      <title>Content Pages</title>

      <para>Content pages contain the actual settings of the assistant.
      Summarize the type of setting present on each content page in its title
      area. For example, <guilabel>Mail Server</guilabel>.</para>

      <formalpara>
        <title>Title Format:</title>

        <para><replaceable>Assistant Title</replaceable> - (<replaceable>Current
        Page </replaceable> of <replaceable>Total Pages</replaceable>)</para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para><guibutton>Cancel</guibutton>, <guibutton>Back</guibutton>,
        <guibutton>Forward</guibutton></para>
      </formalpara>

<!--
      <figure>
        <title>Example of a middle page of an assistant</title>

        <mediaobject>
          <imageobject>
            <imagedata depth="341" fileref="images/windows-assistant-middle-page.png"
            format="PNG" width="452" />
          </imageobject>

          <imageobject>
            <imagedata fileref="images/windows-assistant-middle-page.eps" format="EPS" />
          </imageobject>

          <textobject>
            <phrase>Screenshot showing the third page of an email account
            assistant, asking for mail server information</phrase>
          </textobject>
        </mediaobject>
      </figure>
-->
    </sect2>

    <sect2 id="assistant-last-page">
      <title>Last Page</title>

      <para>The last page should summarize the settings that will be changed
      by the assistant, and how the user can modify them later.</para>

      <formalpara>
        <title>Title Format:</title>

        <para>Finish <replaceable>Assistant Title</replaceable></para>
      </formalpara>

      <formalpara>
        <title>Buttons:</title>

        <para><guibutton>Cancel</guibutton>, <guibutton>Back</guibutton>,
        <guibutton>Finish</guibutton></para>
      </formalpara>
    </sect2>
  </sect1>
</chapter>