NAME

suntools, othertools, selection_svc − the SunView window environment

SYNOPSIS

suntools [ −n | −s startup-file ] [ −S ] [ −d display-device ] [ −m mouse-device ] [ −k keyboard-device ]

[ −p ] [ −b red green blue ] [ −f red green blue ] [ −i ] [ −B|−F|−P ]

[ −pattern on | off | gray | iconedit-file-name ] [ −background raster-file-name ] [ −8bit_color_only ] [ −toggle_enable ] [ −overlay_only ]

GETTING STARTED

suntools starts up the SunView environment and (unless you have specified otherwise) a default arrangement of a few useful “tools,” or window-based utilities. 

See Start-up Processing below to learn how to specify your own initial arrangement of tools.  Some of the behavior of suntools is controlled by settings in your defaults database; see SunView Defaults below. 

OPTIONS

−n Bypass startup processing by ignoring both the /usr/lib/suntools and ~/.suntools files.  See Startup Processing for details. 

−s startup-file
Read startup commands from startup file (instead of /usr/lib/suntools or ~/.suntools).

−S Set "click-to-type" mode, allowing you to select a window by clicking in it.  Having done so, input is directed to that window regardless of the position of the mouse-cursor, until you click to select some other window. 

−d display-device
Use display device as the output device on which to run, rather than the default frame buffer device, /dev/fb. 

−m mouse-device
Use mouse device as the system pointing device (locator), rather than the default mouse device, /dev/mouse. 

−k keyboard-device
Accept keyboard input from keyboard device, rather than the default keyboard device, /dev/kbd. 

−p Prints to standard out the name of the window device used for the suntools Root Window. 

−b red green blue
Specifies the values of the red, green and blue components of the background color.  If this option is not specified, each component of the background color is 255 (white).  Prism users that use this option should use the -8bit_color_only option too. 

−f red green blue
Specifies the values of the red, green and blue components of the foreground color.  If this option is not specified, each component of the foreground color is 0 (black).  Prism users that use this option should use the -8bit_color_only option too. 

−i Invert the background and foreground colors used on the screen.  On a monochrome monitor, this option provides a video reversed image.  On a color monitor, colors that are not used as the background and foreground are not affected. 

−B Use the background color for the Root Window color. 

−F Use the foreground color for the Root Window color. 

−P Use a stipple pattern for the Root Window color.  This option is assumed unless −F or −B is specified. 

−pattern [on | off | gray | iconedit-file-name]
Use the indicated “pattern” to cover the Root Window. on means to use the default desktop gray pattern.  off means to not use the default desktop gray pattern.  gray means to use a 50% gray color on color monitors.  iconedit-file-name is the name of a file produced with iconedit(1) which contains an image that is replicated all over the Root Window.

−background raster-file-name
Use the indicated raster file as the image in your Root Window. The raster file can be created with screendump(1). Screen dumps produced on color monitors currently do not work as input to this option. Small images are centered on the screen.

−8bit_color_only
For multiple plane group frame buffers, only let windows be created in the 8 bit color plane group.  This frees up the black and white overlay plane to have a separate desktop running on it. This option is usually used with the −toggle_enable option.  See the section below entitled Multiple Desktops on the Same Screen. 

−toggle_enable
For multiple plane group frame buffers, when sliding the cursor between different desktops running within different plane groups on the same screen, change the enable plane to allow viewing of the destination desktop. See the section below entitled Multiple Desktops on the Same Screen. 

−overlay_only
For multiple plane group frame buffers, only let windows be created in the black and white overlay plane group.  This frees up the 8 bit color plane group to have a separate desktop running in it. This option is usually used with the −toggle_enable option.  See the section below entitled Multiple Desktops on the Same Screen. 

DESCRIPTION

Windows

The SunView environment always has one window open, called the Root Window, which covers the whole screen.  A solid color is its only content.  Each tool is given its own window which lies on top of some of the Root Window (and possibly on top of other tools).  A window obscures any part of another window which lies below it. 

Input to Windows

Mouse input is always directed to the window the mouse cursor is in.  You can have keyboard input follow mouse input, or you can use the “Click-to-Type” approach.  With Click-to-Type, keyboard input continues to be directed to a window, no matter where the mouse is pointing, until you click the left or middle mouse button in another window.  Click-to-Type is an option in your defaults database; see SunView Defaults below.  If you are not using Click-to-Type, and your mouse cursor is in the Root Window, keyboard input is discarded. 

Your input actions (mouse motions, button pushes, and keystrokes) are synchronized.  This means that you can “type-ahead” and “mouse-ahead,” even across windows. 

