NAME

suntools − the Suntools window environment

SYNOPSIS

[setenv PATH ${PATH}:/usr/suntool ]
suntools [−n | filename]

DESCRIPTION

Suntools starts up the Suntools window environment and awaits the user’s directions (often a menu action).  If /dev has not been initialized for the window environment, suntools will fail; see Initialization below for details.  If there is a file called .suntools in the user’s home directory, suntools starts the application programs (tools) specified in that file; this start-up processing can be bypassed by specifying the −n flag on the command line.  The format of the .suntools file is described in detail below under Startup Processing.. 

The indications that the suntools system is ready are:

1)the screen is painted with a light gray, and

2)an arrow-shaped cursor appears on the screen, tracking motions of the mouse.  The mouse
must be on its special pad before it can be tracked. Sometimes the cursor will not move at start-up; moving the mouse in large circles for a few seconds will bring the cursor to life.

Windows

The suntools window environment always has one window open which covers the whole screen; this is called the Root Window. The gray pattern mentioned above is the contents of the Root Window; it serves as the background for the suntools environment.  Tools that run in the environment are given their own windows which lie on top of portions of the Root Window (and possibly other tools).  A window obscures those portions of other windows which lie below it; thus, only the topmost window is guaranteed to be fully visible, and the background gray pattern shows through only in areas which have no tool windows on them. 

User Input to Windows

User input actions (typing on the keyboard, moving the mouse, or pressing buttons on the mouse) are directed to the window which lies immediately under the cursor at the time they occur.  User input actions are queued for each window, with mouse motions and button pushes integrated with keystrokes.  It is perfectly reasonable to type some characters to one window, then move the mouse to another window, and type or use the mouse in it before the first window has processed its input; the type-ahead and mouse-ahead are serialized and distributed correctly. 

The mouse buttons are usually interpreted as follows: the left button is used for selecting or choosing objects; the middle button is used to adjust selections to include more or fewer objects; and the right button is used to invoke menus.  However, the exact interpretation of user actions depends on the window receiving them.  For the standard tools available with the suntools system, the tool’s input handling is described with the rest of its behavior in its specific section below. 

Menus

Many functions in suntools may be invoked by using the mouse and a pop-up menu.  By convention, pressing the menu (right) button on the mouse and holding it down calls up the menu(s) appropriate to the window containing the cursor.  A menu is painted on the screen near the current location of the mouse, and the cursor is changed to a right-pointing arrow.  The menu remains on the screen as long as the menu button is held down, and the pointer tracks the mouse.  When the pointer enters a menu item, that item video-inverts, but nothing else happens while the menu button is kept down.  Releasing the button while the pointer is in a menu item invokes that menu item: the menu is removed from the screen, and processing of that item begins. 

Multiple Menus

Multiple menus are currently available only in the panetool.  However, the following description applies to multiple menus in general. 

You may see more than one menu presented simultaneously; generally this occurs when several different classes of actions are possible in the current context.  The menus are presented in a stack, with the label of each menu visible, and with the current menu on top so its items are also visible.  To bring another menu to the top, thus making its items available, invoke its label as you would a menu item.  That is, position the cursor in the label of the desired menu and release the menu button.  Then press the menu button again, and the stack of menus is presented once more, but now with the selected menu on top. 

An accelerator is provided for expert users to achieve the same result a little more quickly: when the cursor is positioned in the label of the desired menu, do not release the menu button; rather, while continuing to hold down the menu button, press and release the select (left) mouse button.  The stack of menus is repainted with the selected menu on top, and menu operations may continue. 

The Root Manager

The Root Window ignores all keyboard input; any keystrokes generated while the cursor is over the background gray are simply discarded.  However, four job-control functions are provided through the Root Window’s menu, which is presented when the menu button is depressed while the cursor is over the background gray. 

The items in the Root Manager menu are:

