[HIG] REVIEW mini-HIG Draft 1

[Gregory Merchan <merchan phys lsu edu>]

Just one big list. :-)

Overall
 * Check typesetting points.
 * General principles when developing on X11:
   * Do not fight the toolkit.
   * Do not fight the window manager.
   * Remember the network.
     (Nothing special need be done, but occassionaly 
      testing remotely is a good idea.)
   * Adhere to the ICCCM.
     (The more carefully you read it,
      the more rules you know and
      the more you know them
      the more you can bend them.)
 * Provide rationale for everything, even the obvious.
   * If something really doesn't need a rationale,
     it probably really doesn't need to be here.
 * Perhaps a reflow of the main sections is in order?
   Partial recommendation:
     ...
     Drawing
       Icons
       Focus
       ...
     Input and Hardware
     Controls (a.k.a. Widgets) <- small subtitle or first sentence
     Primary Windows
       Menus
       Toolbars
       ...
     Secondary Windows
       Palettes/Toolboxes/Panels
       Dialogs
       Assistants
       Alerts
       ...
     Tertiary Windows (?)
       Splash screens
       Input method boxes
       Search boxes (see GtkTreeView)
       ...
     ...
   Probably not the best order. Perhaps it the order could also be a
   guide to development? (Not explicitly, of course.)

Front matter
 * Suggested title: The GNOME 2.0 Interface Guidelines
 * Is there a reason Colin's name is all lower case?

1 Introduction
  * I concur with these statements as the pertain to the introduction:
    * http://mail.gnome.org/archives/hig/2001-October/msg00071.html
    * http://mail.gnome.org/archives/hig/2001-October/msg00052.html

2 Menus and Toolbars

2.1 Menu Principles
    * Should application menus have icons? Quid pro quo?
      (I think they look baroque and are usually too small to be helpful.
       The bookmark icon feature in galeon is neat though.)
    * Insert "or options"
      "Menus are a means by which a set of commands or options . . ."
    * GDP word list calls a GtkOptionMenu a drop-down list box.
      It calls the GtkList or GtkTree or a single column GtkCList or GtkCTree
      a list box. (These are Gtk+ 1.2 names) What the GDP calls a 
      drop-down list box and a list box are very different in appearance;
      the drop-down list box looks like a menu, the list box looks like a 
      column of text. Even if GtkOptionMenu is not considered a menu by the 
      guidelines, it still holds that options are available on menus; unless 
      the guidelines will forbid that.

2.1.1 Drop-Down Menus
      * 'Visible' is not a good word; items may be obscured by overlapping
        windows, iconification, or being off screen.
      * Each primary window should have a menubar, no others should.
2.1.2 Popup menus
      * Capitalize consistently - Popup Menus
      * These are accessible from the keyboard via Shift+F10
      * Organization
        * Context groups should provided when there is a context hierarchy.
        * Context groups should be sorted from general context to specific.
        * Separators should be placed between context groups.
        - Rationale: As in web pages, the context under the cursor is not
          immediately discernable. Consistently ordered context groups aid
          muscle memory.

 I recommend that 2.1.1 and 2.1.2 be reflowed and perhaps a section on
 option menus be added. The section would then be:
      2.1.1 Menu Types
      2.1.1.1 Drop-Down Menus
      2.1.1.2 Popup Menus
      2.1.1.3 Option Menus


2.1.3 Menu Organisation
      * There are some common apps which do not have static menubars, such
        as emacs. I think we need guidelines for how to do this rather than
        a blanket exclusion. The Mac menubar is dynamic.
      * Separators also provide (to a small extent) a buffer to movement.

2.1.4 Naming Conventions
      * '...' is not an ellipsis as it lacks the requisite space. This might
        be confusing to some. (I wondered about it.)

2.1.5 Unavailable Items
      * Rename as 'Unavailable Commands or Options'
      * The widgets themeselves are insensitive.

2.1.6 Toggled menu items.
      * The check items should be relabeled as in the 'Show/Hide Toolbar'
        example further down.
      * I suspect that the first item should never be a check or radio item.