The Mouse Buttons

Left button(the select button)  Click once to select or choose objects. 

Middle button(the adjust button)  Click once to shorten or lengthen your selection. 

Right button(the menu button)  Depress and hold down to invoke menus. 

Menus

suntools provides pop-up menus. In the current release, there are two styles of pop-up menus: the original menu style, called stacking menus, and a new style, called walking menus (also known as “pull-right menus”).  A menu is invoked by pressing and holding the menu button.  The menu remains on the screen as long as you hold the menu button down.  To select a menu item, point at it (it will be highlighted), then release the menu button. 

With stacking menus, more than one menu can appear simultaneously.  The menus are shown in a stack, with the label of each menu visible, and with the current menu on top so that its items are visible.  To bring a menu to the top (and make its items available), select its label as you would a menu item.  Then push the menu button again.  The menu stack is repainted with the selected menu on top. 

With walking menus, any menu item can have an arrow ( => ) on the right.  Pointing to this arrow invokes a sub-menu, with additional menu items that can be selected. Selecting an item that has an arrow (a “pull-right item”) invokes the first item on the sub-menu.

Walking menus are an option in your defaults database; see SunView Defaults below. 

The Root Window Menu

You can use the default Root Window Menu to start ten common tools and perform three functions.  To invoke it, hold down the menu button when the mouse cursor is anywhere in the Root Window. 

The items in the default Root Window Menu are:

ShellToolCreates a new shelltool(1), running a new copy of the shell.

CommandToolCreates a new cmdtool(1), a scrollable cousin of the shelltool.

MailToolCreates a new mailtool(1).

TextEditorCreates a new textedit(1).

DefaultsEditorCreates a new defaultsedit(1), for browsing or changing your defaults database.

IconEditorCreates a new iconedit(1).

DbxToolCreates a new dbxtool(1), a window-based debugger.

PerfMeterCreates a new perfmeter(1), to monitor system performance.

GraphicsToolCreates a new gfxtool(1), for running graphics programs.

ConsoleCreates a new Console window, a cmdtool with a −C flag, which acts as the system console.  In particular, most error messages will be directed to the console.  You should always have a console window on your screen. 

Lock ScreenCompletely covers the screen with a graphics display, and “locks” the workstation until you type your password.  When you “unlock” the workstation, the screen is restored as it was when you locked it.  See lockscreen(1) for details.

Redisplay AllRedraws all the contents of the screen.  Use this to repair damage done by processes that wrote to the screen without consulting the SunView system. 

Exit SuntoolsExits the suntools program.  Closes all tool windows and kills their associated processes (depending on the processes, this can be fairly slow).  You return to the shell which invoked suntools.
This command requires confirmation: When it prompts you, press the left mouse button to complete the Exit Suntools command; press the right button to cancel.

You can specify your own Root Window Menu; see SunView Defaults below. 

The Frame Menu

A small set of universal functions are available through the Frame Menu.  There are also accelerators for some of these functions; see below. 

You can invoke the Frame Menu when the cursor is over any part of the tool which does not provide an application-specific menu, such as the tool namestripe (black stripe holding the tool’s name), the border stripes of the window, and the whole of the tool’s icon. 

The items in the Frame Menu are:

Close (Open)Only one of Close or Open appears in the menu, depending on the current state of the window.  Close shrinks the tool to a small image (an icon). Open reopens an icon and places the tool in the spot it occupied when it was open.  Icons are placed on the screen according to the icon policy in your defaults database; see SunView Defaults below.  You can move a closed window just like an open window.  When the window is closed, the tool’s process(es) continue to run. 

MoveMoves the tool window to another spot on the screen.  When invoked, Move instructs you with an instruction box that appears in the middle of the screen. 
If you are using walking menus, Move has a sub-menu with two items: Constrained and Unconstrained.  Constrained moves are either vertical or horizontal, but not both.  Selecting Move invokes a Constrained move. 

ResizeShrinks or stretches the size of a window on the screen.  Resize, like Move, instructs you with an instruction box that appears in the middle of the screen. 
If you are using walking menus, Resize has a sub-menu with four items: Constrained, Unconstrained, Zoom (or UnZoom, depending on the current state of the window) and FullScreen.  Constrained resizes are either vertical or horizontal, but not both.  Zoom makes a window the full height of the screen; UnZoom undoes this.  FullScreen makes a window the full height and width of the screen; UnZoom undoes this.  Selecting Resize invokes a Constrained resize. 

ExposeBrings the window to ‘the top of the pile’.  The whole window becomes visible, and occludes any window it happens to overlap on the screen. 

