           Default Buttons
           ---------------

Default buttons can be selected by clicking
on them with the mouse or by typeing the "return"
key (type the "space bar" on systems with OS/2).
They appear the same as regular buttons, but with
a thicker black border.   There should only be one
default button per dialog, and only dialog boxes
with keyboard focus will accept "return" key input.
Buttons labelled "OK" or "CANCEL" are commonly 
made to be the default.

No programming is required to make a default 
button.  This can be done within SIMDRAW using
the "button detail" dialog when editing your
dialog box.  Notice that the "Quit" button for
this program is a default button.  Striking
the "return" key when its dialog has input 
focus will terminate this program. 


      Dialog Positioning and Alignment
      --------------------------------

The position of a dialog box on the screen is no
longer restricted to the center of the window.
A dialog box can be placed anywhere on the screen
relative to any one of the four screen corners.

The "DDVAL.A" attribute of the dialog form pointer
specifies which corner of the screen the dialog is 
positioned with respect to.  This position is the 
offset to the SAME corner of the dialog box.  DDVAL.A
can be set to one of the following 5 values:

0 -> Position ignored.  Dialog box will be centered
within the window.  This is the default alighnment.

1 -> Bottom left.  The position is the translation of 
the lower left corner of the dialog box from the
lower left corner of the screen.

2 -> Bottom right.  The position is the translation of 
the lower right corner of the dialog box from the
lower right corner of the screen.

3 -> Top left.  The position is the translation of 
the upper left corner of the dialog box from the
upper left corner of the screen.

4 -> Top right.  The position is the translation of 
the upper right corner of the dialog box from the
upper right corner of the screen.

Setting the position of the dialog is performed 
using the LOCATION.A attribute of the dialog's
form pointer.  The coordinate system under which
the position is specified has (0,0) at the screen
corner described by the alignment field, and 
(32786, 32768) at the opposite corner.  Since the 
LOCATION.A call will re-display the dialog box, the
alignment fields (DDVAL.A) should be set up first.
The following code sets dialog position and 
alignment:

let DDVAL.A(FORM.PTR) = 1   
   '' for lower left corner alignment
let LOCATION.A(FORM.PTR) = LOCATION.F(8192, 8192)  
   '' 25% of the screen width and height
call ACCEPT.F(FORM.PTR, 0)
   '' interact with the form


    Using the System File Dialog Box
    --------------------------------

Most toolkits are equiped with a standard dialog box 
which enables a user to easily browse through the 
file system.  SIMGRAPHICS II now interfaces with 
these "system" dialog boxes.  A file dialog can be
used to either find an existing file, or allow the
user to select a directory and name for a non-
existing file.  They also have the advantages of being
able to use a "filter" whereby only files with a certain
extension (such as "*.sim") will be displayed during 
browseing.  The routine "FILEBOX.R" will bring up the 
file dialog box, and return after the user has either 
selected a file, or cancelled the interaction.  Input 
parameters are the file filter string (wild card 
characters are allowed) and a title to display at the
top of the dialog.  Output parameters ("yielding" 
arguments) include the file name and its path
specification.  A more formal definition of this routine
is:

routine FILEBOX.R given FILTER, TITLE 
                  yielding PATH, FILE.NAME

The following code segment shows how it can be used:

define PATH, FILE.NAME as text variables
...
call FILEBOX.R given "*.txt", "Open a text file" 
               yielding PATH, FILE.NAME
write CONCAT.F(PATH, FILE.NAME) as 
"the file selected was ", T *
...


       Using the System Font Browser
       -----------------------------

Font browsers are useful whenever textual data is to 
be displayed from within a program.  This type of
system dialog lets the user choose which one of the 
fonts available on the system should be used for 
displaying graphic text.  Through the browser, text
can be chosen to be bold and-or italisized.  Its size 
is described in points and its style by the font family
name (for example "Courier", "Times Roman", etc).
Most font browsers will show a "sample" of the font
in a small window making it easier for a user to select 
appropriate font attributes.  The routine "FONTBOX.R" will
bring up a font browser and is defined as follows:

routine FONTBOX.R given TITLE 
                  yielding FAMILY.NAME, SIZE, WEIGHT, SLANT
  define TITLE as a text variable
  define FAMILY.NAME as a text variable 
  define SIZE as an integer variable   
  define WEIGHT as an integer variable
  define SLANT as an integer variable