2.1.7 Shortcuts and accelerators.
      * Rename as "Keyboard Shortcuts: Access keys and Accelerators", making
        appropriate changes elsewhere.
      * This section should be moved or it should be explicitly stated that 
        Alt+<accesskey> activates widgets.
      * GTK does not allow Delete (or a few other keys) to be accelerators.

2.2 Standard Menus
    * Should menu items show long tooltips in the status bar?
    * Should they have tooltips at all?
    * What about this?
      _File _Edit _View Fo_rmat <app-specific> _Options _Help
    * What about things like _Buffers, _Documents, _Windows?

2.2.1 File
      * All items should have access keys.
      * Isn't a menu a _must_ for a primary app window?
      * All apps should use _File. I don't think the word is used as a noun
        here. _Edit, _View, and _Format (some other traditional items) all
        seem to be verbs. I know this seems to contradict noun-verb ordering,
        but I think that with a menubar, the noun is the part of the
        app window, the menubar item is the verb, and the submenu item is
        a qualifier. Some examples:
            "This document is to be _File[d] by Save[ing]."
            "This selected text is to be _Edit[ed] by C_ut[ting]."
            "This page is to be _View[ed] _Full Screen."
        Also, "On UNIX, everything is a file" is often misunderstood. This
        does not mean a file in the sense of a manila folder or a document.
        File is there used in the same sense as in rank and file. In
        Spanish, this would be correctly translated as:
            "Sobre UNIX, todo es una fila."
        Not as:
            "Sobre UNIX, todo es un fichero."
        (I hope my Spanish is correct. ;-)

2.2.1.1 File Access
        * See above. Also supporting the above argument is that we may not
          be dealing only with files, but more often now with collections
          of files.
        - New
          * Is this the place to state that the first untitled document
            should be called "Untitled", the second "Untitled 1" (or is
            that "Untitled 2"?), and so forth?
        - Open
          * Why should we not merely present the already open document?
          * Why should the blank document be replaced? (On emacs, the
            blank is like scratch paper, and very useful at that.)
          * The file should be opened according to MDI settings, not
            necessarily in a new window.
        - Close <docname>
          * What if there are multiple views of the same document?
          * Why should the name of the current document be on the item?
            A document name may be very long and neither a larger than screen
            menu, nor an ellipsised name seems palatable.
          * Creating a blank document when closing the last file prevents us
            from eventually being rid of the application-centric Quit or
            Exit. If instead an initial blank is kept, we achieve the same
            effect. If the app is invoked with a particular document, then
            the intent may well be to edit that document and no more.
          * Is this the right place for this?

2.2.1.2 Printing
        - Print
          * As Matthew suggests, I favor Publish. Export may also be
            appropriate. Placing a document on a website is more common
            today, or will be soon. Print may also imply a WYSIWYG interface
            and that is not always the best. (See LyX or structured editors).
        - Print Preview
          * As above.
        - Print Setup
          * This is "Page Setup..." in all instances of which I am aware.

2.2.1.3 Quitting
        * As mentioned before, we should be moving away from applications
          being the focus of the environment.
        * Isn't this the place for _Close?
        - Quit <appname>
          * The appname may be long and I don't see the utility of 
            presenting it here.
        - Close All
          * In an SDI application, Close All should not be present.

