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.