New ShellCreate a new Shell Tool. 
A new tool window is created on the screen, running a new copy of the shell. The window is placed on the screen on top of everything it overlaps. Its initial size can display 80 columns and 34 rows of characters.

New GraphicsCreate a new Graphics Tool. 
A new tool window appropriate for running graphics programs is placed on the screen on top of everything it overlaps.

ExitExit the suntools program. 
All tool windows are closed, and their associated processes are killed. The user is returned to the shell which invoked suntools. This command requires confirmation: press the left mouse button to complete it; press the right button to cancel.

ReDisplay AllAll the contents of the screen are redrawn. 
This can be used to repair damage done by processes that wrote to the screen without consulting the Suntools system (see the discussion of the Shell Tool for details on how to avoid this).

The Tool Manager

Tools interpret most user input in their own fashion; for instance, many tools incorporate a terminal emulator running a shell.  However, tools are also expected to provide a small set of universal functions, through the Tool Manager menu.  These functions are available when the cursor is over a portion of the tool which does not impose some other interpretation on the user input.  For any tool, the black stripe at the top which holds the tool’s name, the border stripes of the window, and the whole of the tool’s icon are such areas. 

The items in this menu are:

Close (or Open)Shrink the tool to a small image on the screen. 
Its process(es) continues to run.  Closed windows are by default placed in the lower left of the screen, filling in rows to the right, and then bottom-to-top, in the order they are created.  A closed window may be moved just like an open one; if it is reopened and closed again, it returns to its last closed position.

When the Tool Manager Menu is brought up over a closed window, this item reads Open, and serves to reverse the process.  When reopened, windows return to the position from which they were closed. 

MoveChange the location of a window on the screen, without affecting its size or contents. 
When invoked, Move instructs the user to grasp the window by depressing and holding down either the left or middle mouse buttons, or to cancel the operation by pressing the right button; depressing any mouse button removes these instructions from the screen.  When either the left or middle button is depressed, the window is outlined by a box which tracks the mouse as long as that button is held down.  The position of the pointer when the button is pressed determines how the window is moved: if it is near a corner, that corner of the box is attached to the mouse cursor.  If it is in the middle third of a side, then the midpoint of the side of the box is attached to the mouse cursor.  This box should be positioned where the window should go and the mouse button released; the window is repainted in its new location, and its old location repaired.  The level of the window (on top of or underneath others) is not affected.

StretchChange the size of a window on the screen. 
As with Move, instructions are posted for the user until a mouse button push either starts the Stretch or cancels it.  The position of the pointer when either the left or middle button is pressed determines how the window is stretched: if it is near a corner, both of the sides that form that corner are adjusted; the opposite corner remains fixed.  If it is in the middle third of a side, then only that side is adjusted; all 3 other sides remain fixed.  The use of the bounding box, and behavior with respect to window level, is the same as for Move.

ExposeBring the window to ‘the top of the heap’. 
The whole window becomes visible, and occludes any window it happens to overlap on the screen.  Its position on the screen does not change.

HidePut the window on the ‘bottom of the heap’. 
The window is occluded by any window which overlaps it.  Its position on the screen does not change.

ReDisplayRedraw the contents of the window. 

QuitNotify the tool that it should terminate gracefully. 
This command requires the same type of confirmation as the Exit command in the Root Menu.

In many multi-subwindow tools, the boundary between two subwindows may be adjusted up or down without changing the overall size of the tool.  To do this, depress the middle mouse button over the boundary; a bounding box will be drawn for the subwindow above or to the left of the selected boundary.  Now adjust the size of that subwindow, exactly as with the Stretch operation.  When the button is released, that subwindow is adjusted to the size indicated, and the remaining area of the tool is allotted to the other subwindows. 

Tool Management Accelerators

Accelerators are provided for some of the Tool Manager functions, allowing experienced users to invoke these functions more quickly: these functions can be invoked with a simple button push in the tool window. 

