4.3	Configuration files

Most QNX Windows resources can be defined by files in a 'windows' subdirec-
tory under the user's login directory or in /windows/config (see section 4.1). 
The user's directory is always searched first. All configuration files are text
files and can be created by any text editor.

Each file contains a number of options, one option per line, in the following 
format:

    command  arg1,  arg2  ...

That is, a command, starting in the left column, followed by zero or more 
arguments, separated by spaces or tabs. Arguments are separated by commas.

Configuration files can be customized for a specific node by appending the 
node number to the file name. In the absence of a node-specific file, the 
'generic' configuration is used by default. For example, "screen.cfg2" will be 
executed when a windows server is started on node 2. If screen.cfg2 is not 
found, then screen.cfg (if it exists) is used.

For example, the "screen.cfg" file may contain:

    "test configuration:

    name      screen1

    button    O=Nm, f=B

    start     /my_project/test



This example names the server, redefines the default button format and starts 
a test program. ('test' is automatically executed as an independent process.) 
Any line that begins with a double quotation mark or '#' is considered to be a 
comment and is ignored.

Only one screen.cfg file is processed when the server is started. The commands 
that may be placed in the file are listed on the following pages.


AREA
----
Reserves an area of the screen for application-drawn buttons, etc. (see Picture-
Current). All windows are restricted to the area below the given row and to the 
right of the given column, i.e., they are offset by these coordinates:

    area  row,column


BACKGROUND
----------
Specifies the screen's background color and pattern, by number (see 'Colors' 
and 'Patterns' in chapter 6, and the 'color' command below):

    bkgd  color,pattern


BUTTONS
-------
Defines the format of 'standard' buttons. The command's syntax is:

    button  C=n,E=n,F=n,P=n,O=s,R=n,f=s,o=n,S=n

The arguments consist of a series of assignments of the form "param-
eter=value", where the parameter is a single character and the value is a 
number (C=3) or a string (O=Sem). The parameters are:
C (label color), E (edge color), F (fill color), P (pattern), O (options),
R (roundness), f (format), o (outline color), S (font size).
See DrawButton and SetButton in chapter 6 for further information.

For example, the command on the previous page defines square-cornered 3D 
buttons.

Note that this applies only to buttons drawn with the default format or the 'S'
format. It works best if WINDOW_BUTTON, WINDOW_COL and 
WINDOW_SPACING are used to draw the buttonssee 'Constants, typedefs 
and global variables' in chapter 6.


COLORS
------
Defines the color palette for the server. Each color command specifies a color 
number ('n') and the mix of primary colors of which it consists ('r', 'g' and
'b'-red, green and blue). An optional 'name' can also be assigned to the
resulting color, to allow applications to reference colors symbolically rather
than by  number. Note that the color number is limited by the device and
graphics driver on the server's node.

    color  n,r,g,b name

A complete set of colors may also be loaded by specifying a file name:

    color  @file_name

The file contains one text line per color. Each line looks like this:

    color_name  r  g  b  color_number

The fields are separated by blanks or tabs. The colors must be ordered by 
color_number (increasing). A line beginning with a double quotation mark or 
'#' is treated as a comment.

(Note that QNX Windows will always load a color file named "colors.cfg" if it 
is found in the local 'windows' subdirectory or in /windows/config. A node 
number may be appended to the file name, e.g. "colors.cfg5".)


CURSORS
-------
Defines the default colors for the global screen cursor (normal and large sizes):

    cursor  color,large


DIALOG
------
Defines the default colors for dialog window frames, window text (titles and 
messages), the pane background and the title bar's background when 
'depressed':

    dialog  frame,text,bkgd,bar,nest,picture