The "SIZE" parameter generally ranges from about to 
4 to 28 points.  12 points is a common font size.  The 
"WEIGHT" and "SLANT" parameters meaure relative boldness 
and italisization respectively.  Both range from 0 to 1000
with 0 meaning no boldness or italics and 1000 meaning 
maximum boldness or italics.   The family name, size, 
weight, and slant INITIALLY shown in the dialog can set 
by pre-assignment of the corresponding parameters.  
The following example may be helpful:

  ...
  let FAMILY.NAME = "Courier"
  let SIZE = 12
  let WEIGHT = 1000
  let SLANT = 0
  call FONTBOX.R giving "Select Font" 
         yielding FAMILY.NAME, SIZE, WEIGHT, SLANT
  write FAMILY.NAME, SIZE, WEIGHT, SLANT as
  "Font ", T *, " with size ", I 4, ", weight ", I 4, 
  ", and slant ", I 4, " was selected."
  ...

The parameters obtained by FILEBOX.R can be passed directly
to "TEXTSYSFONT.R" for enabling the system to draw in this
font.


   Setting the Top Item Shown in a List Box
   ----------------------------------------
                 
When a list box contains more items than can be 
concurrently displayed, it may be neccesary to
programitically "scroll" to some position in that 
list.  List box scrolling can be implemented through 
"SET.LISTBOX.TOP.R".  Giving the index of an item 
contained in the list, the list box will be scrolled 
so that this item appears at the top of the window
showing the visible items.  The routine is defined as

routine SET.LISTBOX.TOP.R given LISTBOX.PTR, INDEX

and an example of its usage is

...
call SET.LISTBOX.TOP.R given 
      DFIELD.F("LISTBOX", FORM.PTR), 5
...

This program uses SET.LISTBOX.TOP.R to show the topic 
selected from the table of contents.


        Setting the System Cursor
        -------------------------

The system cursor is used to show the current mouse 
position on the screen.  Windowing systems frequently 
have many different cursor representations to choose 
from.  The "SETCURSOR.R" routine is used to set the 
cursor which will track the mouse from within the 
confineds of the window assigned to the current value 
of VXFORM.V.  In other words, the cursor will have the
prescribed representation as long as it is inside the 
current window.  The new routine is described below:

routine SETCURSOR.R given CURSOR.TYPE
  define CURSOR.TYPE as an integer variable

Currently there are only two possible values for 
CURSOR.TYPE available:

  0  -->  Default "arrow" cursor
  1  -->  Busy "watch" or "hourglass" cursor


        Using System Text in a Program
        ------------------------------

As described above, system defined fonts can now be 
employed in the creation of graphic text.  The 
WGTEXT.R routine is still used in conjunction with 
OPEN.SEG.R and CLOSE.SEG.R to draw the text, but a 
new routine called "TEXTSYSFONT.R" has been added 
for assigning system text attributes for subsequent 
drawing.  Calling TEXTSYSFONT.R enables the drawing
of system text; All subsequent text primitives will 
be of the system variety.  Calling TEXTFONT.R passing 
a parameter less than 8 disables the drawing of system 
text.  TEXTSYSFONT.R has the same arguments as are 
returned by FONTBOX.R.  The SIZE parameter is in
"points", while the WEIGHT and SLANT parameters are
percentages (integers between 0 and 1000).

routine TEXTSYSFONT.R given FAMILY.NAME, SIZE, 
                            WEIGHT, SLANT
  define FAMILY.NAME as a text variable 
  define SIZE as an integer variable   
  define WEIGHT as an integer variable
  define SLANT as an integer variable

An example of usage is:

...
call OPEN.SEG.R
call TEXTSYSFONT.R given "Courier", 12, 0, 1000
call WGTEXT.R(10000, 10000, "Hello World")
call CLOSE.SEG.R
...

The text attributes of alignment, rotation, and color 
still apply to system text, but TEXTSIZE.R and 
TEXTFONT.R do not apply.  In addition, system text 
can only be rotated 90, 180 or 270 degrees. 


    Sending window contents to a printer
    ------------------------------------

Using the function PRINTWINDOW.R the graphical 
contents of a window can be sent to a printer on
line.  The standard print dialog allowing you to set
up printer options can be displayed if desired.  For
example, the code:

define WINDOW.DSP as a pointer variable
define USE.DIALOG, SUCCESS as integer variables
...
call PRINTWINDOW.R(WINDOW.DSP, USE.DIALOG) 
  yielding SUCCESS

will print out the graphics in the window 'WINDOW.DSP'
which is returned from OPENWINDOW.R.

