The ST/X Style Guide

Introduction
General Look
Window (PullDown-) Menus
- Menu Items
- Menu Labels

Introduction

One of the most annoying defects of many programming systems is inconsistency in its user interface.
This document is meant to provide some rules which may help to avoid this in the future of ST/X development.

We are awareof the fact that this document is neither complete (feedback welcome) and the current ST/X system itself does not yet completely follow the rules as stated below - we are still working on it and fix the GUI as we come along.

General Look

Layout

If you ever plan to provide national variants of your program, or want to allow the user to add translations himself, leave enough space for longer texts in buttons, labels etc.
I.e. always provide somewhat more space for your widgets.
From our experience, national variants sometimes require more than twice the amount of real estate.

Messages

When creating longer texts from fragments, be prepared that sentences are have different structure in different languages; NEVER construct by concatenating individually translated strings.
The following is an example for VERY BAD coding style:

    Dialog
	information:(resources string:'Cannot read: ') , filename.

The reason for this to be so bad is that in many languages, the sentence must be written in another order; for example, in German, you would write:

    <filename> kann nicht gelesen werden

This germanstring cannot be constructed from the above english template by simple text-translation.

Therefore, the above code should be written as:

    Dialog
	information:(resources string:'Cannot read %1' with:filename).

and a translation for German could be given (in a resource file) as:

    'Cannot read %1'        '%1 kann nicht gelesen werden'

Colors

Do not hard-code (i.e. program) any color information into applications.

Widget Colors

Use the default colors as provided by the widgets - do not override them programatically.

If you really want (or think you need) to add fancy colors, do so via the resource and/or styleSheet mechanism, which is user-configurable.

Alert Colors

Think twice about using alarm colors (such as red) in your application.
When overused, these loose their alarming effect and you loose the ability to inform the user about real trouble.

Sound and Beeps

Do not (over-)use sound effects or beeps.

Just think about an office full of terminals which constantly emit awful win2000 startup melodies - if at all, allow the user to turn these sounds off or let her configure individual acoustic alarms.

Window (PullDown-) Menus

Window Menu: Every topView should have a window- (pullDown-) menu.

Menu Items

Exit Item

The menu should have an exit item somewhere - preferably in the leftMost submenu, which is usually the "file" menu.

Although most windowing systems do provide a close function in their window decoration, some (especially older, puristic ones like twm) do not.
Also, some window managers close function is actually a "kill" function, in that it kills the whole application (i.e. the whole smalltalk) instead of asking it to close that individual window.

By always providing an exit menu item, these problems can be avoided.

Help Menu

The menu should have a "help" submenu. This submenu should have (at least) an item which leads to a general tool document - preferrably a hypertext document (html, pdf or similar).

Visible vs. Disabled

All items should be visible. Items which are inappropriate for the tools state (for example: nothing selected) should be disabled instead. Disabled items are typically shown in a grey color.

The problem with invisible items is that a newcomer (and often even experts) will have a hard time to learn about the functionality which is offered by a tools menu, if the set of items changes with the state of the tool.
New users typically try all menus to see which functions are provided by which menu and will have a longer learning curve, if some items are invisible.

Menu Labels

Use the so called "headline capitalization" for english menu item labels - that is:

capitalize the first word.
capitalize all nouns, verbs, adjectives and adverbs.
do not use punctuation (i.e. no period at the end).
mark items which ask for more information by opening a dialog or confirmer, by a trailing "...".

Notice that in many other languages, this kind of capitalization is NOT used and actually looks ugly.
For example, in German, the normal sentence capitalization rules apply (i.e. capitalize the first word, then only capitalize nouns).

Menu Items

Do not make menus too big - if you need more than (say) 10 items, create submenus.
Group items by function and keep the ordering of groups consistent among different applications.

<cg at exept.de>

Doc $Revision: 1.7 $ $Date: 2021/03/13 18:24:52 $

The ST/X Style Guide

Contents