Proposal for First Draft of GNOME Style Guide 1.1

[John R Sheets <dusk smsi-roman com>]

Here's one way to do it!

I threw these ideas together pretty fast (in a couple afternoons)
using ideas from myself and from the list, and from recent
conversations with Maciej Stachowiak, so they're far, far from
being perfect.  (c:  Most of the meat here is pasted directly
from the existing style guide, albeit reorganized to meet the new
structure.  Also included are some suggestions on ratings for
different levels of compliance.  (I took the liberty of making a
quick hell-in-a-bucket first pass at ranking each item...these
will no doubt change as the guide goes through the mill -- grind,
grind, grind.)

Let me know what you think!

John

---------------
Levels of Compliance

C1 - Mandatory (bare minimum)
     Only the essential styles, to allow quicker GNOME
     compliance for new apps.

C2 - Recommended (needed for a proper GNOME app)
     Features and behavior needed to make an app a full-blooded
     GNOME app.  (Only C2+ apps allowed in GNOME distribution?)

C3 - Suggested (should be there)
     More advanced, harder-to-implement features, beyond the
     call of duty, yet still within the core group of styles.

C4 - Optional (fringe feature)
     The more controversial features that haven't been accepted
by the
     community as a whole, but are fully implemented & stable.

C5 - Under Development (cutting edge, not official style yet)
     Experimental features that are not fully implemented or
     supported yet.  (Will fall into C4 or C3 when fully
realized)

---------------
Universal Guidelines

1.1  MENUS
C1 -  If an application uses a menubar, it must contain at least
two entries: "File" and "Help". In the event that "File" is not
appropriate, another label may be used in its place. In the
remainder of this document, this menubar entry will always be
referred to as the "File" entry.

C1 -  If a menubar is not present in an application, two buttons
must be present somewhere labeled "Help" and "Exit". If the help
for that application does not contain "About" information ( see
below ) then an additional "About" button must also be provided.

C1 - The last entry in the "File" menu must be called "Exit".
This button will exit the application completely.

C1 - The "File" menu must be the leftmost entry on the menubar
and must be fully left justified.

C1 - Menu items that open dialogs or require additional user
information should indicate it with a "..."  after the label. For
example, the "About" menu entry in the "Help" menu should
actually look like "About...".

C1 -  Menu items that contain sub-menus should indicate this with
a right justified arrow.

C1 -  Menubar items and menu entries that are currently not
available in the application should appear grayed out.

C2 - The "Help" menu must contain at least one entry called
"About".

C1 - All menus should contain at least one entry, except for user
generated lists ( bookmarks, etc. ) which may initially contain
no items.

1.2  DIALOGS
C1 - All dialogs should have at least one button that is labeled
"Close", "Cancel", "OK", or "Apply."

C2 - Modal dialogs should be avoided wherever possible.

C2 - The default highlighted button for a dialog should be the
safest for the user.

C2 - All dialogs should default to a size large enough to display
all of the information in the dialog without making a resize
necessary.

C2 - All dialogs should set the titlebar with an appropriate
string.

C2 - A dialog which consists of a single entry box shall have its
OK button be the default (which is to say that enter shall accept
the entry), and the escape key shall be bound to the Cancel
button.

C1 - In a dialog the "OK" or "Apply" button should not be
highlighted until the user has made a change to the configurable
data in the dialog.

C1 - If a dialog contains more than one button for the
destruction of that dialog, ( for example, an "OK" and a "Cancel"
), the affirmative button should always fall to the left of the
negative.

1.3  KEYBINDINGS
C1 - All menu items, menubars, dialogs and notebooks should be
navigable from the keyboard.

C1 - Menu items that have bindings should list them right
justified of the menu item label.

1.4  PROGRESS BAR
C2 - All operations that have a deterministic time to completion
in which no other obvious application activity would normally be
taking place should indicate progress using a progress bar. This
progress bar should begin its activity at the beginning of the
operation.

C1 - Where possible, all operations that use a progress bar
should have a cancel button as well.

C2 - Operations where a cancel button would be harmful to the
application or user data should use a confirmation dialog.

1.5  NAVIGATION
C?  - ???

---------------
GNOME Guidelines

2.1  MENUS
C2 - The "About" button will display a dialog with information
containing at least the name and email address of the author,
copyright information, version, and a link to the application
repository information. Please use the gnome_about widget.

C3 - If the "File" menu contains a "New" menu entry, it should
indicate what you will be creating. For example, if the
application creates a new word processing document, it should say
"New Document" instead of just "New". If the application is able
to create more than one type of resource, it should indicate that
it will create a dialog with a "..."

C3 -  If it seems appropriate to the specific application, the
use of floatable menubars is encouraged.

C2 - All menu items that have a corresponding button elsewhere in
the application that uses an icon should also contain the same
icon. The icon should be scaled to the proper menu size and be
left justified in front of the label on the menu.

C4 - [Pie Menus]

2.2  DIALOGS
C3 - If you have a situation where a dialog might spawn another
dialog please consider using a notebook instead.

2.3  KEYBINDINGS
C2 - All applications that have common operations should use the
binding interface that is outlined in the gnome key binding
standard. Using the interface outlined in this standard will
allow users to define  their own set of favorite key bindings and
still maintain consistency across applications.

C1 - Applications should not allow users to change the default
bindings for common operations.

2.4  PROGRESS BAR
C3 - Progress bars can be either set into the application panel
or create their own dialog, depending on the individual design of
the application.

C2 - All operations that do not have a deterministic time to
completion should indicate progress using a dialog that contains
either an animated icon or changing number to indicate progress.

2.5  NAVIGATION
C1 - All functions of the application should be available through
the default user interface.

C1 - If the "Exit" menu entry or button is used or a destroy
event is emitted, and the user has unsaved information, the
application should pop up a modal dialog to ask the user if they
are sure they want to exit the application without saving.

C3 - Document based applications should contain four menu entries
in the "File" menu for the last four documents opened. In the
event that there haven't been four documents accessed, entries
that have not been filled should be grayed out.

2.6  LOOK & FEEL
C1 - [Use GTK+ widgets]

2.7  COMMUNICATION
C3 - [Which CORBA interfaces should be implemented]

C5 - [WM Hints]  (C3 when fully supported)

2.8  THEMES
C3 - [Color-reactiveness]

C? - [Appearance Guidelines (Graphics, etc.)]

C? - [Sound Guidelines]

2.9  APPLICATIONS
C2 - Applications should have an entry in the gnome application
repository

C2 - [Session Management]

C3 - [Drag & Drop]

C5 - [Document-Object compliance] (C3 when fully supported)

2.10  APPLETS
C3 - [Minimum CORBA interface]

2.11  DOCUMENTATION
C2 - Documentation for the application should be written using
DocBook. DocBook supports generation of many document formats
including HTML and PostScript. For an introduction in using
DocBook, please see the DocBook tutorial.

2.12  DISTRIBUTION
C2 - Licensing under the GNU public license is strongly
encouraged.