The accelerators for the various functions are:

OpenA closed (iconic) tool may be opened by clicking the select (left) mouse button while the cursor is over the icon. 

MoveThe Move operation may be invoked by depressing the middle mouse button while the cursor is in the tool window’s name stripe or outer boundary; a bounding box is displayed and tracks the mouse as long as the middle button is held down; the window is placed in the position indicated by that box when the button is released. 

ExposeClicking the left mouse button at an open tool window exposes that window. 

HelpTyping a question mark to a tool window will cause a help message to be displayed on the screen, explaining the material covered here. 

Terminal Emulators and Selections

Several tools provide a terminal emulator in some part of their window, running a shell.  Keystrokes typed to this subwindow are passed through to the program running in it, rather than being handled by the tool.  (This means these tools provide Tool Manager functions only when the cursor is in their name stripe or borders.) Similarly, output from the programs is displayed in the window. 

Terminal subwindows support a facility called a selection, which provides for limited inter-tool communication and mouse-oriented text manipulation.  A selection is a span of characters which you may wish to manipulate.  The mouse is used to make a selection:

•Click the select (left) mouse button while the tip of the cursor is over a character, and that character is selected.  Any previously selected characters are de-selected.  A box is drawn around selected characters to indicate their status. 

•Click the adjust (middle) mouse button to change the span of characters that are selected: all characters from the one originally selected through the one over which adjust is pressed are selected.  Characters which used to be selected, but which do not lie in the span just described, are de-selected.  The box which indicates the selection is adjusted to reflect its new contents. 

Only characters which are displayed in a terminal subwindow may be selected.  Characters which are in a portion of the window obscured by another window will be selected if they lie within a span of characters whose endpoints are selected. 

The user feedback (the boxed characters) indicating the selection is removed if:

•the cursor moves out of the subwindow which holds the selection,

•any key is typed, or

•any new output is written to the window which holds the selection. 

However, even if the feedback is removed, it is important to note that the selection still exists and can be operated upon until the point in time that another selection is explicitly made by the user.  The fact that the feedback is removed in these circumstances reflects an incomplete selection implementation. 

The selection is manipulated via the Selection menu provided by the terminal subwindow.  There is a single menu item:

StuffThe characters in the selection, are copied to the window as though they had been typed at the keyboard.  The window in which Stuff is invoked does not have to be the same as the one in which the selection was made; thus text may be copied between windows by this facility. 

The selection mechanism is not integrated with the terminal emulator.  However, it is useful for building up complex command sequences and helps avoid repetitive keyboard input.  Selection facilities will be expanded in future releases. 

Other Aspects of Terminal Emulators

Existing tools with terminal emulator subwindows pass command line arguments to the terminal emulator.  The terminal emulator then passes a command line to the program it starts.  No arguments indicate that the program described by the user’s SHELL environment value is run by the terminal emulator.  If this program is not available then /bin/sh is run.  If there are arguments then the program named by the first one is run.  However, if the first argument is "-c" then a shell is run which in turn runs the command line named by the argument following the "-c" (See Start-up Processing below for an example). 

The Shell Tool

The Shell Tool is one of the standard tools provided with the suntools environment.  It consists of a terminal subwindow, in which a shell is started.  Because keystrokes are passed to the shell, or the programs run from it, and the mouse is used to support selections, the Tool Manager is not accessible from the terminal subwindow of the Shell Tool.  Tool Manager functions may be accessed in the tool’s name stripe and borders. 

Programs that are run in the Shell Tool are generally for character-oriented terminals.  Graphics Programs (see below) will run in the Shell Tool, but may exhibit minor glitches.  Graphics Programs should be run in the Graphics Tool (see below). 

The size of the Shell Tool’s virtual terminal (in lines and columns) is adjusted to reflect the dimensions of the window as they change.  Thus, programs like emacs, more, and vi, which inquire the characteristics of the terminal they run on, adjust to differently-sized windows automatically.  Since they only inquire as they start up, however, they do not reflect changes to window dimensions that occur after they are started; such changes may result in a confusing display for that program.