'nest' and 'picture' redefine the prefix characters used for nested dialog and 
references to picture files (normally ('@' and '$').


FILL
----
Defines the pattern and/or color for the interior of text buttons which are in 
the 'set' (depressed) state. The patterns and fill colors are defined in up to
three pairs, for the default 'set' state, for the 'dim' option, and for the
'bright' option, respectively:

    fill  set_pat,set_fill,dim_pat,dim_fill,bright_pat,bright_fill


FONTS
-----
Defines the default system fonts ((if supported by the graphics driver):

    font  type=name,size

'type =', 'size' and 'style' are optional; 'size' is the font height, in tips; 
'type' may be one of the following:

button     the default font for all 'standard' buttons

dialog     the default font for all dialog text

help       the font for help text (overrides 'dialog', above)

label      the font for attached labels

menu       the font for menu items (overrides 'dialog', above)

notice     the font for notice text (overrides 'dialog', above)

picture    the default font for text elements in pictures

small      the font for 'small' attached labels

system     the font for all text (default if 'type' is omitted)

title      the font for window titles (overrides 'window')

window     the font for window titles and staus/mode messages

'style' may be one of: "B" (bold), "I" (italic) or "BI" ( bold and italic).


ELEMENT
-------
Defines the default colors for element shadows, edges (when the element is 
'enclosed') and labels:

    element  shadow,edge,label


ICON
----
Defines the default colors for icon labels and background fill:

    icon  label,label_bkgd,icon_bkgd


LIST ITEMS
----------
Defines the color of the text,  the pattern and color of the fill for modelled
text items, and the outline color for unmodelled items, for standard 'list'
groups (see DrawGroup). The first four parameters apply to the item's 'normal'
state, while the second four are used for the 'set' state:

    list  color,pat,fill,edge,set_color,set_pat,set_fill,set_edge


MESSAGES
--------
Defines the title and text of messages displayed by the server on the console or 
in notice windows:

    message  type=title;text

'type' may be one of:

number_format   "invalid character typed" message when editing a number

number_range    "value out of range" message when editing a number

shutdown        the "system shutdown in progress" message

For example,

    message  number_range=Range Error;That number is too big!

The title is optional (omit the semicolon separator as well).


MNEMONIC
--------
Defines the default colors in menus, buttons, etc., when highlighted (if
applicablesee 'ScreenOptions' in chapter 6):

    mnemonic  color


MOUSE
-----
Controls the mouse's responsiveness ('gain' and 'threshold'), the time interval
which must elapse before a button is considered to be held down, the interval 
within which a doible-click is recognized, the delay before auto-repeating a 
button, and the auto-repeat interval (all times are in tenths of a second):

    mouse  gain,threshold,hold,double-click,delay,repeat


NAME
----
The 'name' command assigns a string to the server which is executing the 
configuration file. The name can be used in the GraphicsOpen function and is 
returned by ScreenInfo. For example,

    name  DevOne

The name may be a maximum of QW_MAX_NAME_LEN (31) characters 
long in QNX 4.0 and eight characters in QNX 2.15. It must consist solely of 
alphabetic characters and/or digits.

Under QNX 4, the name must be preceded by '/' to be accessible across the
network.


OPTIONS
-------
Initial screen options can be specified. The argument is a single string of 
option characters, as defined for the ScreenOptions function (q.v.). For 
example,

    options  -SL

turns off the 'sleep' capability (which allows user to switch out of windows
into text mode) and enables large cursors.

Options:

1       treat all pointing devices as having a single button, i.e., treat all
        button inputs as 'select/menu'

A       use alternate set of glyphs

c       draw resize handles in the corners  of windows (default)

C       display a cursor (default)

d       drag windows by their title bar only

D       dim scroll bars when the picture fits in the view (default)

e       select the element under the cursor (if any) as a side-effect when an 
        inactive window is selected; i.e., allow a window and an element to be 
        selected simultaneously (default)

E       resize windows by dragging their edges

f       make a window's parent active when the window is closed (default)

F       treat all parent child hierarchies as 'families' (see WindowOpen)

g(s)    focus options (for dual-monitor nodes); s is a combination of the 
        following characters:

        k   transfer keyboard control when the focus is switched (default)

        m   transfer mouse control when the focus is switched (default)

        s   make a sound when the focus is switched

h(s)    help options; s is a combination of the following characters:

        a   send all elements (not just 'selectable' elements) in events

        A   send the tag of the selected element, if any, in the event 
            (otherwise, send the tag of the element under the cursor)

        ('h' by itself sets/clears all sub-options)

i       inherit the message sender's (application's) priority (default)

I       re-use vacated  icon slots (default)

j       the cursor moves automatically ('jumps') when selecting in a scroll 
        bar (default)


J       the cursor moves to the default element (if any) when a window is 
        opened (default)

K       allow system keyboard shortcuts (default)

l       modify input for left-handed users: swap 'select' and 'menu' mouse 
        buttons

L       display all cursors larger than normal (approx. 400%)

m       highlight the mnemonic character in buttons and text elements

M       jump the cursor to the first/default elment in a menu when it is 
        opened (default)

o(s)    optimization options; s is a combination of the following characters:

        d   draws and redraws

        i   images (caching color palettes, etc.)

        s   tag searches (see P{icture 's' option)

        w   window closes (saves and restores the screen image under the 
            window; not recommended for VGA displays)

        ('o' by itself sets/clears all sub-options; optimization generally
        requires substantial dynamic RAM)

O       keep menus completely on the  screen, if possible (default)

P       jump the cursor to a window's pin when the window is opened 
        (default; requires 'J')

Q       end editing when another area is selected (default)

R       display an element's mnemonic character at its right edge (if it fits)

s       enable context-sensitive cursors (for dragging, etc.)

S       allow the screen to 'sleep' (default)

T(s)    define the text-editing caret; 'T' is followed by a string in brackets, 
        consisting of the following characters:

        l   vertical line between characters

        L   larger-than-normal caret (the normal caret is a small triangle drawn at
            the text's baseline)

u       underline the mnemonic character in buttons and text elements

V       automatically load missing fonts referenced by elements (default)

W       allow switching between windows via the numeric keypad '5' key 
        (default)

z       display all dialogs in 'compact' format, if possible

Z       scroll by shifting pixels (default, if supported by the driver)

$       move windows by shifting pixels, rather than by redrawing their 
        contents (if supported by the graphics hardware and driver)


PAUSE
-----
Introduces a delay (in seconds) in the file processing, primarily to spread out
process creations (i.e., 'start' commands):

    pause  n


PICTURE
-------
Defines the default color and pattern for picture backgrounds:

    picture  color,pattern


PORTS (QNX2 only)
-----
Defines the range of ports that can be used by the server and applications 
which connect to it:

    ports  n,m


SCREEN
------
Defines the default light and dark colors for 3D modelling:

    screen  highlight,modelling


SOUND
-----
Defines a tone which is generated (asynchronously) when an object is selected; 
the duration is in milliseconds:

    sound  frequency,duration


START
-----
Any number of processes can be executed at the same time as the windows 
server is started. The command is followed by the name of the executable file, 
and optionally followed by arguments to the process; in other words, a QNX 
command-line:

    start  pathname args

Typically, the first process started is a shell or 'workspace manager', for 
example, /windows/apps/Olwm/olwm.


TEXT
----
Defines the default colors for the editing caret and selected text:

    text  caret,selection


TIMER
-----
Sets the amount of time (in seconds) without input activity before triggering 
a time-out event (e.g., for a screen-saver):

    timer  input


WINDOW
------
Defines the default colors for standard (non-dialog) windows:

    window  frame,text,shadow,label,outline,pane,bar,bkgd

The text color applies to the windows's title and footer messages (see 
WindowMsg). outline refers to a 2D (unmodelled) window's outline, while 
pane refers to a 2D pane's outline. bar defines the title bar's background when 
'depressed'. label and bkgd refer to the icon's background fill and the icon 
label's background, respectively. (see also 'icon', above)