HidePuts the window on the ‘bottom of the pile’.  The window is occluded by any window which overlaps it. 

RedisplayRedraws the contents of the window. 

QuitNotifies the tool to terminate gracefully.  This command requires the same type of confirmation as the Exit Suntools command in the Root Window Menu. 

Frame Menu Accelerators

Accelerators are provided for some of the Frame Menu functions.  You can invoke these functions quickly with a simple button push in the tool window’s name stripe or outer boundary, without displaying a menu.  See Windows and Window-Based Tools: Beginner’s Guide for more details. 

The accelerators for the various functions are:

OpenClick the select mouse button when the cursor is over the icon. 

MoveDepress the adjust mouse button while the cursor is in the tool’s name stripe or outer boundary.  A bounding box is displayed which tracks the mouse as long as you hold the adjust button down. 
If the cursor is near a corner when you press the mouse button, the move is Unconstrained.  If it is in the middle third of a side, the move is Constrained. 

ResizeWhile holding down the CTRL key, depress the adjust mouse button while the cursor is in the tool’s name stripe or outer boundary.  A bounding box is displayed, one side or corner of which tracks the mouse as long as you hold the adjust button down. 
If the cursor is near a corner when you press the mouse button, the resize is Unconstrained.  If it is in the middle third of a side, the resize is Constrained. 

Zoom (UnZoom)While holding down the CTRL key, click the select mouse button while the cursor is in the tool’s name stripe or outer boundary. 

ExposeClick the select mouse button while the cursor is on the tool’s name stripe or outer boundary. 

HideWhile holding down the SHIFT key, click the select mouse button while the cursor is on the tool’s name stripe or outer boundary. 

In addition, you can use two function keys as even faster accelerators.  To expose a window that is partially hidden, hit the Expose key (normally L5) while the cursor is anywhere in the tool window, not just on the tool’s name stripe or outer boundary.  Or, if the window is completely exposed, use the Expose key to hide it.  Similarly, to close an open window, hit the Open key (normally L7) while the cursor is anywhere in the tool window, not just on the tool’s name stripe or outer boundary.  Or, if the window is iconic, use the Open key to open it.  You can change which keys mean Expose and Open by using setkeys(1).

In many multi-subwindow tools, you can adjust the boundary between two subwindows up or down without changing the overall size of the tool.  While holding down the CTRL key, depress the adjust mouse button over the boundary.  A bounding box is displayed for the subwindow selected.  Adjust the size of that subwindow, exactly as with the Resize operation. 

Startup Processing:  The .suntools File

Unless you override it, suntools will start up with a predefined arrangement of windows.  The default arrangement is specified by the file /usr/lib/suntools.  If there is a file called .suntools in your home directory, that will be used instead.  The −s flag on the command line indicates that the initial window arrangement should be read from a file with a different name.  The −n switch suppresses this start-up processing altogether. 

To create your own .suntools, arrange the screen the way you like, then save the arrangement by running toolplaces and redirecting its standard output to .suntools.  See toolplaces(1) for a description of the format of this file, or take a look at /usr/lib/suntools. 

SunView Defaults

SunView allows you to customize the behavior of tools and packages by setting options in a defaults database (one for each user).  Use defaultsedit(1) to browse and edit your defaults database.  Select the “SunView” category to see the following items:

Walking_menusIf enabled, the Root Window Menu, the Frame Manager Menu, and many tools will use walking menus.  Tools that have not been converted will still use stacking menus.  If disabled, all tools will use stacking menus.  Default value is “Disabled”. 

Click_to_TypeIf enabled, keyboard input will stay in a window until you click the left or middle mouse button in another window.  If disabled, keyboard input will follow the mouse.  Default value is “Disabled”. 

FontYou can change the SunView default font by giving the full pathname of the font you want to use.  Some alternate fonts are in the directory /usr/lib/fonts/fixedwidthfonts.  The previous (2.0 release) default font is /usr/lib/fonts/fixedwidthfonts/screen.r.13.  Default value is null, which gives you the same effect as if you had specified /usr/lib/fonts/fixedwidthfonts/screen.r.11. 

Rootmenu_filename
You can change the Root Window Menu by giving the full pathname of a file that specifies your own menu. See Customizing the Root Window Menu below for details.  Default value is null, which gives you the menu found in /usr/lib/rootmenu. 

Icon_gravityDetermines which edge of the screen (“North”, “South”, “East”, or “West”) icons will place themselves against.  Default value is “North”. 

Icon_close_levelDetermines whether icons will close ahead of or behind other windows and icons.  Default value is “Ahead_of_all”. 

