ControlsDoc.tioga
Bloomenthal, October 8, 1990 12:08 pm PDT
PCEDAR 2.0 — FOR INTERNAL XEROX USE ONLY
Controls
Jules Bloomenthal
© Copyright 1988, 1990 Xerox Corporation. All rights reserved.
Abstract: An interface is provided for the creation of menu buttons, vertical or horizontal sliders, circular dials, a typescript, functions, and a graphics display within a viewer. Placement and sizing of these is semi-automatic. Attention has been paid to ease of interaction. A test program is provided to demonstrate some of the control capabilities.
Created by: Jules Bloomenthal
Maintained by: Jules Bloomenthal <Bloomenthal.pa>
Keywords: controls, sliders, dials, functions, contours, sketches, viewers, interaction.
XEROX   Xerox Corporation
    Palo Alto Research Center
    3333 Coyote Hill Road
    Palo Alto, California 94304

For Internal Xerox Use Only
1. Introduction
Generally, Controls is used to produce a top level viewer within which are a number of optional viewers. These optional viewers are of the following types:
Button:  a menu button.
Typescript: a viewer for messages to/from the user.
Graphics: a viewer for drawing pictures.
Control:  an interactive viewer of one of the following types:
  
  a circular dial or horizontal or vertical slider:
  The sliders or dials may contain optional detent positions, marked by thin
  lines within the control. The control will become detented if the mouse is
  close to the detent position. When detented, the center of the dial or slider
  will display a small circle or square.
  The current value of the control is, optionally, displayed. This displayed
  value may be mouse-selected, and a new value typed; upon a carriage-return,
  the control is set to the typed value, and any proc associated with the control
  is called.
  
  If the control key is depressed while mousing in a dial or slider, the mouse
  input is "fine-tuned;" that is, the resolution of the control is improved by
  approximately ten times.
  
  In its default mode, a dial or slider "traps" mouse actions once a mouse-down
  occurs within the dial or slider. This assists the user in using the control
  without the need to look at to ensure he or she remains within it. The default
  mode is defeated with the UserProfile option: ControlsMouseTrap: FALSE.
  
  a function:
  The user may sketch a function; the left or middle mouse buttons produce a
  freehand curve; the right button connects positions with straight lines. The
  last input value is, optionally, displayed.
  
  a contour:
  The user may sketch a freehand contour; if the end of the contour is close to
  its beginning, then the contour is closed. The contour may be edited by
  redrawing parts of it. Unpredictable results may occur if the direction of
  drawing is reversed while editing the contour.
  
  a sketch:
  The user may make a freehand sketch.
A convenience procedure, OuterViewer, permits an arbitrary number of buttons and controls to be placed within a top level viewer, but only one typescript and one graphics viewer are supported. All subviewers are optional. Generally, OuterViewer positions the buttons at the top, followed in vertically descending order by the typescript, the graphics viewer, and the controls. The controls may be arbitrarily positioned by the client or default positioned by OuterViewer.
The test program, ControlsExamples, demonstrates most of the above features.
2. Software Environment
Bringover -p /Cedar/CedarChest7.0/Top/Controls.df.
3. The Interface
The best description of the procedures and data structures is in Controls.mesa. ControlsCommandsImpl.mesa provides programming examples.
4. Commands
ControlsExamples: A demonstration of all the various control types.
ControlsMouseTest: A test of the mouse functionality.
ControlsSketcher: A program for free-style, by hand, sketching. This is a simple program that does
  not permit adjustment of color or line thickness, but it allows the user to place
  free-hand strokes into a viewer, as an alternative to the more formal, editable
  and repeatable style of Gargoyle. One may delete backwards, one at a time, the
  accumulated strokes. ControlsSketcher doesn't produce the prettiest artwork,
  but it may be of use now and then. The results may be sent to an Interpress file,
  and subsequently incorporated into a document, like this:
[Artwork node; type 'Artwork on' to command tool]
ControlsSimpleViewer: Just like SimpleViewer command.
ControlsTopLevel: An example of a top level control.
ControlsVernier: A separate viewer containing a fine-tuning control for the most recently moused
  control, if the control is a dial or slider. The vernier will adjust the value of the
  control and, if NOT control.truncate, call any proc associated with the control.