2.2.2 Edit
      * Gtk+ 2.0 (and 1.2, iirc) does not allow Del or Delete, among
        other keys, to be an accelerator. This should be fixed.
        (Bug report #)
      * This seems shy at least an item:  "Fi_nd Again   Ctrl-G"

2.2.2.1 Modification History
        - Undo <action>
          * Eventually (Big HIG?) it may be worthwhile to say what
            the boundaries of an action should be.
        - Redo <action>
          * Should this be disabled when after some undoings the user
            done something else?

2.2.2.2 Clipboard Access and Deletion
        * We should emphasize that explicit Cut/Copy/Place use the
          CLIPBOARD selection.
        - Cut
          * s/current/PRIMARY/g
          * The order is incorrent. First the contents are placed on the
            clipboard and then they are removed.
        - Copy
          * s/current/PRIMARY/g
        - Paste
          * It is possible to detect if there is something on the clipboard.
            This should be a library routine probably called when the menu
            is made visible and with a reasonable polling frequency if the
            menu remains visible (as when torn off).
        - Delete
          * s/current/PRIMARY/g
          * Pending a check of the ICCCM, perhaps PRIMARY can contain
            non-text data too.

2.2.2.3 Manipulating the Selection
        * Rename this. s/Selection/Boundaries of Selected Data/
        - Select All
        - Select None
          * Should not this merely be Deselect?

2.2.2.4 Searching and Replacing
        * 'Search'-ing, 'Find'-ing, what is what?
        * Include also "Fi_nd Again    Ctrl-G"
        * Is there to be a recommendation for regexp
          or glob searches? (finds?)
        - Find
          * We should encourage incremental Find as in emacs 
            and in GtkTreeView.
        - Replace

2.2.3 Options
      * Pending analysis

2.2.4 Help
      * What is Ctrl-H? Nothing? Search help?

2.3 Toolbars
    * rapid? I think it is more convenient than rapid.
    * How should MDI and toolbars be handled?
    * With proper app support, it is possible to have a global
      Cut/Copy/Paste/Delete feature. Would someting like this be worthwhile?
      (I can describe how if anyone is interested. Other global
      toolbar items are possible, even without click-to-focus.)
    * Point of Pedantry: s/NB/N.B. -/
    * Too many _rows_ of toolbars consume screen space. Pre-2.0 GNOME
      allowed for multiple toolbars in a DockBand. Should this be kept?
    * The Gtk+ 2.0 Toolbar has the option for placing labels to the right
      (or left, in locale) of the toolbar icon.
    * What should be the default state of the toolbar?
      (I say, icons only.)

2.3.1 Designing Toolbar Icons
      * Stock icons are now provided by Gtk+.
        They are, of course, themable. ;-)
      * Perhaps icon size should be 4 ems?
        (2x2 tiling of em-sized squares)

2.3.2 Standard Toolbar Icons
      * It is not obvious, but it should be. The toolkit needs changes.

2.3.3 Controlling Display and Appearance of Toolbars
      * Colin seems to disagree about changing menu labels?
        But, OTOH, this would happen with the File->Close <docname>
        item.
      * I wonder if the access key for Show Toolbar should be 'h'
        To keep the same key (at least in English).
      * ASCII radio buttons should be
        ( ) if not selected or
        (x) when selected
        So they are distinct from [ ] check boxes.

2.3.4 Default Toolbar Layout - Office Applications
      * I'm not sure all these items are ever prudent.
      * I'm not sure about the order either, see LyX for example.
      * The trashcan is bad for deleting text. The icon for Clear
        is only slightly better.
2.3.5 Default Toolbar Layout - Browser Applications
      * What about applications like Amaya which combine
        browsing and editing (This was part of Tim's original plan,
        it just wasn't implemented in time to ride the Web's wave).
      * I have never found the Home item (toolbar or menu) to be useful.
      * The recommended placements are quite odd. I don't think
        I've ever seen anything like them, and would probably be
        confused or change them. Maybe the guide to ordering should be
        rethough (For either the menus or the toolbars.)
      * Should more be said about the expected behavior?

3 Dialogs
  * This really must be split. The GDP be damned,
    not every secondary window is a dialog.

3.1 General Principles
    * Not all such windows are dialog boxes.
    * I think more often secondaries complement, rather than supplement.

3.1.1 Type of Dialog Boxes
      * Note capitalisaton.
      * This section needs a reflow.

3.1.1.1 Modal and Modeless Dialog Boxes
        * There are different types of modality. Non-modal, application
          modal and system modal. It should perhaps be made clear how to
          do each of these.
          - non-modal: same as other windows
          - app modal: use another event loop (call gtk_main() again, iirc)
          - system modal: OverrideRedirect should be on. Pointer and keyboard
            input should be grabbed. See ICCCM for more detail.

3.1.1.2 Informational Dialog Boxes
        * This seems to be about alerts. When are they appropriate?
          What is appropriate when that's not satisfied?
        * No choices? What about warnings?

3.1.1.3 Druids
        * I understand we should call these wizards. I thought that was
          a Microsoft specific word. Assistants sounds much better. Druids
          gives us that yummy warm GNOMEie feeling; I feel maybe we
          should keep this.