Jump_cursor_on_resize
If enabled, during a resize the cursor will jump to the edge of the window. If disabled, the window edge will move to the current location of the cursor. Default value is “Disabled”.

Audible_bellIf enabled, the “bell” command will result in a beep.  Default value is “Enabled”. 

Visible_bellIf enabled, the “bell” command will cause the screen to flash.  Default value is “Enabled”. 

Embolden_Labels
If enabled, all tool labels are boldface. Default value is “Disabled”.

Root_PatternUsed to specify the “pattern” that covers the Root Window.  “on” means to use the default desktop gray pattern.  “off” means to not use the default desktop gray pattern.  “gray” means to use a 50% gray color on color monitors.  Anything else is the name of a file produced with iconedit(1) which contains an image that is replicated all over the Root Window. Default value is “on”.

After you have set the options you want, click on the Save button in defaultsedit; then exit suntools and restart it. 

Customizing the Root Window Menu

The file called /usr/lib/rootmenu contains the specification of the default Root Window Menu.  You can change the Root Window Menu by creating your own file and giving its name in the Rootmenu_filename item in the SunView Defaults (see above). 

Lines in the file have the following format: The left side is a menu item to be displayed; the right side is a command to be executed when that menu item is invoked.  You can also include comment lines (beginning with a ‘#’) and blank lines.

If you are using stacking menus (“Walking_menus Disabled” in SunView defaults), the menu item must be a string (strings with embedded blanks must be delimited by double quotes).  If you are using walking menus (“Walking_menus Enabled”), the menu item can be a string or the full pathname of an icon file, delimited by angle brackets.  With care, strings and icons can be mixed in one menu. 

There are four reserved-word commands that can appear on the right side. 

EXITExit the suntools program, after user confirmation. 

REFRESHRedraw the entire screen. 

MENUIf you are using stacking menus, a menu is added to the pile with the Root Window Menu.  The menu contents are taken from the filename that follows the MENU command.  You must give the full pathname of the file. 
If you are using walking menus, this menu item is a pull-right item with a submenu. If a filename follows the MENU command, the submenu contents are taken from the filename. Otherwise, all the lines between this MENU command and a matching END command are added to the submenu.

ENDMarks the end of a nested submenu.  The left side of this line should match the left side of a line with a MENU command.  Not valid if you are using stacking menus. 

If the command is not one of these four reserved-word commands, it is treated as a command line and executed.  No shell interpretation is done, although you can run a shell as a command. 

Here is a menu file that demonstrates some of these features:

Quit EXIT

Clock clock −r −f

"Mail reader" mailtool

"More tools" MENU  /usr/foo/me/moretools.menu

"Click to type" swin −c

"Follow mouse" swin −m

"Print selection" sh −c get_selection | lpr

# Only if you are using walking menus:

"Nested menu" MENU

Cmdtool cmdtool

Shelltool shelltool

"Nested menu" END

"Icon menu" MENU

</usr/include/images/textedit.icon>   textedit

</usr/include/images/iconedit.icon>   iconedit

"Icon menu" END

Multiple/Color Displays

The suntools program runs on either a monochrome or color screen.  Each screen on a machine may have its own invocation of suntools running on it.  The keyboard and mouse input devices are shared among multiple screens.  The mouse cursor slides from one screen to another when you move the cursor off the edge of a screen. 

A common multiple display configuration is one monochrome and one color screen.   You could set up an instance of suntools on each screen in the following way:

1.Invoke suntools on the monochrome display by running “suntools”.  This starts suntools on the default frame buffer named /dev/fb. 

2.In a shelltool, run “suntools -d /dev/cgone0 -n &”.  This starts suntools on a color screen named /dev/cgone0. 

3.In a shelltool on the monochrome screen, run “adjacentscreens /dev/fb -r /dev/cgone0”.  This sets up cursor tracking so that the cursor slides from the monochrome screen to the color screen when you move the cursor off the right hand side of the monochrome screen, and back when you move the cursor off the left hand side of the color screen. 

Multiple Desktops on the Same Screen

Given appropriate hardware, the suntools program can be made to run separate desktops on the same screen.  This facility is an extension of the features described in the previous section entitled Multiple/Color Displays.  The Prism is an example of a machine with multiple plane groups that can take advantage of this facility.  Each plane group on a machine may have its own invocation of suntools running on it.  Such an invocation is called a desktop.  The keyboard and mouse input devices are shared among multiple desktops.  The mouse cursor slides from one desktop to another when you move the cursor off the edge of the screen. 

A common multiple desktop configuration for the Prism is one monochrome and one color desktop.   You could set up an instance of suntools on each plane group in the following way:

1.Invoke suntools in the color plane group by running “suntools -8bit_color_only -toggle_enable”.  This starts suntools on the default frame buffer named /dev/fb but limits access to the color plane group. 

2.In a shelltool, run “suntools -d /dev/bwtwo0 -toggle_enable -n &”.  This starts suntools in the overlay plane that is accessed by /dev/bwtwo0. 

3.In a shelltool run “adjacentscreens -c /dev/fb -l /dev/bwtwo0”.  This sets up cursor tracking so that the cursor slides from the monochrome desktop to the color desktop when you move the cursor off the right hand side of the monochrome desktop, and back when you move the cursor off the left hand side of the color desktop. 

Old pre-3.2 applications run on the 8bit_color_only desktop will not appear because they will be writing to the overlay plane.  I.e., don’t run old pre-3.2 applications on an 8bit_color_only desktop. 

There is an application called the switcher that is used as an alternative to adjacentscreens for getting between desktops on the Prism.  Clicking the switcher icon gets you to another desktop using some amusing video wipe type animation.  The switcher can also be used to simply set the enable plane to 0 or 1 if the enable plane get out of wack.  See the man page switcher|(1) for details. 

Generic Tool Arguments

Most window-based applications now take the following arguments in their command lines:

FLAG(LONG FLAG)ARGSNOTES
-Ww (-width)   columns
-Wh (-height)  lines
-Ws (-size)    x yx and y are in pixels
-Wp (-position) x yx and y are in pixels
-WP (-icon_position)x yx and y are in pixels
-Wl (-label)   "string"
-Wi (-iconic)  makes the tool start iconic (closed)
-Wt (-font)filename
-Wn (-no_name_stripe)
-Wf (-foreground_color)red green blue0-255 (no color-full color)
-Wb (-background_color) red green blue0-255 (no color-full color)
-Wg (-set_default_color)(apply color to subwindows too)
-WI (-icon_image)filename(for tools with non-default icons)
-WL (-icon_label)"string"(for tools with non-default icons)
-WT (-icon_font)filename(for tools with non-default icons)
-WH(-help)print this table

Each flag option may be specified in either its short form or its long form; the two are completely synonymous. 

Getting Out

To exit any tool, invoke the Quit command in the Frame Menu as described above.  To exit the entire window system, invoke Exit Suntools in the Root Window Menu as described above.  Make sure that all windows are in a safe condition (for example, editors have written out all changes) first. 

You can exit suntools via the keyboard by typing ^D followed by ^Q.  There is no confirmation.  This facility provides an escape if you inadvertently start suntools without a mouse attached to the system. 

SEE ALSO

Windows and Window-Based Tools: Beginner’s Guide

Some of the applications that run in the SunView environment:

clock(1), cmdtool(1), dbxtool(1), defaultsedit(1), fontedit(1), gfxtool(1), iconedit(1), lockscreen(1), mailtool(1), overview(1), perfmeter(1), perfmon(1), shelltool(1), tektool(1), textedit(1), traffic(1)

Some of the utility programs that run in or with the SunView environment:

adjacentscreens(1), clear_functions(1), get_selection(1), rastps(1), setkeys(1), stty_from_defaults(1), swin(1), switcher(1), toolplaces(1)

ENVIRONMENT

DEFAULTS_FILE
The value of this environment variable indicates the file from which SunView defaults are read.  When it is undefined, defaults are read from the .defaults file in your home directory. 

FILES

~/.suntools
/usr/bin/suntools
/usr/bin/othertools
/usr/bin/get_selection
/usr/bin/selection_svc
/usr/lib/suntools
/usr/lib/rootmenu
/usr/lib/fonts/fixedwidthfonts/∗
/dev/winx
/dev/ptypx
/dev/ttypx
/dev/fb
/dev/kbd
/dev/mouse
/etc/utmp

BUGS

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 Window Menu.  Then invoke the Console item to start a console. 

To improve interactive performance, the kernel should be reconfigured in order to make more memory available for applications.  See the System Manager’s Guide.

With an optical mouse, sometimes the arrow-shaped cursor will not move at start-up; moving the mouse in large circles on its special pad for a few seconds will bring the cursor to life. 

suntools 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. 

On a color display, all of the colors may “go strange” when the cursor is in certain windows.  This is caused by SunView accommodating a particular window’s request for a large number of colors. 

When running multiple desktops, be careful to not have more than one shelltool or cmdtool acting as the console at once.  Kill one console before starting another. 

Sun Release 3.2  —  Last change: 27 January 1986