One important feature of a Shell Tool is that it may be used as a substitute for the standard console.  Unless instructed otherwise, the system displays messages for the console by writing directly on the bitmap display, bypassing all of the support for multiple windows sharing the bitmap; thus, console messages damage the window images.  It is possible to redirect console messages into a terminal subwindow by starting a Shell Tool with a first argument of CONSOLE, which causes all messages destined for the console to appear inside this shell’s window.  An example appears under Startup Processing below. 

The Graphics Tool

The Graphics Tool is a second tool provided with suntools. It has two subwindows: a terminal subwindow in which a shell is started, just as for the Shell Tool, and a graphics area which may be drawn on by programs invoked from that shell. The boundary between these two subwindows may be moved as described in The Tool Manager above.  The graphics area normally acts as part of the tool window for user input; that is, it provides Tool Manager functions to mouse and keyboard events.  Some graphics programs run in this window may take over inputs directed to it; SunCore is an example, since it uses the mouse and keyboard for its own input.  While this is true, Tool Manager functions are accessible only in the namestripe and borders, as with the Shell Tool.  When the program which has taken the input terminates, the window is restored to its original status. 

Demos which draw pictures should be run in the Graphics Tool; the four distributed with the current release of suntools are:

/usr/suntool/bouncedemo
Displays a bouncing square in the graphics window.  A decimal number on the command line indicates how many repetitions of the bounce sequence should be done.

/usr/suntool/spheresdemo
Laboriously computes a shaded sphere.  A “-n” followed by a decimal number on the command line indicates how many instances of the same sphere should be shaded thus progressively darkening it.

/usr/suntool/jumpdemo
Simulates the famous Star Wars jump to light-speed sequence using vector drawing.  A “-n” followed by a decimal number on the command line indicates how many stars should be used in the star field, up to 500. 

/usr/suntool/framedemo
Displays a series of frames, each of which contains a 256 by 256 image formed of pixels one deep (that is, the image is a square monochrome bitmap, with 256 bits on a side).  The frames must be in the files frame.1 through frame.n on the current working directory, and are displayed in numerical order.  A set of sample frames is available on the directory /usr/suntool/globeframes.  A “-n” followed by a decimal number on the command line indicates how many times to cycle through the frames.  If the cursor is moved into the image window, typing certain characters affects the rate at which the frames are displayed: the initial rate is one frame per second; each “S” causes an additional one second delay between frames; each “F” removes one second from the inter-frame delay; each “s” adds 1/20th of a second; each “f” removes 1/20th of a second. 

For all these demos the following is true: if no −n flag appears on the command line then the program runs continuously until interrupted by the user.  A −r flag on the command line turns the window into a retained window which allows the image to reappear when uncovered instead of restarting the demo. 

The Icon Tool

The Icon Tool is a simple bitmap editor, useful for constructing small images such as cursors and icons.  It has three subwindows; clockwise from the upper left:

•a small ‘proof area’ for checking the image as it is drawn,

•a control panel which is an options subwindow, as described in chapter 7 of the Sun Window System Programmer’s Manual, and

•a large canvas on which to draw the image. 

Painting

The canvas dispays magnified pixels in a square either 16 or 64 on a side.  The larger magnification (fewer pixels) is appropriate for cursors; the smaller, for icons.  The left mouse button is used to darken (paint) pixels on the canvas; the middle button to lighten (erase) them.  A button may be held down and the cursor ‘wiped’ through several pixels.  The right (menu) button has no special significance to the icontool, so it invokes the standard tool-manager menu. 

The Control Panel

The control panel presents a number of parameters and commands:

Quitis a command; when the left or middle mouse button is released over it, the icontool goes away. 