3.1.2 Dialog Box Layout
      * GTK automatically handles changing the order per locale.
      * {action, closing, navigation, help} isn't a division, these overlap.
      * This is all quite confusing, either pick a basis or show what is
        meant by these classifications.

3.1.3 Dialog Box Behavior
      * Changes not relevant to the dialog need not ne visible in it.
      * An analysis of for what these things are is essential to getting
        instant apply vs. confirmed apply correct.

3.1.4 Dialog Box Buttons
      * Needs rewording.
      * Many of the details of geometry are handled by the toolkit.
        If we wanted people to really worry about the most basic geometry,
        we wouldn't use Gtk+, we'd use raw Xlib; from what I've seen, that
        about the level of pain when coding with MFC.

3.1.4.1 Action Buttons
        * What if cancel or the equivalent deserves the default?
          Does it ever?
        * "Yes" and "No" must be forbidden. "OK" is often most apt.
        * We still don't know what should be modal and how.

3.1.4.2 Closing Buttons
        * I program and I'm getting confused.
        * "Close" buttons should be assumed available from the
          window manager. Even when there is no window manager,
          there are other things used to close windows.
          (xkill, for example. hmm, do we want a gkill? ;-)

3.1.4.3 Navigation Buttons

3.1.4.4 Help Buttons
        * Developers should not be encouraged to provide help,
          they should be encouraged to make help unnecessary.

3.1.5 Dialog Window Titles
      * cf. ICCCM

3.2 Standard Dialogs
    * This section is almost just a description of the API.

3.2.1 File Selector
      * This basically describes the widget and little more. Provide
        3.2.1.1, 3.2.1.2, etc. (as appropriate given other reflows)
      * What happens when a document is composed of more than one file?
      * Reiteration: The _File item on the menubar looks like a verb to me.

3.2.2 Font Selector
      * "Choose" is better than "Pick" (Pick a scab?)

3.2.3 Color Selector
      * "Choose" is better than "Pick" (Ice pick?)

4 Controls
  * Language is a pain here. Sometimes a control is just a widget, sometimes
    it is something from Bonobo.
  * Form of address ("in your application") seems out of place.
  * "visual language"? ick. ick.

4.1 Buttons
    * It seems buttons _are_ (not should be) used to initiate actions.
      Is there anything else they could do?

4.2 Toggle Buttons
4.3 Check Boxes
4.4 Radio Buttons
    - The above match almost exactly the widget names.
      This could be confusing.

4.5 Option Menus
    * heh. The GDP calls these drop-down list boxes.
    * The rationale seems weak.

4.6 Combo Boxes
    * GDP calls these drop-down combination boxes.
    * "predefined values" - When? By whom?
    * If these are not editable or the required input is not readily
      apparent (heh), something else should be used.

4.7 Progress Bars
    * It seems a great disservice not to refer to the API here
      and else where.

4.8 Status Bars
    * "important" - To whom? For what? In what degree?

5 Layout
  * ". . . an aesthetically-pleasing interface is more pleasant to use."
    Removing some adjectives, a prepositional phrase, and the noun
    which is implicit in the context:
      "pleasing is pleasant"
    This seems rather obvious. :-)
    (i.e., this is a place to cut verbiage, or say, "pleasing is used")

5.1 Order and Relationships
    * The toolkit handles l10n and i18n, programs should be written to
      the POSIX locale (i.e., C).

5.2 Aesthetics
    * Size groups, a new feature, should be mentioned here.

5.3 Grouping and Separators
    * 2nd paragraph seems backwards.
      Perhaps this is a good place for an image.
 
5.4 Fonts and Text
    * Pretty much, fonts should never be chosen by the developer.
      The toolkit intentionally makes this difficult. See Pango docs
      about the mark-up language provided.
    * Relative sizes should be given, or appropriate mark-up.
    * Most backdrops et al. should be handled by themes,
      not by the developer.
    * s/username/user name/, unless a system item is meant.

5.4.1 Capitalisation

5.5 Colour and Contrast
    * Again, mostly this is handled by the toolkit.
    * I thought black text on a white background was easier to see?

