| Tools and Techniques This section of the manual concerns itself with
tips, tools and techniques for building applications.
Panel
Menus
Panel
Menus are a simple means for constructing dialogs that request information from the user.
For SilverC development, this is the primary method for interface with the user. For
SilverEngine and SilverPlus, these menus offer a quick alternative to a the construction
of a custom dialogs.
There are three steps are required to use
a panel menu:
- The program executes pm_initialize
. This establishes the title of the panel and initiates the assembly process.
- Lines of the panel are sequentially
assembled using the pm-family of functions. Each of these functions corresponds to
a specific type of panel input. Among these are text entry, menu selection, color
selection, and icon selection. The order in which these functions are called determines
the order in which items appear in the panel.
- The program executes pm_execute.
This displays the panel and allows the user to input or edit items in the panel. When the
user signals completion, pm_execute returns to the program. Updated panel values
are then available.
There are 15 functions that define
different types of panel input. Here is an overview of these functions:
| Function
|
Description |
| pm_box
|
Provides a
button that will display a popup box. The item is then selected from the popup box. |
| pm_box2
|
Similar to pm_box
. |
| pm_color
|
Prompts for a
color value. The color value may be entered directly or may be selected via a button from
a color bar, color palette, or a color slide. |
| pm_comment
|
Inserts a line
of descriptive text into the panel. |
| pm_displacement
|
Allows entry
of an xyz-displacement. The displacement may be marked interactively via a button. |
| pm_distance
|
Allows entry
of a distance. The distance may be marked interactively via a button. |
| pm_double
|
Allows entry
of a real number. |
| pm_font
|
Allows
selection of a TrueType or SilverScreen font. |
| pm_formatted
|
Allows entry
of a real number. The number is displayed in any of the notations supported by
SilverScreen. |
| pm_generic
|
This is a
generalized selection entry that allows selection of items from 15 categories. |
| pm_icon
|
Provides a
button that will display a set of icons. The selected icon provides a value for the item. |
| pm_icon2
|
Similar to pm_icon
. |
| pm_integer
|
Allows entry
of an integer value. |
| pm_menu
|
Allows
selection of an item from a menu. The item is selected by pointing at the desired item. |
| pm_rgb
|
Prompts for a
RGB value. The RGB maybe entered directly, or may be selected via a button from a color
bar, color palette, or a color slide. |
| pm_text
|
Allows entry
of a text string. |
| pm_xyz
|
Allows entry
of an xyz-coordinate. The coordinate may be marked interactively via a button. |
Here is a short example
illustrating the use of panels:
// Establish panel title
pm_initialize ( "Machine Specification" );
// Initial values
machine_size = 1;
width = 10.0;
machine_color = color_blue;
// Items to appear in panel
pm_menu ( "Machine size", "Small Medium Large", &machine_size );
pm_double ( "Machine width", &width, 1 );
pm_color ( "Machine color", &machine_color );
// Display panel and edit
if ( pm_execute () )
ss_command ("note User signaled successful completion");
else
ss_command ("note User terminated by cancellation");
The initial values for machine_size,
width, and machine_color will be used to initialize the
panel. Values will be returned in these variables if pm_execute returns TRUE.
Generic
Data Sets
The
generic data sets represent a wide assortment of data that is used in SilverScreen. Each
generic set has a corresponding constant that is defined in silver.h . The
following is the list:
| Defined |
Constant Data Set |
| GN_DRW |
drawing names |
| GN_FNT |
font names |
| GN_IGS |
IGES files |
| GN_DXF |
DXF files |
| GN_EX |
executable programs |
| GN_SF |
script files |
| GN_ENV |
private environments |
| GN_ANN |
annotation environments |
| GN_SDF |
screen definitions |
| GN_MLB |
model libraries |
| GN_MODEL |
library.model names |
| GN_LIGHT |
light names in current
drawing |
| GN_IMODEL |
internal model names in
current drawing |
| GN_GROUP |
named groups in current
drawing |
| GN_VIEW |
named views |
| GN_SCREENS |
named screens |
| GN_PATTERN |
patterns for a given library |
| GN_LINE_STYLE |
line styles of a given
library |
| GN_FILE |
tokens in a text file |
| GN_FILE2 |
tokens in a text file |
| GN_MODEL2 |
model names for a given
library |
| GN_XLB |
execution library |
| GN_XLB_ENTRY |
entries in execution library |
| GN_FILE_NAME |
wild-carded file names |
| GN_FNT_ENTRY |
font names |
| GN_PRP |
property library |
| GN_PRP_ENTRY |
entries in property library |
There are several ways that these
sets can be used.
The prompt_generic function
displays a pop-up panel containing all names in a given data set. The user may then select
one of these. This selection is then returned to the calling program. The following is an
example:
if ( prompt_generic("Select light source",buf,GN_LIGHT,"")
)
ss_command ("note The selected light source is %s", buf);
else
ss_command ("note No light source selected");
The pm_generic
function adds a generic item to a panel menu. The button associated with this item gives
the user the opportunity to select an item from the set. The following is an example:
buf[0] = 0;
pm_generic ( "Light source name", buf, GN_LIGHT, "" );
collect_generic is a function that assembles all items of a
generic set into a list. This list may then be accessed through the get_generic
function:
collect_generic ( GN_DRW, "" );
for ( i = 1 ; ; ++i )
{
if ( ! get_generic ( i, buf ) )
break;
ss_command ( "note item %d in the list is %s", i, buf );
}
The generic data
set is specified by a constant and an auxiliary string. In most cases, the auxiliary
string is empty (as shown in the examples above). The sets that require a non-empty string
are the following:
| GN_PATTERN |
name of the pattern library |
| GN_LINE_STYLE |
name of the line style
library |
| GN_FILE |
name of the file |
| GN_FILE2 |
name of the file |
| GN_MODEL2 |
name of the library |
| GN_XLB_ENTRY |
name of the execution
library |
| GN_FNT_ENTRY |
name of the font library |
For GN_PATTERN and GN_LINE_STYLE,
only "silver" should be used since this is the only library presently
supported.
GN_FILE requires
the name of an ASCII text file containing space-delimited tokens. An example of such a
file is the following (note that the end-of-line character counts as whitespace):
bill sue
mary kjel
henry
jack jill jim
GN_FILE2
requires the name of an ASCII text file where each line is an element in the data set.
Example:
Jean Paul Sartre
Plato
Bertrand Russell
David Hume
GN_MODEL2
requires the name of the model library from which the model names are to be selected.
SilverScreen Transformation Matrices
In
SilverScreen, a transformation matrix is a 4x4 array of doubles. One can view a
transformation matrix as a function that maps points from one space to another space,
typically representing some combination of the scaling, rotation and translation
operations. For a point (x1,y1,z1), and a transformation matrix T, the
mapping to (x2,y2,z2) is defined by the matrix multiplication
[x2 y2 z2 1] = T. [x1 y1 z1 1]
Transformation matrices may be
multiplied together to produce composite transformations. For example, if the matrix T
maps (x1,y1,z1) to (x2,y2,z2), and if the matrix S maps (x2,y2,z2)
to (x3,y3,z3), then the matrix product T . S will map (x1,y1,z1)
to (x3,y3,z3).
Most commonly, matrices are multiplied to
produce composite transformations. The chain of multiplications begins with the unity
matrix, a matrix that has the value one in each diagonal element, and the value zero in
all other elements. This matrix, if used to transform the point (x1,y1,z1), will
map the point onto itself. Thus the unity matrix is, in effect, a null transformation.
A typical operation performed with
matrices is the following:
A polygon with points p1, p2,
p3 is to be scaled to one-half its size by scaling about the point p1. Here
we assume p1 = (x1,y1,z1), p2 = (x2,y2,z2), and p3 = (x3,y3,z3).
- Initialize the matrix T to be the
unity matrix.
- Construct a translation matrix S
that translates all points through a displacement (-x1,-y1,-z1). The effect of this
transformation is to map the point p1 to (0,0,0), and to map the other points to (x2 - x1,y2 -
y1,z2 - z1) and (x3 - x1,y3 - y1,z3 - z1).
- Multiply the matrix T by the matrix
S.
- Construct a new translation matrix S
that scales all points by a factor of 1/2.
- Multiply the matrix T by the matrix
S.
- Construct a new translation matrix S
that translates all points through a displacement (x1,y1,z1). This transformation
effectively moves the points back to their original location.
- Multiply the matrix T by the matrix
S.
The result of these operations is a
composite transformation matrix that will scale all points in the polygon about the point p1.
There are three types of transformation
matrices that are explicitly supported by the SilverScreen API: translation, rotation, and
scaling. Each of these functions performs two operations: First, a transformation matrix
is created; second, the transformation matrix is multiplied into a composite matrix.
The functions that perform these
operations are:
- translation: tm_translate
- scaling: tm_scale_x , tm_scale_y,
and tm_scale_z
- rotation: tm_rotate_x, tm_rotate_y,
and tm_rotate_z
The scaling and rotation functions are
designed so that rotation and scaling can be performed independently on each axis.
Here is the code that will produce the
composite transformation matrix described in steps 1 through 7 above.
double t[4][4];
SS_XYZ p1,p2,p3;
SS_XYZ q1,q2,q3;
tm_clear (t); // Initialize t to the unity matrix
tmp.x = -p1.x;
tmp.y = -p1.y;
tmp.z = -p1.z;
tm_translate ( &tmp, t ); // Translate (-p1.x,-p1.y,-p1.x)
scale_x( 0.5, t ); // Scaling by
0.5
scale_y( 0.5, t );
scale_z( 0.5, t );
tm_translate ( &p1, t ); // Translate (p1.x,p1.y,p1.x)
// After these statements have been executed, the
// transformation matrix can be used to transform
// the points to their new locations. This is done by
// the function tm_transform. Here we can transform
// p1, p2, and p3 to q1,q2, and q3 by:
tm_transform ( &p1, &q1, t );
tm_transform ( &p2, &q2, t );
tm_transform ( &p3, &q3, t );
In
addition to the simple transformation functions described above, SilverC contains a number
of specialized transformation tools.
The function tm_cspace will
produce a transformation matrix that maps points from world space to the current
construction space. The following will transform a w-space point p to a
c-space point q:
tm_cspace ( tm );
tm_transform ( &p, &q, tm );
To transform a
c-space point back to w-space, the function tm_inverse is used. The inverse
function produces a matrix which maps in the opposite direction of the original matrix.
The following will first get the w-space to c-space matrix tm. Then, tm_inverse
is used to get the c-space to w-space matrix tm_inv. The final statement transforms
the c-space point p1 to the w-space point p2.
tm_cspace ( tm );
tm_inverse ( tm, tm_inv );
tm_transform ( &p1, &p2, tm_inv );
For a more concrete
example, consider the following problem. For a point p, we wish to locate a point q
that is 2 units from p in the direction of the positive y-axis of c-space. Although this
description, may sound complicated, this operation is, in fact, fairly common in geometric
programming. The solution is:
double tm[4][4],tm_inv[4][4];
SS_XYZ p,pp,q;
tm_cspace ( tm );
tm_inverse ( tm, tm_inv );
tm_transform (&p,&pp,tm); // result: pp in c-space
pp.y += 2.0; // add c-space displacement
tm_transform ( &pp, &q, tm_inv ); // result: q in w-space
The function w_to_c
implicitly uses the w-space to c-space transformation matrix to transform a point from
w-space to c-space. For a point p in w-space, the following produces the
corresponding point q in c-space:
w_to_c ( &p, &q );
This is exactly
equivalent to:
tm_cspace ( tm );
tm_transform ( &p, &q, tm );
There is also an
inverse function c_to_w that transforms a c-space point to w-space. The following
function makes use of w_to_c and c_to_w to move the cursor on the xy-plane
of c-space:
SS_XYZ wxyz,cxyz;
SS_XYZ new_position;
double zspace;
cv_set ( CV_VERY_QUIET, 1 );
// Get initial location of cursor
wxyz.x = worldx;
wxyz.y = worldy;
wxyz.z = worldz;
// Transform wxyz in w-space to cxyz in c-space
w_to_c ( &wxyz, &cxyz );
// Move location to xy-plane of c-space
cxyz.z = 0.0;
zspace = snap_spacing();
for ( ; ; )
{
switch ( inchar () )
{
case LARROW: cxyz.x -= zspace; break;
case RARROW: cxyz.x += zspace; break;
case UARROW: cxyz.y += zspace; break;
case DARROW: cxyz.y -= zspace; break;
case ESCAPE: return;
default: continue;
}
// Find corresponding w-space location
c_to_w (&cxyz, &new_position);
// Reposition the cursor
ss_command ( "at %z", &new_position );
}
The function tm_to_2d
will produce a transformation matrix that maps three non-collinear points to the xy-plane.
For the points p1, p2, and p3, the tm_to_2d transformation
will map p1 to the origin, p2 to a point on the positive x-axis, and p3
to a point on xy-plane with a positive y-coordinate. This function provides a powerful
tool for solving 3D problems in 2D.
Suppose, for example, that the points p1,
p2, and p3 form a triangle somewhere in 3D space. To compute the area of
this triangle, we can do the following:
SS_XYZ p1, p2, p3;
SS_XYZ q2, q3;
double area;
tm_to_2d (&p1, &p2, &p3, tm );
tm_transform ( &p2, &q2, tm );
tm_transform ( &p3, &q3, tm );
area = 0.5 * q2.x * q3.y;
Colors
and RGB
SilverScreen
is fully RGB-based. In all drawings, colors are stored as RGB values rather than color
numbers. When a drawing is loaded, the RGB values are converted to color numbers that are
appropriate to the video display.
When a color is selected for a surface or
a line, the user may express this color as an RGB value or as a color number. If a color
number is selected, then this number is internally converted to an RGB value.
The advantage of this approach is clear:
SilverScreen drawings are independent of any color limitations imposed by the video device
on which they were created. A surface, even on a 16-color system, may be given the RGB
color of r13g120b93. On a 16-color system, this color may be interpreted as the
color 3 (cyan). If the drawing is later displayed on an RGB video device, the color will
be accurately portrayed as r13g120b93 .
For video systems that do not have RGB
display capability, SilverScreen uses a base palette of either 16 or 256 colors, dependent
on the capabilities of the video device. Each color in SilverScreen is simultaneously
maintained both as an RGB value and as a color from this palette.
A special data type, RGB, defined
in silver.h, is used to store this color information. The data type is an int, 32
bits in length. Eight bits are used to store the base color and 24 bits are used to store
the RGB. There are several macros that are defined in silver.h that allow each of
these values to be extracted:
RED_COLOR (rgb)
GREEN_COLOR (rgb)
BLUE_COLOR (rgb)
THE_COLOR (rgb)
MAKE_RGB (color,red,green,blue)
The SilverScreen
API also provides functions that convert color to RGB and RGB to color.
color_to_rgb for a
given base color, the function returns the RGB components of the color.
rgb_to_color for an RGB,
this function returns the base color appropriate for the current video device.
Icons
The
functions described in this section provide a means to creating an icon-based dialog.
These functions provides a relatively easy way to create a dialogs that are functionally
similar to a toolbars.
Icons are supported with the icon,
panel_icon, and pm_icon functions. The icon function displays the
icons in the menu area, while the panel_icon function displays the icons at the
center of the screen within a panel. The pm_icon function allows an icon item to be
added to a panel menu, and invoked via a button. In this case, the icons appear in a
pop-up panel in the center of the screen. Other related functions include icon2, panel_icon2,
pm_icon2 , display_icon and clear_icons .
The use of the icon functions is
relatively straightforward. The greater effort is the preparatory design work.
Icons are stored in what we shall call an
icon drawing. Here are the characteristics of an icon drawing:
- An icon drawing is a normal SilverScreen
drawing.
- Icon entities are stored at the root of
the icon drawing.
- Icon entities are named icon1, icon2,
icon3, and so on.
- An icon entity may be a block, an object
or text.
- A block icon may contain any combination
of blocks, objects, or text entities.
- Icon entities may be placed anywhere in
the drawing provided that the zoom extents of the entities do not overlap.
- The scale of the icon entities is not
important since zooming will occur prior to the display of the icon.
- The background color of the drawing will
be the background color of the individual icons.
- The border color of the drawing will be
the border color of the individual icons.
- Surface fills and patterns may be enabled
for the drawing. This will cause fills and patterns to be displayed for all icons.
- The presence of entities that are not icon
entities will not affect the display of icons except if these entities overlap the extents
of icon entities.
It is often attractive to have different
background colors for different icons. By (8) above, it would seem that all icons would
have the same background color. However, there is a way to work around this.
Before creating any of the icons, create
an object, say obj1. Since this object is the first entity in the drawing
structure, it will be displayed first. Later, after all of the icons have been drawn, obj1
can be used to provide background color for individual icons. This is done by enabling
fill and by placing colored polygons in obj1 that enclose the zoom extents of an
icon. Since the polygon will be filled before the icon is drawn, the color of the polygon
will be the background color for the icon.
The automatic zooming described in (7) is
sometimes a convenience and sometimes a burden. Let us consider the one of the troublesome
aspects of scaling.
Suppose that we wish to construct an icon
drawing that has two icons, both of which are text. The first icon is to contain
"YES" and the second "NO". We place the two lines in a drawing, and
rename them so that "YES" is icon1 and "NO" is icon2.
When these icons are displayed, we find that the letters of "NO" are larger than
the letters of "YES". This is due to the automatic scaling that independently
zooms each entity.
In order to produce icons that are
uniformly scaled, a scaling object must be introduced for each icon. The purpose of the
scaling object is to establish the physical extents of the icon. In the above case, we
would create two blocks, icon1 and icon2. Within these blocks, we would
place two identically sized polygons, and then place the lines of text within the extents
of these polygons. Once this is done, the scaling of the icon is dependent on the size of
the scaling objects rather that the size of the text. To prevent the scaling objects from
being displayed as part of the icon, their visibilities can be disabled. Alternatively,
they can be given the color of the background.
As a practical matter, it is often
convenient to create a single icon block, icon1, which contains a scaling object.
This block can then be matrix copied to produce as many icon blocks as desired.
Custom
Menus
SilverScreen
allows the use of custom menus. These menus, in appearance and in functionality, are very
similar to the SilverScreen menus. The menus can be displayed using the built-in function menu.
Using this function, a program can display a menu and receive the user's response.
The construction of custom menus begins
with a source file that defines the structure of the menus. This file is then compiled to
produce a .CMF file. It is the .CMF file that is used by the menu function.
Sample Custom Menu File
heading="Sample menu"
{
ceiling "CEILING Ceiling commands"
{
build "BUILD Build ceiling" 10
display "DISPLAY Display ceiling" 20
}
floor "FLOOR Floor commands"
{
build "BUILD Build floor" 30
display "DISPLAY Display floor" 40
}
quit "QUIT Exit" 50
}
This is a simple
menu consisting of three major menu selections (ceiling, floor, quit).
The ceiling and floor selections have secondary menus, while the quit selection does not.
The quoted strings are single line descriptors that appear at the top of the screen when
the corresponding selection is highlighted.
The numbers at the right are returned to
the program if the user selects that item. Note that these numbers appear only at the leaf
level of the menu tree.
Let us assume that above source menu is
stored in the file SAMPLE1. The file is compiled using the following SilverScreen
command:
CUSTOM-MENU COMPILE <source menu file>
This will produce,
in this example, a custom menu file SAMPLE1.CMF, which will be stored in the
current directory. The CMF file may now be used by the menu function:
switch ( menu ( "sample1" ) )
{
case 0: // The user entered ESCAPE
break;
case 1: // The user entered a function key or control key
switch ( ich )
{
case F1:
...
case F2:
...
}
break;
case 10: // CEILING BUILD
...
case 20: // CEILING DISPLAY
...
case 30: // FLOOR BUILD
...
case 40: // FLOOR DISPLAY
...
case 50: // QUIT
...
}
The menu
command returns 0, 1, or a number corresponding to a menu selection. The return value 0
means that the user chose to enter Esc rather than select an item from the menu.
The return value 1 means that the user pressed a function or control key. When this
occurs, the key is made available in the predefined variable ich. The other numbers
correspond to a successful menu selection by the user.
.CMF files may be stored in executable
libraries. This is particularly convenient when an application system has many such files.
Structure of a
Custom Menu File
A custom menu file has the
following format:
[HEADING = <string>]
[TITLE = <string>]
[MACRO = <string>]
MENU_UNIT
where:
MENU_UNIT ==> { MENU_ITEMS }
MENU_ITEMS ==> [ MENU_ITEMS ] MENU_ITEM
MENU_ITEM ==> <id> <string> MENU_UNIT ||
<id>
<string> <number> ||
<id>
<string> ||
*
The ‘*’
menu item denotes that a menu separator is to appear at that location in the menu.
Control Variables
SilverScreen
has a set of control variables that control the run-time environment. These variables may
be modified by the cv_set function. The current settings of control variables may
be examined by the cv_get function.
A number of these variables are
read-only, that is, they may not be used as an argument to cv_set .
The control variables are references
using defined constants that appear in silver.h. The following is a description of
the variables. Variables that are marked as read-only may not be used with cv_set :
| Variable
Name |
Description |
|
| CV_BREAK |
This variable
can be used to enable/disable the user's ability to interrupt execution by Control-Break.
Pressing the Control-Break key can be used to break out of a program only if this variable
is on. |
|
| CV_COMMANDS |
This variable
controls the display of commands. Commands will be displayed only if this variable is on. |
|
| CV_DEFER_PAINTING |
This variable
controls drawing repaint procedure: normally SilverScreen draws to the refresh buffer, and
then updates to the screen buffer at the end of repaint (default value of 1). This
variable allows the default behavior to change, providing more or less immediate screen
update visibility. Possible values
repaint procedure
0 Paint to screen and to refresh
buffer at the same time.
1 Paint to refresh buffer, then at the
end of repaint, update screen via BitBlt (this is the default value)
2 Paint to refresh buffer, but update to
screen via BitBlt every 0.25 seconds. |
|
| CV_DISPATCH_SYSCHAR |
This variable
controls whether the SilverScreen input system allows Windows system keys (WM_SYSCHAR)
to be passed back to SilverScreen apllications via inchar/nextkey. A value
of 0 means that system keys are returned to the inchar caller, otherwise they are passed
through to MFC for default handling. The default value is 0. |
|
| CV_ENABLE_CLOSE |
This variable
enables or disables the System window close button on the SilverScreen frame window. The
window close button will be displayed if the variable is non-zero, and will not be
displayed if the variable is set to zero. |
|
| CV_ENABLE_DLL_IDLE_PROCESSING |
This variable
controls whether SilverScreen calls idle processing in its own frame idle routine, when
the CWinApp-derived class returned via AfxGetApp is not SilverScreen (i.e.
is a DLL). The default value is 1, which means that DLL idle processing is enabled. |
|
| CV_ERRORS |
This variable
controls the display of command error messages. These messages will be displayed only if
this variable is on. This variable can be used in combination with the predefined variable
ss_errno and the function error_text to intercept SilverScreen error
messages. |
|
| CV_FILL_ENABLED |
cv_get(CV_FILL_ENABLED)
returns 1 if fill is currently enabled, and otherwise 0. |
read only |
| CV_GRID |
cv_get(CV_GRID)
returns 1 if the grid is currently enabled, and otherwise 0. |
read only |
| CV_ICON_AREA_WIDTH |
This variable
controls the pixel width of the icon area used in the icon and icon2 functions. |
|
| CV_JUMP_MENU |
This variable
controls the availabity of the popup Jump Menu when picking a point. If this variable is
set to 0, the Jump Menu will not be available. |
|
| CV_MESSAGES |
This variable
controls the display of messages that appear at the bottom of the screen. (i.e.,
"Printing ...", "Sweeping ...") These messages will be displayed only
if this variable is on. |
|
| CV_MODIFIED |
cv_get(CV_MODIFIED)
returns 1 if the current drawing is modified, and otherwise 0. |
read only |
| CV_NOTATION |
cv_get(CV_NOTATION)
returns a number corresponding to the current setting for notation |
|
| CV_NOTES |
If this
variable is on, then NOTE and the WAIT commands will be handled normally. If
the variable is off, these commands will be ignored. |
|
| CV_ORTHO_SNAP |
cv_get(CV_ORTHO)
returns 1 if ortho-snap is currently enabled, and otherwise 0. |
read only |
| CV_PAINT_ONE_WINDOW |
This variable
controls the ability of the program to force repainting to occur in only the current
window or in all windows. |
|
| CV_PASSTHROUGH_CMDUI_ENABLE |
This variable
determines whether SilverScreen will pass down ON_UPDATE_COMMAND_UI notifications
to the DLL via the SilverScreen-defined message WM_CMDUI_ENABLE message. If set to
1, the update command UI messages are relayed to the DLL, otherwise, they are enabled
automatically. The default is 0. This is documented more fully in the SilverPlus manual. |
|
| CV_PATTERNS_ENABLED |
cv_get(CV_PATTERNS_ENABLED)
returns 1 if patterns are currently enabled, and otherwise 0. |
read only |
| CV_QUICK_MENU |
When selecting
points, entities or primitives, the CTRL-LEFT event will normally allow the user to change
the view. This will be disallowed if this variable is set to 0. |
|
| CV_REDRAW_LOCAL |
When the
SilverScreen window is resized, SilverScreen will normally redraw the contents of the
drawing windows. This automatic redraw can be disabled by setting CV_REDRAW_LOCAL
to 0. When this is done, a refresh event (C_REDRAW or C_RESIZE) notifies that a resize has
occurred. |
|
| CV_REFRESH |
This variable
controls display of the graphic area of the screen. If this variable is on, then the
results of SilverScreen commands will be displayed on the screen; otherwise they will not.
cv_set(CV_REFRESH, 1) is functionally equivalent to the SilverScreen command REFRESH
ENABLE. cv_set(CV_REFRESH,0) is equivalent to REFRESH OFF. |
|
| CV_RESIZE_PERMITTED |
This variable
by be used to permit/disallow the resizing of the SilverScreen window. Only when the
variable has the value 1 will the user will be able to alter the window’s size. |
|
| CV_REUSE_ICON |
This variable
controls the clearing of the icon area after icon prompting. It is useful to reduce screen
updates when the same icon is used repeatedly. By setting this variable to 1, the icon
area will not be cleared after the prompting has occurred |
|
| CV_SINGLE_STEP |
This is a
debugging variable that can be used to halt execution whenever a command is executed. If
this variable is on, commands will be displayed and the system will await a key from the
keyboard. |
|
| CV_SNAP |
cv_get(CV_SNAP)
returns 1 if snap is currently enabled, and otherwise 0. |
read only |
| CV_TRACE_INFO |
This variable
controls the display of the trace information in the XYZ toolbar. This information appears
during interactive drawing and when points and displacements are being marked. If the
variable is on, and if the toolbar is visible, then the information is displayed;
otherwise it is not. |
|
| CV_UNITS |
cv_get(CV_UNITS)
returns a number corresponding to the current setting for units of measure |
read only |
| CV_VERY_QUIET |
This is a
composite variable that simultaneously sets CV_COMMANDS and CV_MESSAGES . |
|
| CV_WINDOW_BORDER |
This variable
controls the border color that is used for the current window. If the variable is on, the
current window is displayed using the color white; otherwise the normal window color is
used. |
|
Initial Setting at Start of Execution
| CV_COMMANDS |
ON |
| CV_ERRORS |
ON |
| CV_MESSAGES |
ON |
| CV_SINGLE_STEP |
OFF |
| CV_BREAK |
ON |
| CV_TRACE_INFO |
ON |
| CV_REFRESH |
ON |
| CV_NOTES |
ON |
| CV_PAINT_ONE_WINDOW |
OFF |
| CV_REUSE_ICON |
OFF |
| CV_WINDOW_BORDER |
OFF |
The following is an example of the
use of CV_ERRORS:
cv_set ( CV_ERRORS, 0 ); // Disable error display
ss_command ( "redraw object \obj1 %d", the_color );
if ( ss_errno )
{
// Handle the error
}
cv_set ( CV_ERRORS, 1 ); // Re-enable error display
System
Variables
SilverScreen
system variables are named storage objects that are global to the SilverScreen system.
They are useful for communicating between programs. They may also be used to retrieve the
results of certain SilverScreen commands (see below).
Three types of system variables are
allowed: value, text and XYZ. Value variables are used to hold a single floating point
number (double). Text variables are used to hold a text string (char). XYZ
variables are used to hold the location of a point in 3D space. In order to support XYZ
variables, the data type struct _xyz is predefined by the C compiler. System
variables may be accessed via the load_variable function or the sysvar
functions.
In SilverScreen, system variables are
created, destroyed and assigned by using LANGUAGE VARIABLE commands:
- They can be assigned a value by the VARIABLE
ASSIGN script command. The command has three forms, each corresponding to a data
type that can be associated with a system variable:
variable assign <name>
value <value>
variable assign <name> text <string>
variable assign <name> xyz <xyz location>
-
Groups of variables can be assigned
values by means of a VARIABLE LOAD command. This command is related to the VARIABLE
SAVE command. The latter command saves all currently active variables in disk file
with extension .VAR. These variables can then be reloaded with the VARIABLE LOAD
command. See the SilverScreen manual for further details on these commands.
- Groups of variables may also be assigned
values with the VARIABLE V-EDIT command. This command is essentially a variant of
the VARIABLE LOAD command. For further information on this topic, see the
SilverScreen manual and the section on the V-EDIT command.
- Variables can be assigned values as a
result of a MEASURE command. There are roughly a dozen variables that are set by
this command to reflect the result of a measurement. A listing of these variables appears
at the end of this section.
- Variables retain their values until they
are unassigned with the VARIABLE UNASSIGN command, or until the CLEAR
command is issued.
To use system variables in a program, the
variable must first be defined by using a VARIABLE ASSIGN command, or by loading a
group of variables from disk using the VARIABLE LOAD command.
A number of SilverScreen commands produce
results that are assigned to various system variables. The commands that currently produce
system variable results all belong in the GEOMETRY MEASURE family.
The following table describes the
variable created, the SilverScreen command that creates it and the data type of the
variable created (the GEOMETRY prefix is not included in the command description):
| Variable |
SilverScreen Command |
Data Type |
| $angle |
MEASURE ANGLE |
value |
| $area |
MEASURE AREA |
value |
| $centroid |
MEASURE CENTROID |
XYZ |
| $dimx |
MEASURE DIMENSIONS |
value |
| $dimy |
MEASURE DIMENSIONS |
value |
| $dimz |
MEASURE DIMENSIONS |
value |
| $distance |
MEASURE DISTANCE |
value |
| $length |
MEASURE LENGTH |
value |
| $ixx |
MEASURE MOMENT
CENTROID |
value |
| $ixx |
MEASURE MOMENT
ORIGIN |
value |
| $ixy |
MEASURE MOMENT
CENTROID |
value |
| $ixy |
MEASURE MOMENT
ORIGIN |
value |
| $ixz |
MEASURE MOMENT
CENTROID |
value |
| $ixz |
MEASURE MOMENT
ORIGIN |
value |
| $moment |
MEASURE MOMENT
AXIS |
value |
| $moment |
MEASURE MOMENT
ENTITY AXIS |
value |
| $volume |
MEASURE VOLUME |
value |
Here is an example where the
MEASURE command is used to measure the area of a polygon:
double area;
...
ss_command ("measure area primitive polygon \\arm\\bolt4.26");
sysvar_value ("$area",&area);
ss_command ("note The area of \\arm\\bolt4.26 is %f",area);
V-EDIT
command
The
VARIABLE V-EDIT command is a means for creating tab dialogues where large
numbers of variables can be edited. The V-EDIT command is a close cousin to the
panel menu family of functions (that is, pm_execute). However it differs from these
functions in two respects:
- V-EDIT uses only system variables
(rather than standard C variables).
- At the start of an editing session, V-EDIT
can retrieve initial values from a .VAR file.
- At the conclusion of the editing session, V-EDIT
can store the edited values in a .VAR file.
- V-EDIT will permit an unlimited
number of variables to be edited in the same session.
- The values of the system variables stored
in the .VAR file can later be loaded by the VARIABLE LOAD command.
V-EDIT is
particularly useful in establishing a set of system parameters that are to be used during
execution.
The appearance and contents of the are
specified in a V-EDIT source file. A sample V-EDIT file is shown below:
title = "Sample V-EDIT file"
input = "sample1"
output = "sample1"
* ""
* "!0Editing of variables"
* ""
m $var1 "Variable 1" "one" "two" "three"
n $var2 "Variable 2" "one" "two" "three"
t $var3 "Variable 3" "hello"
f $var4 "Variable 4" 1.23
i $var5 "Variable 5" 6
* ""
title
specifies text that is to appear at the top of the screen during editing. input
specifies the .VAR file that is to be used to initialize system variables. output
specifies the .VAR file to which the system variables are to be written when the editing
session concludes. Both input and output are optional.
Starting on line 4, there is a line by
line specification of the items that are to appear in the menu. The first character in
each line identifies the type of information that is contained on the line:
| Character |
Meaning |
| *!0 |
indicates the beginning of a
tab section of the tab dialogue. Text from this line will be used in the tab. |
| * |
indicates that the line
contains descriptive text. |
| m |
indicates that the line
contains a selection of items, one of which is to be selected by the user. |
| n |
indicates that the line
contains a selection of items, one of which is to be chosen by the user. |
| t |
indicates that the user may
enter text. |
| f |
indicates that the user may
enter a real number. |
| i |
indicates hat the user may
enter an integer. |
Except for the line containing
descriptive text, each line is associated with a system variable. The variable name
appears immediately after the line code. The line code determines variable type and the
value that will be assigned at the conclusion of the editing session:
| Character |
Meaning |
| m |
the variable is a text
variable; it will be assigned the string corresponding to the selected item. |
| n |
the variable is a value
variable; it will be assigned the ordinal number corresponding to the selected item. |
| t |
the variable is a text
variable; it will be assigned the string that appears on the line. |
| f |
the variable is a value
variable; it will be assigned the value that appears on the line. |
| i |
the variable is a value
variable; it will be assigned the value that appears on the line. |
Following the variable name is a
string of display text. For menu lines, the last entry is the set of menu items. Initial
values appear on the remaining lines.
Further information about the V-EDIT
command can be found in the SilverScreen Reference Manual.
Multi-Language Applications: Tfiles
Support
for multi-language applications through the use of tfiles. Typically the developer
maintains a set of messages, prompts and other text used to communicate with the user.
This text may be stored in a single file, the tfile, for access by message number. To move
to another language, only the text in the tfile needs to be translated, preserving message
numbers. By accessing different tfiles, the application can move readily back and forth
among languages.
SilverScreen supports multiple language
applications with a set of functions that allow the creation and use of external text
files (tfiles). The tfile uses a text numbering system that associates each string of text
with a number. By using the appropriate number, a line of text can be retrieved from the
tfile.
Here is a description of the functions
that support files:
| tfile_make |
This function
reads a text file and produces a tfile. |
| tfile_open |
This function
opens a tfile and prepares it for text retrieval. If another tfile was open, it is
automatically closed. |
| tfile_close |
This function
closes the current tfile. |
| tfile_gets |
Using a text
number, this function retrieves a text string from the current tfile. |
These functions provide the ability
to change language at any time. This is consistent with SilverScreen's ability to change
languages at a single keystroke.
The tfile_make function permits
developers to build their own tfiles from an input ASCII text file. The format of the
input file is as follows:
1 First line of text
2 Second line of text
3 Third line of text
...
The syntax for the
text file is:
- All lines must begin with an integer
(associated message number).
- The integer must be followed by
a single space and the message text.
- The lines must be arranged in ascending
sequence.
- No breaks are permitted in the sequence.
The following is an example of how to use
tfiles. Assume that there are two input text files: english.txt and spanish.txt
; we will call the resultant tfiles english.tf and spanish.tf .
To build the tfiles:
if ( ! tfile_make ( "english.txt", "english.tf" ) )
// Error of some kind
if ( ! tfile_make ( "spanish.txt", "spanish.tf" ) )
// Error of some kind
To start up in English:
char msg1[100];
if ( ! tfile_open ( "english.tf" ) )
// Error of some kind
if ( ! tfile_gets ( msg1, 1 ) )
// Error of some kind
display_text( msg1 );
. . .
To switch to
Spanish:
char msg1[100];
if ( ! tfile_open ( "spanish.tf" ) )
// Error of some kind
if ( ! tfile_gets ( msg1, 1 ) )
// Error of some kind
display_text( msg1 );
. . .
To close out tfile
usage:
tfile_close ();
Notice that there
is no need to close a previous tfile before opening another -- that is done automatically
by tfile_open .
Keyboard and Pointer
Keyboard
and pointer events are handled in an event queue that is internal to SilverScreen. In a
program, events are removed from the queue with the inchar function. The event may
be a keystroke, a pointer movement, or a pointer button press. If the queue is empty when inchar
is called, then the function waits until an event occurs.
A second function, nextkey, may be
used to view the event that is at the front of the queue without removing this event. If
the queue is empty, nextkey does not wait for an event to occur, but instead,
returns 0.
The combination of nextkey and inchar
can be used to clear the queue. First, nextkey checks to see if an event is in the
queue. If so, then inchar is used to remove the event. Here is the code:
while ( nextkey () )
inchar ();
Events
handled in SilverScreen, both keys and pointer events, are defined in sskeys.h.
This header file defines the function keys, the control keys, and the pointer button and
motion events.
Programs are able to monitor the location
of the arrow and to determine its location. Here are the functions:
| pointer_mode |
sets the pointer mode |
| pointer_locate |
locates the arrow at a screen coordinate
|
| pointer_char_locate |
locates the arrow at a position on a
line |
| pointer_position |
returns the screen coordinates of the
arrow |
| pointer_char_position |
returns the line and position of the
arrow |
The events received from the
pointing device are dependent on a pointer mode that can be set with pointer_mode.
There are three modes: 0, 1 and 2.
Mode 0 disables the pointer so that no
pointer events occur. Mode 1 places the pointing device into key translation mode. When in
this mode, pointer movement is translated to keyboard arrow movement, and certain button
events are translated to keyboard keys. Mode 2 causes all pointer events to be returned.
It is in mode 2 that pointer_locate and pointer_position functions are used.
The following section illustrates the use
of several of the pointer functions:
pointer_mode ( 2 );
pointer_char_locate (20,20);
for ( ; ; )
{
switch ( inchar () )
{
case ESCAPE:
...
case M_BOTH:
...
case M_LEFT:
pointer_char_position ( &line,
&position );
...
case M_RIGHT:
pointer_char_position (
&line,&position );
...
}
}
}
The pointer is
placed in mode 2, located at position 20 of line 20, and made visible. The program then
reads events with inchar, identifying Esc from the keyboard and the three
mouse events.
Executable Libraries
Executable
libraries allow a consolidation of the various files that are included within an
application. The following file types can be included in an executable library:
- Script files (.SF)
- Executable programs (.EX)
- Custom menus (.CMF)
- Icon drawings (.DRW)
- ASCII text files
The notation "library>file"
is used to refer to a file within a library. For example: iconlib>file1.
Script files and executable programs can
be executed from a library with a command of the form:
execute libx>prog1
Custom menus can be
loaded from a library with the menu function or with a command of the form:
custom-menu load libx>menu4
Icon menus can be
displayed from a library using the icon, icon2, and display_icon
functions. Icons can also be used in panel_icon, panel_icon2, pm_icon
, and pm_icon2 .
Image files can be displayed from a
library with a command of the form:
snapshot view screen libx>snap1
Direct Pointer Variables
The
get_direct_pointer function is used to retrieve a direct pointer to the specified
SilverScreen variable. Currently, the only variable supported is accessed by DP_LIGHT_LIST,
which returns a pointer to the first LIGHT_NODE structure in a drawing (DP_LIGHT_LIST
is defined in silver.h ; the LIGHT_NODE structure is defined in ss_nodes.h).
See the get_direct_pointer in the Run-Time Library Reference.
Copy Protection
SilverScreen
uses the Sentinel hardware lock. Each lock has a unique serial number that is recorded in
the lock. The serial number can be accessed by the function get_version .
Developers are often faced with
protecting new versions and upgrades of their software. The purpose of this section is to
suggest a method whereby a developer may use the serial number of the hardware lock to
secure their software.
The method involves computing a pass
number based on the version number of the software and the serial number of the hardware
lock. It assumes that the developer faithfully records the serial numbers of the packages
on which their software is authorized to run. It also requires that the developer issue
pass numbers with each release or update. These pass numbers are based on the serial
number stored in the hardware lock.
Consider the following function:
int get_passnumber( int serial, int version )
{
int i;
for ( i = 1 ; i <= version ; ++i )
serial *= 1315731;
return serial % 10000;
}
Based on a serial
number and a version number, this function will generate a 5-digit pass number. For
version 1, 2, ..., n, the function will generate a set of pass numbers that are seemingly
unrelated to one another.
The mechanism for protecting the software
is simple: Before the software is sent to the user, the developer records the serial
number of the user's hardware lock. Using this serial number, and the version number of
their software, the developer computes a pass number that he gives to the user.
When the user executes the developer's
program, the program asks that the user enter a pass number. The program, using its access
to the serial number, computes a pass number using the function shown above. If this
number matches the number entered by the user, then access to the program is granted.
This basic approach can be enhanced by
storing correctly entered pass numbers on disk. In this way, the user would be required to
enter the pass number only once.
B-tree Databases
A
b-tree database consists of two files: an index file and a data file. The index file is
used to organize information that is stored in the data file. The index file contains a
set of keys that are maintained in ascending sequence. Associated with each key is a
record number. This record number identifies the record in the data file that is
associated with the key.
The keys in the index file can be
accessed sequentially or randomly. For a given key, the associated record number can be
used to retrieve the data file information that is related to that key.
Two or more b-trees may be based on a
single data file. This allows the information in the data file to be organized in several
different ways. For a file containing employee information, one might construct one index
to access employee information by employee number, while creating another index to access
the information by employee name.
Here is a summary of the b-tree
functions:
B-tree open, close and flush:
| bt_open |
Open a b-tree |
| bt_close |
Close a b-tree |
| bt_flush |
Flush all b-trees to disk |
File creation functions:
| bt_create_data |
Create a data file |
| bt_create_tree |
Create an index file |
Index file functions:
| bt_delete |
Delete an entry |
| bt_find |
Find a key |
| bt_find2 |
Find key/record |
| bt_insert |
Insert a new entry |
| bt_next |
Retrieve the next entry |
| bt_previous |
Retrieve the previous entry |
| bt_set_first |
Set read marker to beginning
of index |
| bt_set_key |
Set read marker to a
specific key |
| bt_set_last |
Set read marker to end of
index |
| bt_update |
Update an entry |
Data file functions:
| bt_erase |
Erase (remove) a record |
| bt_read |
Read a record |
| bt_store |
Store (create) a new record |
| bt_write |
Write (update) a record |
B-trees are created by the bt_create_data
and bt_create_tree functions. These functions create an empty data file and an
empty index file respectively.
When a data file is created, the record
size must be specified. If text information is to be stored, then record size should be
the length of the longest possible string. If structure information is stored, then record
size should be the size of the structure (sizeof <structure name>).
Before a b-tree can be accessed, it must
be opened with bt_open. This function returns a b-tree handle. Index file functions
use this handle to identify the index file, while data file functions use the handle to
identify the data file. If two b-trees use a common data file, then either handle can be
used to identify the data file.
Quick
Advice
The
purpose of this section is to describe a number of techniques that have proven themselves
to be helpful in application development.
- The hierarchical drawing structure is an
important organizational tool. There is a strong relationship between the organization of
the drawing and the organization of the information about the drawing. A block can be used
to store information about the group of entities contained in the block. Information about
an elementary entity can be stored with that entity.
- Tags are a better means for storing
information than schemas. They are faster to access and do not depend on an external
library.
- The names given to entities in a drawing
are important. Suppose that a drawing consists of rooms where each room is a block.
Further suppose that each room contains walls and doors, where each door is a block
containing hinges, a doorknob and a panel.
- If all of the doorknobs are given a common
prefix, then a wildcard can be used to isolate doorknobs (i.e., to make doorknobs visible
and all other entities invisible). If common prefixes are also used for the other
entities, then it is a simple matter to make walls and doors visible and hinges and
doorknobs invisible.
- Consider the following sequence of
commands:
sweep linear polygon \obj1.3 points 0,0,0 0,0,-10
name box
view select isometric front right top
zoom object \box
hide object \box hidden-line
When these commands are executed, the
user would first see a sweep operation, followed by a change of view, followed by a zoom
to the object, followed by hidden-line removal; probably a lot of unnecessary screen
activity.
The control variable CV_REFRESH can be used with cv_set to control screen
refreshes. When refresh is off, commands will execute without disturbing the contents of
the screen. The following avoids unnecessary screen refresh:
cv_set (CV_REFRESH,0)
ss_command ( "sweep linear polygon \\obj1.3 points 0,0,0 0,0,-10 name box");
ss_command ("view select isometric front right top");
ss_command ("zoom object \\box");
cv_set (CV_REFRESH,1);
ss_command ("hide object \\box hidden-line");
-
It often occurs that an object of a
certain type, say a doorknob, is to be picked by the user. The function to accomplish this
is pick_entity. Unfortunately, pick_entity is not particularly clever. This
function will pick the nearest visible object whether it be a doorknob or a light bulb.
A nice solution is the following:
cv_set ( CV_REFRESH, 0 );
ss_command ("isolate object !knob*");
if ( pick_entity ("Pick doorknob",E_OBJECT,path) )
...
else
...
ss_command ("isolate reset");
cv_set (CV_REFRESH, 1 );
The trick is to
isolate those objects that are candidates for selection without disturbing the screen.
Once the pick has been made, isolation can be reset, again without disturbing the screen.
record_visibility is also a useful
function in this context.
- Many applications require a specific
annotation environment. This can be handled by loading a private annotation environment.
|