Image Type
is a parameter which controls whether the icontool is working on a cursor-sized (16-square) or icon-size (64-square) image.  The image type may be set by clicking either the left or middle mouse button over the desired choice.  The image type can also be set by the Load File command (below), according to the size of the object loaded.  When the image type is changed, the old image is preserved, and restored if type is changed back.

Cursor Op
is a parameter which controls the RasterOp used to display a cursor image, either ORing the cursor with the background, or XORing them.  It is set with the mouse, just like the type parameter.

Invert Image
is a command which inverts all the pixels in the current image. It is invoked by releasing either the left or middle mouse button over the command.

Load File
is a command, invoked like Invert Image.  Load File attempts to read the file whose name is given in the File Name parameter.  Load File expects a text file which defines and initializes an array of 32-bit words, 4 on a line, in hex — the format generated by the Store File command.

Store File
is a command which writes the current image into the file named by the File Name parameter, overwriting any previous contents.

File Name
is a text parameter used by the Load File and Store File commands.  Any (printable) characters typed at the keyboard while the cursor is in the option subwindow are appended to the file name parameter.  The user’s erase and kill characters may be used to delete the last character and the whole text.  There is no need to enter an ‘insert’ command, or to terminate the name with a carriage return, escape, or other terminator; Load File and Store File will always simply use the text currently available.

Feedback

In icon mode, the proof window in the upper left corner presents the current image at its true size on a white background.  In cursor mode, the cursor in the canvas and proof windows is updated continuously to reflect the current image.  The proof window displays four backgrounds against which it may be interesting to test a new cursor. 

The Clock Tool

The Clock Tool is a simple tool to display the current time.  It must be started from a shell, or an entry made for it in your start-up file, since it does not appear in the Root Manager menu.  Type clocktool  & to any shell running in a window; the ampersand allows the shell to process other commands while the clock is running.  While it is open, the Clock Tool prints the date and time in its window; when it is closed, its icon is a clock face which keeps time.  The Clock Tool’s window is not a terminal subwindow; it provides the Tool Manager menu if the menu button is depressed over it.  However, it listens for keyboard input, toggling its state on two letters (case does not matter):

stoggles the display of seconds.  The clock starts with seconds turned off, and updates every minute.  With seconds turned on, it updates every second, and, if iconic, displays a second hand. 

ttoggles the ‘test’ mode.  The clock starts with testing off.  With testing on, the clock ignores the real time, and instead runs in a loop continuously incrementing the time by one minute and displaying it. 

These states may only be modified while the clock is open; when it is iconic, it responds with the standard Tool Manager functions to mouse and keyboard input. 

The Pane Tool

The Pane Tool is a sample tool to demonstrate a random collections of features not used by other tools:

•There are four subwindows that tile the tool surface.  The boundaries between the subwindow can be moved as described above. 

•Keyboard input directed at the upper right subwindow is redirected to the upper left subwindow. 

•Keyboard input directed at the upper left subwindow demonstrates raw unencoded up/down keyboard codes. 

•The lower left subwindow cycles through alternating menu stacks each time the menu button is depressed. 

Start-up Processing:  The ‘.suntools’ File

Suntools can set up a standard arrangement of windows for the user when it starts up.  It does this by reading the file .suntools in the user’s home directory, and following the instructions there.  A file name on the command line indicates an alternative file to be read.  A −n switch suppresses start-up processing. 

Each line in the file indicates data for one tool to be started.  A line has the format:

path  nl  nt  nw  nh  il  it  iw  ih  I  args

where path is the file name of the tool to be run, nl, nt, nw, and nh are decimal numbers which define the window for the normal (open) tool, as left edge, top edge, width, and height; il, it, iw, and ih are the same for the iconic form of the tool; and I is a boolean flag which should be non-zero if the tool is to be started in its iconic form.  The remainder of the line (args) is passed to the program running in the window as command-line arguments.  The origin (0, 0) is the upper left hand corner of the screen.  If a size parameter is equal to −1 then the Root Manager assigns an appropriate value. 

