RSG, draft 4
- From: Tom Vogt <tom lemuria org>
- To: gnome-gui-list gnome org
- Subject: RSG, draft 4
- Date: Fri, 7 Aug 1998 01:04:39 +0200
I just finished the 4th draft of the RSG. this is not yet the html version,
mainly it's just cleaned up, sorted a bit more clearly and structured a lot
better. it also contains an extended table of contents.
all of this has been collected from the ongoing discussions on the list,
very little is my own work, except for the selection. if I forgot something
important or messed something up - please tell me so I can correct it.
I will post this again to the list as well as put it online (later, though)
for two reasons. number one is that miguel asked for it. number two is that
I hope it helps getting the discussion focussed a bit by providing concrete
formulations to those point still a bit vague.
Rogue GNOME StyleGuide
======================
Foreword
========
This is NOT an official document, nor is it in any way related to the
official GNOME User Interface Styleguide that is being maintained by
Dan Kaminsky, Bowie J. Poag and Bill Swingle.
Table of Contents
=================
Part One - Philosophy and Backgrounds
Introduction
Heritage
Concepts
Part Two - The GNOME User Interface
Default GNOME Elements
GNOME Application Style Guide
Common Standards
Part Three - Writing GNOME Applications
Library Items
Examples and Templates
Making existing Apps compliant
Appendices
----------------------------------------
Part One
Philosophy and Backgrounds
Introduction
============
The purpose of this document is to set forth guidelines for a consistant
GNOME look and feel.
Such consistancy is necessary to help the user find his way around the
system and all compliant programs easily and without the need to relearn
basic operations. It also should help all users to use their computer with
less headaches and more productivity.
Heritage
========
(dev-note: someone volunteer to write this? :) )
Concepts
========
One of the most important issues in this respect is that the machine needs
to speak the user's language, not force him to learn artificial terms or
actions. "Intuitively" is a buzzword abused extensively by the marketing
crowd of about every other company, but there is hardly a better term to
describe what a good interface should aim at.
"Intuitively" to us means that every part of the interface has to make
sense to the user, even if it has been different on the GUI he was used
to use before moving to GNOME.
(dev-note: philosophy and intent (aka "why"s) have to fleshed out in much
greater detail!)
One term being used throughout this document is "compliant" or "compliance".
Being compliant means a program honors the guidelines contained herein and
thus "fits in" with the other GNOME applications.
We will define various levels of compliance, and will rate programs according
to these. This will help users to find consistant programs more easily and
should help programmers and designers to deal with the issues.
The levels of compliance are:
G1 - Mandatory (bare minimum)
Contains only the essential styles, so current programs can be brought
up to at least some level of compliance fast.
G1 features are considered to be of primary importance and non-compliance
will be considered a bug for GNOME applications.
G2 - Recommended (needed for a proper GNOME app)
Features and behavior needed to make an app a full-blooded
GNOME app.
Only applications meeting all of the G1 and G2 entries in this guide
should be considered "true" GNOME programs.
G3 - Suggested (should be there)
More advanced, harder-to-implement features, beyond the
call of duty, yet still within the core group of styles.
Should, but don't have to be implemented in finished programs, in no
way mandatory for development versions.
G4 - Optional (fringe feature)
"Nice to have" features that are considered useful, but may not
be appropriate for all programs and are not necessary even where
appropriate.
G5 - Under Development (cutting edge, not official style yet)
Experimental features that are not fully implemented or
supported yet.
(Will fall into other categories when fully realized)
Exceptions will of course be allowed if the application or other circumstances
require, but only then.
Applications will be rated from G1 to G3. An application will have to follow
ALL features of the relevant levels to reach compliancy. However, to reach a
level of G3+ only SOME of the G4 OR G5 features need to be used. G3+ basically
says "fully compliant and has some enhanced features".
----------------------------------------
Part Two
The GNOME User Interface
Default GNOME Elements
======================
This chapter contains suggestions to the developers of the core GNOME
applications like the panel, properties and other configuration dialogs,
help browser and many more.
We consider these applications important enough to deserve a special
treatment due to two reasons. First, they will create the first impression
a new GNOME user has. Second, all other apps will be measured by the core
applications.
2.1 THE PANEL
--------------
2.2 CONFIG DIALOGS
-------------------
2.3 HELP BROWSER
-----------------
2.4 GNOME SYSTEM UTILITIES
---------------------------
2.5 OTHERS
-----------
GNOME Application Style Guide
=============================
This chapter contains the various items of interest for GNOME applications.
They are sorted by topics and within the topics by compliance levels, i.e.
by importance.
Some of these chapters contain long and very detailed descriptions. We deem
these necessary, even though in various cases most of them never need to
trouble the developer. There is an extra item at the end of most sections
that lists the help a developer can enlist from the GNOME libraries. several
items in here have been completely taken care of for you, and you only need
to know them in full detail if you plan on coding your own implementations
instead of using the libraries.
(dev-note: the mentioned "extra item" is missing everywhere, of course :) )
3.1 GENERAL LAYOUT
-------------------
Compliance Level 2 - Recommended
--------------------------------
Dialog and other buttons in windows other than the main window should
tend to be found at the bottom and either centered or in the case of only
one button, expanded to fill the whole width of the window.
3.2 MENUS
----------
Compliance Level 1 - Mandatory
------------------------------
If an application uses a menubar, it must use the following layout:
- To the very left of the menubar is a button displaying a small version
of the GNOME foot logo. This button will be called "Program" menu in
the following.
- To the right of the Program menu, a "File" menu must be available if
appropriate to the application.
- To the right of the "File", or if it misses the "Program" menu, all
other menus follow. The suggested standard is "Edit", "View", "Options"
or menus with similiar contents, but none of these menus is mandatory
and the application might use their own special menus instead.
- The last item in the menu bar must be the "Help" menu, always called
"Help" so a user in search for help will instantly find it. The "Help"
menu is mandatory and must be there if a menubar is used.
The "Program" menu is a special GNOME menu that contains items relevant to
the application as a whole. It will be represented by a raised icon of the
GNOME footprint.
The topmost entry in the "Program" menu must always be "About...". The
last entry in the "Program" menu must be called "Exit". This item
will exit the application completely, but gracefully.
If appropriate, there must also be a "Preferences..." item in the
"Program" menu, that controls all app-wide configuration. File or
document-specific options belong into the "File" or other appropriate menu(s),
however.
The "Program" menu must be the leftmost entry on the menubar
and must be fully left justified.
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.
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...".
Menu items that contain sub-menus should indicate this with a right justified
arrow.
Menubar items and menu entries that are currently not available in the
application should appear grayed out.
All menus should contain at least one entry. In the case of user generated
lists ( bookmarks, etc. ), a grayed-out "-(No Entries)-" label should be used.
Configuration has to be in a consistant place. For items that affect the
application as a whole, this place is "Program"->Preferences. For items that
only affect the current document, this place is "File"->Configure.
(dev-note: gotta talk about "configure", maybe "preferences" or "settings"
is better?)
Compliance Level 2 - Recommended
--------------------------------
The "Help" menu must contain at least one entry called "GNOME Help", that
starts the GNOME helpbrowser with its main page.
The "About" button or menu item 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.
(dev-note: gotta discuss if "About" belongs to Program or Help. both have
arguments in their favor, but we've gotta find a solution)
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.
Compliance Level 3 - Suggested
------------------------------
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 "..."
If it seems appropriate to the specific application, the use of floatable
menubars is encouraged.
Compliance Level 5 - Under Development
--------------------------------------
G5 - [Pie Menus]
3.3 TOOLBAR
------------
Compliance Level 2 - Recommended
--------------------------------
If a toolbar is used, it must be user-configurable in the
"Program->Preferences..." dialog whether it will display only text, only
icons or both.
3.4 DIALOGS
------------
Compliance Level 1 - Mandatory
------------------------------
All dialogs should have at least one button to close the dialog. This button
should be labeled "Close", "Cancel", "OK", or "Apply.".
A label of "Close" is strongly encouraged (G3 for this last sentence)
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.
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.
Compliance Level 2 - Recommended
--------------------------------
"Dialogs" that only display information with no user interaction should have
only a single button labeled "Close".
Modal dialogs should be avoided wherever possible.
The default highlighted button for a dialog should be the safest for the user.
(but see further down in G4)
All dialogs should default to a size large enough to display all of the
information in the dialog without making a resize necessary.
All dialogs should set the titlebar with an appropriate string.
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.
Compliance Level 3 - Suggested
------------------------------
If you have a situation where a dialog might spawn another dialog please
consider using a notebook instead.
Compliance Level 4 - Optional
-----------------------------
The default selection should be user-customizable, using a checkbox in the
dialog itself, very much like the common "don't show this popup again"
checkboxes.
3.5 KEYBINDINGS
----------------
Compliance Level 1 - Mandatory
------------------------------
All menu items, menubars, dialogs and notebooks should be navigable using
the keyboard.
Menu items that have bindings should list them right justified of the menu
item label.
Applications should not allow users to change the default bindings for common
operations.
Compliance Level 2 - Recommended
--------------------------------
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 ("themes") and still maintain consistency across
applications.
3.6 PROGRESS BAR
-----------------
Note: "Lengthy" is a vague term. It was included to avoid the
misinterpretation that a 10ms loop must show a progress bar.
Compliance Level 1 - Mandatory
------------------------------
All lengthy 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.
Where possible, all operations that use a progress bar should have a cancel
button as well.
Compliance Level 2 - Recommended
--------------------------------
All lengthy 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.
Operations where a cancel button would be harmful to the application or
user data should use a confirmation dialog.
Compliance Level 3 - Suggested
------------------------------
Progress bars can be either set into the application panel or create their
own dialog, depending on the individual design of the application.
3.7 NAVIGATION
---------------
Compliance Level 1 - Mandatory
------------------------------
All functions of the application should be available through the default
user interface.
If the "Exit" menu entry or button is used or a destroy event is emitted
(a SIGINT or SIGTERM signal is received), and the user has unsaved
information, the application must pop up a modal dialog to ask the user
if they are sure they want to exit the application without saving and
if not, give them a chance to save before exiting.
(dev-note: what about SIGHUP?)
Compliance Level 3 - Suggested
------------------------------
Document based applications should contain a "Open Recent >" entry in
the "File" menu that opens another menu with the recently accessed
documents. selecting one of those has to load it as if it would have
been selected using the normal "Open..." operation.
3.8 LOOK & FEEL
----------------
3.9 COMMUNICATION
------------------
Compliance Level 2 - Recommended
--------------------------------
[Session Management]
Compliance Level 3 - Suggested
------------------------------
[Which CORBA interfaces should be implemented]
[MWM Hints]
Compliance Level 5 - Under Development
--------------------------------------
[GNOME WM Hints] (G3 when fully supported)
3.10 THEMES
------------
Compliance Level 5 - Under Development
--------------------------------------
[Color-reactiveness]
[Appearance Guidelines (Graphics, etc.)]
[Sound Guidelines]
3.11 APPLICATIONS
-----------------
Compliance Level 2 - Recommended
--------------------------------
Applications should have an entry in the GNOME application repository
[Session Management]
Compliance Level 3 - Suggested
------------------------------
[Drag & Drop]
GNOME-compliant programs should test for a GNOME-environment at startup.
if no GNOME can be found, but the program can still run, it should display a
dialog (with "don't show this again" button) that tells the user that it may
lose some functionality.
Compliance Level 5 - Under Development
--------------------------------------
[Document-Object compliance] (G3 when fully supported)
3.12 APPLETS
-------------
Compliance Level 3 - Suggested
------------------------------
[Minimum CORBA interface]
3.13 DOCUMENTATION
-------------------
Compliance Level 2 - Recommended
--------------------------------
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.
Compliance Level 5 - Under Development
--------------------------------------
[Screenplays] (optional, may NOT replace the normal documentation,
and all information of a screenplay must be available as text somewhere)
3.14 DISTRIBUTION
------------------
G3 - Licensing under the GNU public license or Library GNU public
license (as appropriate) is strongly encouraged.
Common Standards
================
(dev-note: elaborte somewhat about common standars and why we used or
dumped them.)
----------------------------------------
Part Three
Writing GNOME Programs
This chapter contains guidelines, pointers to the used GNOME-library
functions and other help to make the life of GNOME coders easier. Also
contained are several examples, templates and the skeleton of a fully
GNOME compliant "Hello World" application that can be used as a good
starting point for other programs.
In addition, a couple of references will be made to help implementing
G1-G5 features using the GNOME libraries. (GNOME_about widget and more)
(dev-note: not much here currently. should we go and start or wait until
things are fleshed out and library functionality is available? do we
define that functionality or leave it to the developers?)
----------------------------------------
Appendices
A1 - Alternative Ideas
----------------------
A place to collect ideas that didn't make it into the body of the document,
but still MIGHT be of interest. Archived in case they get a revival. Also a
store for alternative ways to do things that didn't fit in with the overall
concept, but might if that gets changed.
"Program" Menu - Record Option
---------------------------
Idea: Implement one "record" and one "playback" button in the "Program" menu,
allowing for simple macros and easy screenplays, utilizing XLab.
Problems: xlab only plays back, it will break for the most simple things,
like different window sizes, toolbar-icons instead of toolbar-text (will
change the window layout), maybe even different languages (different length
of menu titles).
Menu Restructuring
------------------
Idea: Right-click in app window opens menubar as in gimp. user-option to
leave the old menubar in place or disable it.
Two things against this otherwise nice idea. One is it's unusual and new
users will need some time to relearn (took me some in gimp). Two is that it
will take right-click away from the app.
Fleshing out of this idea:
----->
I think we can expand this idea. (In other words, I like it.)
How about this:
By default, you have a menu bar. So... It'd look like this:
|| 8' File Edit Options Appearance Help
Under Appearance (or View) you can turn off the menubar. Doing
this EXPANDS the root menu. (Which resides on button 3 of the mouse.) So
any context sensitive menu will be added to. Example:
,---------------. <- If this bar is selected, the menu is "pinned."
|---------------|
| * Spell Check | <- The old context sensitive menu. (Which will
|---------------| be displayed even if the menubar is visible.)
| * Cut |
| * Copy |
| * Paste |
|---------------|
| * About ... | <- The contents of the "Gnome" Menu are placed
| * Quit | IN the popup menu. This gives common commands.
|---------------|
| * File > | <- The menu is placed at the bottom.
| * Edit > |
| * Options > |
| * Appearance> |
| * Help > |
`---------------'
Things to notice: I'm a big fan of pinnable menus. If it can't
be pinned, I'm not interested in it. Also, the Gnome menu is expanded
into the popup menu. This avoids problems with applications like ee which
don't have a nice way to quit. (Get the popup, go to File, go down to
quit. Yech. Sorry Raster.)
As a side note, we should look at transparent windows. This is
where the menu is slightly translucent. Research by Alias
(http://www.alias.com) says this is very helpful for users.
-Ben
<-----
Menu Structure configurable
---------------------------
Idea: The menus should be configurable on both admin and user level, so e.g.
an admin can disable certain features by making the menu item inaccessible.
(note: goes deeper than that! disabling edit->cut doesn't do a thing if ctrl-x
is still available!)
Recent Documents
----------------
Original Idea: use four entries, gray them out if they're not used.
Theme-able Menus
----------------
[...write this later...]
File-Menu Rename
----------------
Idea: Rename the "File" menu to something more appropriate for the app.
currently in heavy discussion. is inconsistant but makes more sense,
especially for moving away from a file-centric ui. waiting to see what
the discussion results in.
A2 - External Resources
-----------------------
(dev-note: quite a lot, gotta take the time to sort and do a clean
bibliography here.)
--
Those who do not understand Unix are condemned to reinvent it, poorly.
-- Henry Spencer
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
