      *******  New graphics enhancements to SIMSCRIPT II.5 ********
                             (Release 2.0)

                              8/29/97

1. New SIMDRAW 

The SIMDRAW graphics editor has been reimplemented to
show a more intuitive and up-to-date look and feel.  All existing graphics 
library (.sg2) files are supported.  The new SIMDRAW will allow you to 
create some objects not found in the previous release such as palettes, 
hierarchical lists (trees), tabbed dialog boxes, multiline text boxes, 
and message dialogs.  The new simdraw also comes with on-line help 
(On XWindows systems the on-line help requires "Netscape Navigator".)  


2. Palettes

Simscript applications can now have palettes attached to the
sides of the windows (or they can be floating).  A palette contains rows and
columns of square palette buttons.  On the face of each palette button is 
a bitmap icon.  This bitmap comes from a ".bmp" file on MS Windows and a
".xwd" file on XWindows which must be in the same directory as your 
"graphics.sg2" library file.  

Palettes are added to your application through SIMDRAW.  Enter the palette
editor using the "Insert/Palette" option from the SIMDRAW menubar.
See the SIMDRAW help section on palette editing.

Palettes are used inside your program the same way that menubars are; by
calling ACCEPT.F given pointers to both the palettes display entity and
control routine.  The accept.f call must be made from within a process
and, a control routine must be included to allow the palette to behave
asyncronously.  Whenever the user clicks on a palette button, the control 
routine is called given the button's field name.  

There are three varieties of palette buttons, momentary, toggle and dragable.  
Momentary buttons pop back up automatically after being pressed,  while
toggle buttons stay down.  Dragable buttons allow the user to click down on
a palette button, then drag its outline to the canvas of the window.  When
the mouse buttons is released, the palette's control routine is called.
From withing the control routine, the drop point can be retrieved through 
LOCATION.A attributes of DINPUT.V.  DIVAL.A(DINPUT.V) will contain the 
Viewing transform number where within that drop location.

Displaying the palette can be done as follows:

process PALETTE
...
show PALETTE.FORM with "mypalette.frm"
let FIELD.ID = ACCEPT.F(PALETTE.FORM, PALETTE.CTRL) '' will suspend this proc.
...


This is a typical palette control routine:

routine PALETTE.CTL given FIELD.ID, FORM yielding STATUS
...
select case FIELD.ID
  case "INITIALIZE"   '' called once just after ACCEPT.F call
    ...
  case "BACKGROUND"   '' called when clicked on window canvas background
    ...
  case "MYFIRSTBUTTON" '' palette button was clicked on
    ...
  case "MY_DRAGGABLE_BUTTON"
    let VXFORM.V = DIVAL.A(DINPUT.V)
    display NEW.ICON at with "temp.icn" at
        (LOCACION.X(DINPUT.V), LOCATION.Y(DINPUT.V)) 
...



3. Tree view list

List of items can now be viewed hierarchically with items containing other
items.  In addition, items in the list can be denoted with a small bitmap
icon.  The tree view list can be added to your dialog box from within 
SIMDRAW.  Items can be added to the list either from within SIMDRAW or
your program.  

The items contained in the list are defined through the DARY.A attribute
of the dialog box field corresponding to the tree. The name specification 
uses the "/" character to separate container name from item name and works
much the same way as a path name for the file system, i.e.

"<top_container_name>/.../bottom_container_name>/<item_name>"

For example, if you wanted to show following items:
a) "San Fransisco" contained in "California" which is in "Usa States"
b) "San Diego" contained in "California" which is in "Usa States"
c) "Las Vegas" contained in "Nevada" which is in "Usa States"
d) "Berlin" contained in "Germany" which is in "Europe"

The DARY.A array should contain the following text strings:

"Usa States/California/San Fransisco" 
"Usa States/California/San Diego" 
"Usa States/Nevada/Las Vegas" 
"Europe/Germany/Berlin" 


To define the bitmap icon to place next to the item name, use the "|" character
after the name specification to separate the path name from bitmap file
(or resource) name (without extension).  For example, to use bitmap ZOOM_L
for item "Zoom Tool" in category "Tools", the array item would be: 

"Tools/Zoom Tool|ZOOM_L"  

To define an icon for a category, list the category by itself on a 
separate line with the "|" character and the bitmap names, i.e.

"Tools|SELTOOL_L"

If you need to use the "|" or "/" characters in your item name, you can
literalize them using a preceeding backslash "\" character.