For example, consider a .suntools file containing:

shelltool0    72  -1   7284    4   64  640-c "vi ~/sked"
shelltool372  0   -1   792-1   -1  64  640CONSOLE
clocktool4    4   180  40 232  4   64  641

This starts suntools with three tools active:

•A Shell Tool in a window 38 by 80 characters, pushed into the lower left corner of the screen, leaving enough space above it to fit some icons, and running the editor vi on a file named ‘sked’ in the user’s home directory.  The string ‘vi ~/sked’ is passed as a command to be executed by the shell which runs in the tool.  The icon is placed in the upper left corner of the screen. 

•Another Shell Tool, extending nearly the full height of the screen (48 lines), and butted against the right edge. Its icon is placed by the system, and the shell waits for user typein; this shell’s window will display all messages directed to the console. 

•A Clock Tool starts out iconic, about a quarter of the way across the top of the screen. 

The program toolplaces in the directory /usr/suntool can be helpful in constructing the .suntools file; it writes (on the standard output) a description of the windows that exist at the time it is run. 

Changing the System Font

The system has a default font built into it.  It is possible to use another font instead by setting the environment variable DEFAULT_FONT to the name of the file containing the font to use.  DEFAULT_FONT must have been set in the shell from which the program was invoked.  A small number of valid alternative fonts can be found in the directory /usr/suntool/fixedwidthfonts. 

Getting Out

Any tool may be exited by invoking the Quit command in the Tool Manager menu while over the tool’s window, as described above.  Tools which run a shell (the Shell Tool and Graphics tool) also go away if that shell ever exits, so typing ^D to the shell in a terminal subwindow also makes the tool go away.  Exit the whole window system by invoking the ‘Exit’ menu item in the Root Manager menu, and confirming that that’s what you meant when the system inquires.  It is wise to ensure that all windows are in a safe condition (for example, editors have written out all changes) first. 

Initialization

Before suntools can be run, appropriate devices must be created for it in the /dev directory.  This need only be done once on each machine.  If this has not yet been done,

•set your user id to root,

•change directory to /dev, and

•execute the shell script ‘MAKEDEV win0’. 

Suntools also needs the file /etc/utmp to have read and write permission for all users.  It should have been installed with these permissions, but if not, you need to use chmod to change the permissions. 

FILES

/usr/suntool/suntools
~/.suntools
/usr/suntool/fixedwidthfonts/∗
/usr/suntool/clocktool
/usr/suntool/gfxtool
/usr/suntool/panetool
/usr/suntool/shelltool
/usr/suntool/icontool
/usr/suntool/bouncedemo
/usr/suntool/framedemo
/usr/suntool/globeframes/∗
/usr/suntool/jumpdemo
/usr/suntool/spheresdemo
/usr/suntool/toolplaces
/etc/utmp
/dev/winx
/dev/ptypx
/dev/ttypx
/dev/MAKEDEV

BUGS

This release has the following notable bugs:

(1)Messages from the kernel ignore window boundaries unless console messages have been redirected, thus trashing the display.  Recover from this by invoking the ‘ReDisplay All’ item on the Root Manager menu. 

(2)Remote login to another machine should be done with a your terminal emulator subwindow matching the standard terminal size for the remote machine (for example, 34 by 80 character for a Sun workstation) The remote machine does not understand terminals with non-standard size. 

(3)Stuffing a selection of more than about two hundred characters into the terminal emulator in one operation fails.  The screen flashes as it throws each excess character away. 

(4)Acceptable performance on realistic tasks (for example editing with vi while running a C compile with make) requires about 600K of available user memory.  With 0.9 Unix on a model 100U, the kernel may have to be reconfigured to make that space available.  See the System Managers Guide. 

Sun System Release 1.0  —  25 October 1983