application_style_guide
Application Program Style Guide
1) The program title should be on line 1 following the page number.
2) An interrupt on the title line (line 1) should copy the
application image to the slot 1 graphic window.
(see 'window_screen_copy_init_c' in ul_windowlib)
3) A "Pgm_Tools" menu should be included and placed in the upper
right hand corner of the display. (see 'utility_window_init(_c)')
4) Error messages should appear in an error message window which
is located at the bottom of the display and which spans the
entire width of the display. Messages should be logged at least
in the console log and optionally in a program log.
(see 'error_init(_c)')
5) Multiple window applications should include a menu bar on
line 2 or 3 which allows for opening and closing the various
windows. The text in the menu bar for a given window should be
all upper case if the window is open and all lower case if the
window is closed. (see 'menu_bar_create' and
'window_menu_bar_create_c')
6) Interrupts should be acknowledged by the program (some examples
are: a color change or a flash in the interrupt field). Long
calculations (>5 seconds) should indicate such with some sort of
heartbeat.
7) Interrupts should be recognized anywhere within the field
(preferable to a single character/symbol). Fields can be
delineated by diamonds, angle brackets (<>), square brackets ([]),
or a different background color. Yellow diamonds should be used
to designate a field which will result in the opening of a menu
or other window.
8) When interpreting an input field, it is best to read the entire
field regardless of the present cursor position.
9) For input fields which are also being updated by the program,
updates should be suspended while the cursor is in the input field.
10) Displayed status should reflect the current condition, not what
the status will be if the field is activated.
11) Use circular save files if possible. Otherwise, allow the user
to select the file to save and to enter a description. A
"caution" is not necessary if the latter paradigm is used, but
should be utilized for the former.
12) Use a 'decide' dialog as protection for potentially destructive
interrupts. Use positive logic. (e.g. decide box should ask
the question "Continue?" as opposed to "Stop?". When asked to
Continue, an "OK" will indeed continue, and a "Cancel" will stop
program flow.) If the choice being made is a particularly
dangerous one, make the cursor default to the "Cancel" position.
(see 'decide(_c)')
13) Simply entering the program should not result in a lengthy
initialization or the capturing/modifying of adjacent resources
(eg. SA windows).
14) Delineate circular selection fields with "-< >+". If user types
in a selection, check for valid entry, and display a menu of
valid choices if it is not. (use the 'select_field' routines)
(see 'select_field_register_c' and 'select_field_init_c')
15) Make sure that colors contrast so that text can be easily read.
Also, check a hard copy of the image to make sure it's readable.
Don't use red or magenta as a background color since the cursor
will "disappear" when placed in that field.
16) Color standards:
Red -> bad, false, not normal text color
(eg. a power supply is on when it should be off)
Green -> good, true, normal (eg. power supply is on and it
should be on) or active interrupt field
Yellow -> transitional, maybe, caution (eg. device remotely
turned on, waiting for response), window titles,
popup window interrupt field delimiters
White -> don't care, masked (eq. power supply is on or off,
don't care) (also used for static text)
Magenta -> strange unrecognized status, extreme situation,
or setpoint
Cyan -> static text
Blue -> window borders, disabled selection fields
17) The programmer should provide a basic overview on the use of
the application in the online help. An "abstract" document
should also exist.
18) Make appropriate use of bubble help as well as context
sensitive help. (see 'window_create_help_field_c'
(in ul_windowlib) and 'bubble_help_callback_init_c' and
'help_callback_init_c')
19) When reasonable, allow the user to view and/or restore to an
initial setting by a simple interrupt.
20) Keep interrupts to a minimum. Commonly used functions should
be on the root window or in the "Pgm_Tools" menu.
21) Be judicious about program control of the cursor position.
22) Insure adequate handling of multiple users. Avoid single-user
programming if at all possible.
23) Provide the user with choices for spawned activities.
(e.g. start up Secondary Applications on either GxSA or GxSB)
24) Place a return button on the border for subpages/windows or
support closing windows when interrupting outside of them.
25) It is desirable to create a tutorial script which exhibits the
basic functions of the program.
26) If an invalid value has been typed into an input field, do not
erase it. Leave it there in red so that the user can edit it.
27) Fields that accept/display array device names should display
those names in the standard format. The CLIB routine
'dio_parse_long_device_name_c' should be used to parse these
names.
28) Device name input fields should always accept a semicolon as
well as a colon for the second character.
29) Avoid creating overly large application windows which consume
too much of the available display.
30) Make TV windows movable whenever possible to allow the user to
configure the display as desired.
31) Do not use the Primary Application Touch Panel window for
any reason.
32) Make appropriate use of application specific error codes through
the use of the application error code facility to represent
errors determined directly by the application program. Make sure
to provide adequate descriptive text for these errors. Do not
use application specific errors to simply mask error codes
returned by a system service.