6 Integrating Applications with the Desktop
  * Some parts should be elsewhere in the HIG, others should be
    in general developer documents.

6.1 Placing Entries in the Panel Menu
    * non-HIG

6.1.1 Menu Entry Icons
      * HIG, elsewhere

6.1.2 Menu Entry Captions
      * HIG, elsewhere

6.1.3 Menu Entry Tooltips
      * HIG, elsewhere

6.2 Providing a Connection between Documents and Applications
    * non-HIG

7 Mouse Interaction Basics
  * Not everyone has a mouse.      (almost everyone has a pointer)
  * Not every pointer is the same. (button arrays and number vary)
  * Not everyone is right-handed.  (my left button, your right button)
  * IBM called the buttons by number in their OS/2 User Manual.
  * The buttons are known by number in the system.
  * More often, pointers have more than three buttons and the placement
    is not predictable. X supported 5, but now supports 9 for this reason.
    It has long supported reordering and emulation.
  * My pointer is a pencil-eraser-shaped item in between the
    G-, H-, and B-keys of my QWERTY keyboard. Button1 larger than Button3
    and these are aligned vertically between my spacebar and the edge of
    the laptop nearest my body; Button1 nearest the keyboard, Button3 nearest
    the edge of the laptop.
  * A stylus device may be used. (One of the new Sonys has this, iirc.)
    Though I can only guess, I imagine that Button1 is a stylus press and
    other buttons are provided by using a button on the stylus to modify
    that press. (I've seen at least one of these.)
  * Some new Apple hardware has no apparent button; the user merely presses
    on the mouse.
  * Button1, Button2, Button3 are unambiguous.
  * Knowing the numbers makes it easier to modify their behavior
    when that is needed.

7.1 Mouse Buttons
    * see above
    * Chording may not be used. Afaik, the system doesn't support it. With my
      two-button pointer, Button1 is the big button, Button3 is the little
      button, Button2 is the both together. More importantly, it is not
      possible to tell what might be chorded.
    * Afaik, we cannot reliably detect window border size. Candidates
      for minimum size are a standard em, the stepper box (arrow button) on
      a scrollbar, the thickness of the pane divider squared.

7.2 Selection
    * Please use the gerund, "Selecting" throughout.
    * General questions:
      * Does PRIMARY support non-text data? (I'll check)
      * Should data such as a uri list be made PRIMARY when
        selected from Nautilus?
    * Selections are an important part of X. They are the simple way to
      handle IPC. The developers should be pointed to the ICCCM and 
      synopsis, with examples, should be presented.

7.2.1 Mouse and Keyboard Equivalents
      * Invert Selected Set, Keyboard action: Beats me.

7.2.2 Rubber-band Selection

7.3 Drag and Drop
    * The GDP wordlist is odd here. For "click", they mean press and release
      for "click-and-hold" they mean press and do not release.
    * What is reversed when the DnD is interclient and Edit->Undo is
      invoked?

7.3.1 Mouse Interaction with Panel Gadgets (Applets)
      * What are we calling what and where?

8 Keyboard Interaction Basics

8.1 Keyboard Navigation
    * Using tab to complete entries is expected behavior.

8.1.1 Keyboard Navigation Examples

8.1.2 Mnemonics
      * Name?

8.1.3 Standard Application Shortcuts and Mnemonics
      * "What's our view on this?"
        * F-keys suck.
      * Table 9: Add 'Search Help  Ctrl+H' ?

8.1.4 Standard Widget Navigation Shortcuts

8.1.5 Additional Widget Navigation Shortcuts
      * Havoc said the emacs-style keybindings are still present because
        they've not gotten to removing them. These conflict with other
        keybindings in use and IMO should mostly go away.

9 Simple Reality Checks

9.1 Things You Can Do Yourself

9.1.1 Before You Start

9.1.2 Keyboard Access and Focus

9.1.3 Themes/Colour/Contrast

9.1.4 Animation

9.2 Things Other People Can Help You With
    * "Things with Which Other People Can Help You"

9.2.1 Getting Early Feedback

9.2.2 Localisation/Internationalisation

10 Terminology
   * Do we need this anymore?

Cheers,
Greg Merchan