The DDVAL.A attribute of a tree list field pointer will contain the index
of the last selected item.  In the above example, if the user clicked on
the "Las Vegas" item, the field's DDVAL.A attribute would be "3".
You can set the selected item in the tree by setting DDVAL.A and redisplaying
the field.  From above, to set the selected item to "San Diego":

...
let DDVAL.A(DFIELD.F("MY_TREE", DIALOG.PTR)) = 2
display DFIELD.F("MY_TREE", DIALOG.PTR)
...


4. Alert dialogs

Your program can now display alert, question, information and stop message
dialogs predefined by Motif or MS Windows.  Message dialogs are built using
SIMDRAW (use the "message dialog" button on the left hand "mode" palette 
shown with SIMDRAW's main window.)  A message dialog can be one of the 
following 5 styles:

a) Plain
b) Stop Sign
c) Question mark
d) Alert (Exclamation point)
e) Information 

It can will contain one of the following sets of response buttons:

a) Ok button only
b) Ok & Cancel buttons
c) Yes & No buttons
d) Yes, No & Cancel buttons
e) Retry & Cancel buttons
f) Abort, Retry & Ignore buttons

Message dialogs are displayed using the "show" statement then the "ACCEPT.F"
routine (like a conventional dialog).  Control routines are not used with
message dialogs.  The text of the message can be set from SIMDRAW or
through the program.  The DARY.A attribute of the message dialog form 
points to a text array containing the lines of message text. 

The field id text returned by ACCEPT.F describes which
button was pressed.  Valid responses returned by accept.f are "OK", "CANCEL",
"YES", "NO", "ABORT", and "RETRY".  (Note: there is no display entity 
corresponding to these field names; do not use DFIELD.F()).  The following
examples shows a typical interaction with a message dialog:

...
show MESSAGE.PTR with "retry_cancel.frm"
let TEXT.LINES(1) = "D:\ is not accessible"
let TEXT.LINES(2) = "The device is not ready."
let DARY.A(MESSAGE.PTR) = TEXT.LINES(*)

select case ACCEPT.F(MESSAGE.PTR, 0)
  case "RETRY"    ...
  case "CANCEL"   ...
endselect
...


5. Tabbed Dialog Boxes

Tabbed dialogs are created from within SIMDRAW.  In simdraw, tabbed dialogs can
be created, or existing dialogs can be converted to become tabbed.  
Using tabbed dialogs requires no change to the source program.


6. Popup menus

A popup menu is displayed as a result of a right mouse button click in
the background of a window.  The function "POPUP.F" shows the popup menu
given an array of text values to show in the menu.  The index of the 
selected item is returned.  Zero is returned if the user doesnt select 
an item.  The menu will not be displayed unless the right mouse button
is down at the time POPUP.F is called.  If you want to "monitor" the 
right mouse button, create a process for this purpose and use READLOC.R
with style 16.  For instance:

process POPUP
...
while 1=1 do

    '' suspend this process until mouse button clicked
    call READLOC.R(0.0, 0.0, 16) yielding X, Y, VXFORM

    reserve POPUP.ITEMS(*) as 3
    let POPUP.ITEMS(1) = "Zoom In"
    let POPUP.ITEMS(2) = "Zoom Out"
    let POPUP.ITEMS(3) = "Properties..."

    '' bring up the popup
    select case POPUP.F(POPUP.ITEMS(*))
      case 0   '' do nothing
      case 1   '' zoom in
      case 2   '' zoom out
      case 3   '' get background properties
    endselect
loop
...


7. Checked menu items

You can now hove check marks displayed programatically next to any menu 
item.  To display the check mark, set the DDVAL.A attribute of the 
menu item field pointer to one (1), then re-display the field. For example

...
let DDVAL.A(DFIELD.F("MENUITEM_TO_CHECK", MENUBAR.PTR)) = 1  
let DDVAL.A(DFIELD.F("MENUITEM_TO_CLEAR", MENUBAR.PTR)) = 0  
display DFIELD.F("MENUITEM_TO_CHECK", MENUBAR.PTR)
display DFIELD.F("MENUITEM_TO_CLEAR", MENUBAR.PTR)
...


8. Where to find more examples of enhancements

a) Palettes 		-- "bounce" demo
b) Tree List 		-- "newsg2/treehelp", "newsg2/iconlist"
c) Alert boxes		-- "newsg2/mboxhelp"
d) Tabbed dialogs	-- "food" demo
e) Popup menus		-- "bounce" demo (right mouse click on a ball)
f) Checked menu items	-- "bounce" demo

