sl-gms function referencesldownloads.sl.com › docs › c++dev › 6.2x › pdffiles › fref ›...

SL-GMS® Function Reference

SL Corporation®

OBJECT-ORIENTED

GRAPHICAL MODELING SYSTEM

Version 6.2a- 26 May 2006

Part Number FREF-360526

The information in this document is subject to change without notice and shouldnot be construed as a commitment by the Sherrill-Lubinski Corporation. TheSherrill-Lubinski Corporation assumes no responsibility for any errors that mayappear in this document.

The software described in this document is furnished under a license and may beused or copied only in accordance with the terms of such license.

This software is based in part on the work of the Independent JPEG Group.

Symbol Factory TM artwork is licensed from Software Toolbox, Inc.

SL-GMS Function ReferenceThis manual is for use only in connection with the described software and may notbe used for any commercial purpose or copied, distributed, sold, displayed,modified, published, or posted in whole or in part without the prior writtenpermission of Sherrill-Lubinski Corporation.

SL-GMS, SL Corporation, the SL Logo, and all Sherrill-Lubinski product namesreferenced in this manual are trademarks or registered trademarks of theSherrill-Lubinski Corporation; any unauthorized use of these marks is strictlyprohibited. All trademarks and registered trademarks referenced in this documentare property of their respective companies.

SL-GMS (6.2x) 26 May 2006Configuration: C62a1_360526

Copyright (c) 1987-2006 Sherrill-Lubinski Corporation. All Rights Reserved.

LIMITATIONS ON USE

Use, duplication, or disclosure by the U.S. Government is subject to restrictions asset forth in the Technical Data - Commercial Items clause at DFARS252.227-7015, the Rights in Data - General clause at FAR 52.227-14, and anyother applicable provisions of the DFARS, FAR, or the NASA FAR supplement.

SL CORPORATION240 Tamal Vista Blvd.

Corte Madera, CA 94925

CUSTOMER SUPPORTPhone 800.548.6881 (inside U.S.)

415.927.8400Fax 415.927.8401E-mail [email protected]

5/26/06 v6.2x

Table of Contents
1. SL-GMS Function Reference
Absolute move......................................................................................... 5Absolute rotation ..................................................................................... 8Absolute scale ......................................................................................... 10Apply Transformation ............................................................................. 13Background ............................................................................................. 15Bitmap object .......................................................................................... 20Center point ............................................................................................. 24Circle object ............................................................................................ 28Class query .............................................................................................. 30Clear ........................................................................................................ 32Clone ....................................................................................................... 33Closure attribute ...................................................................................... 34Color........................................................................................................ 36Current object .......................................................................................... 40Cursor ...................................................................................................... 43Datasource — ".dat" files........................................................................ 51Datasource — class ................................................................................. 52Datasource — Instance............................................................................ 54Datasource — Lists ................................................................................. 57Datasource — messages.......................................................................... 59Directories and paths ............................................................................... 62Display, erase, highlight.......................................................................... 65Dump....................................................................................................... 68Dynamics — double-buffering................................................................ 69Dynamics — DynProps/RenamedVariables ........................................... 70Dynamics — erasure ............................................................................... 78Dynamics — initialize, update, restore, end ........................................... 81Dynamics — optimization ...................................................................... 85Dynamics — query and set Variable Definition attributes ..................... 90Dynamics — query Variable References ................................................ 94Dynamics — Variable Definition Table attached to Models .................. 96Dynamics — variables ............................................................................ 107Edge width attribute ................................................................................ 118Events — create ...................................................................................... 120Events — miscellaneous ......................................................................... 130Events — query....................................................................................... 132

SL-GMS Function Reference iVersion 6.2a- 26 May 2006

Events — timer........................................................................................ 138Events — Xt and X applications ............................................................. 140Extent ...................................................................................................... 143Fill direction and fill percent attributes ................................................... 148Filled........................................................................................................ 151Find file ................................................................................................... 153Find object............................................................................................... 157Font Name Index..................................................................................... 160Free object ............................................................................................... 162General transformation — absolute ........................................................ 164General transformation — relative.......................................................... 167GISMOs — initialization ........................................................................ 169GISMOs — processing ........................................................................... 170Gradient fill attribute............................................................................... 171GraphAxis object..................................................................................... 174GraphTrace object ................................................................................... 178Grid object............................................................................................... 181Group object ............................................................................................ 185Group object - redrawing ........................................................................ 189Internationalization — localization files ................................................. 190Internationalization — String object ....................................................... 208Line object............................................................................................... 214LinkRef object......................................................................................... 215Main — SL-GMS main functions ........................................................... 223Marker — custom.................................................................................... 229Marker — object ..................................................................................... 233Marker — size attribute........................................................................... 234Message tracing....................................................................................... 236Model — object....................................................................................... 237Model — save, get, merge ...................................................................... 240Model — save, get from pseudo-files ..................................................... 244Model — user header string .................................................................... 258Model Instance (ModInst) object ............................................................ 261Model Instance (ModInst) — caching .................................................... 269NDC (Normalized Device Coordinates) ................................................. 273Object — name........................................................................................ 275Object — owner ...................................................................................... 276

SL-GMS Function Reference iiVersion 6.2a- 26 May 2006

Object — parts ........................................................................................ 278Performance optimization ....................................................................... 281Pie object ................................................................................................. 282Plotted Points........................................................................................... 284Point Lists................................................................................................ 287Point Lists — replace .............................................................................. 290Point object.............................................................................................. 292Polygon object......................................................................................... 296PostScript ................................................................................................ 298Projects .................................................................................................... 306Query user ............................................................................................... 308Radius set and get.................................................................................... 310Raster image of objects — save and restore ........................................... 311Raster image of View — save, restore, create ........................................ 314Raster Operation Mode attribute ............................................................. 316Rectangle object ...................................................................................... 319Reference Point ....................................................................................... 322Relative move.......................................................................................... 325Relative rotation ...................................................................................... 328Relative scale........................................................................................... 330Relative transformation ........................................................................... 333Reset transformation ............................................................................... 335Sector object ............................................................................................ 337Sectors, Pies, Splines — miscellaneous .................................................. 340Set transformation ................................................................................... 342Setup, quit, close SL-GMS...................................................................... 344SL-GMS Installation Directory — query................................................ 346SL-GMS Libraries — version, configuration, date................................. 347Spline object ............................................................................................ 350State — attributes .................................................................................... 352State — class ........................................................................................... 356State — initialization............................................................................... 359State — Instance...................................................................................... 363State — mark and reset ........................................................................... 369State — messaging .................................................................................. 371State — miscellaneous ............................................................................ 375State — query.......................................................................................... 378

SL-GMS Function Reference iiiVersion 6.2a- 26 May 2006

State — variables .................................................................................... 382State — variables, set and query attributes ............................................. 386Stress attribute ......................................................................................... 389Style attribute .......................................................................................... 391SubModel List ......................................................................................... 394Text — attributes..................................................................................... 396Text — object.......................................................................................... 401Text — query attributes........................................................................... 407Text Rectangle — constraint attribute .................................................... 409Traps — signal handling ......................................................................... 411Update ..................................................................................................... 415User-defined functions ............................................................................ 418UserData and UserWord ......................................................................... 422View — miscellaneous............................................................................ 424View — object ........................................................................................ 426View — WC-window and Viewport....................................................... 431View — zoom and pan............................................................................ 434Visibility and detectability attributes ...................................................... 436Workstation/Window — attribute changes ............................................. 439Workstation/Window — background color ............................................ 448Workstation/Window — bitplanes.......................................................... 451Workstation/Window — coordinate conversion..................................... 460Workstation/Window — events .............................................................. 462Workstation/Window — object .............................................................. 469Workstation/Window — Window query ................................................ 480Workstation/Window — Workstation query .......................................... 482World Coordinates .................................................................................. 487

Index

Function Name Index

SL-GMS Function Reference ivVersion 6.2a- 26 May 2006

Version 6.2a- 26 May 2006

Sherrill−Lubinski

SL-GMS Function Reference

How to use this manual

This manual provides information concerning the use of the SL-GMSRun-time Functions as part of C language programs.

This manual is divided into many sections, each containing a group ofrelated functions. Each section is comprised of the following parts:

This manual is designed for quick and versatile reference:

SUMMARY a brief explanation about the use of the group of

functions in a particular section

NAME a list of names of the functions described in the section

SYNTAX the call format, including required argument types

DESCRIPTION a detailed discussion about the use of the functions

DIAGNOSTICS (optional) a discussion about anomalies

EXAMPLE (optional) a sample code fragment illustrating the use of the described function(s)

SEE ALSO (optional) useful cross-reference information

SL-GML COMMANDS (optional) the SL-GML commands which correspond to the functions discussed

Table of Contents alphabetical listing of section titles; each section title is a conceptual title for a group of related functions

Index alphabetical listing of specific concepts and function names which are cross-referenced in this manual

Function Name Index alphabetical listing of function names contained in this manual

SL-GMS Function Reference 1

SL-GMS Function Reference 2Version 6.2a- 26 May 2006

SL-GMS data types

In addition to the normal C types used as arguments or returned from func-tions, SL-GMS defines several additional data types. The following arethe pointer types:

The ".h" files for all SL-GMS objects are distributed in the lib directory.

Pointer Type Attribute Descriptionid class pointer to arbitrary objectidPoint class pointer to a Point object

xy coordinatesidLinkRef class pointer to a LinkRef object

successor pointerreference pointer


SL-GMS Run-time Functions: return values

SL-GMS functions return a 1 when they are successful, and a 0 when theyhave failed. In the case of those functions that return id pointers, a "0"(nil) pointer is returned for failure, and an object pointer is returned for suc-cess.

SL-GMS Run-time Functions: naming conventions

The SL-GMS Run-time Functions have:

• function names beginning with gms

• function names beginning with something else, such as pnt orref.

The gms*( ) functions operate on the graphics portion of the SL-GMS sys-tem itself, while the others are support functions primarily used for con-structing Points, and Lists, which are used as arguments for the gms*( )set of functions.

Programming notes

Ordering of include filesSL-GMS application programs written in C begin with include files whichmust be listed in the following order:

1. "gms.h"

2. <other SL-GMS include files>

3. <system include files>

The file "gms.h" must be included in all SL-GMS application programs.This file contains most of the object definitions required by SL-GMS func-tions. The type id is defined as a generic pointer to an object, for exam-ple. Functions returning non-integer values are also declared through thisheader file.

Applications utilizing customized States in SL-SMS must include the file"gms_sms.h". Applications utilizing SL-DMS must include the file"gms_dms.h".


EXPORT/IMPORT macro definitionsMost SL-GMS objects are defined as type id. In the statement below, avariable to hold a View object is created.

EXPORT id v_main = 0;

The location of this statement outside of a function makes it available foruse by other source code modules. The word EXPORT is a C languagemacro definition convention used in SL-GMS to clearly indicate that a vari-able is available for use by other source modules. On most platforms, theabove statement is equivalent to

id v_main = 0;

The statement below creates a reference to an SL-GMS State object that isdefined in another source code module.

IMPORT id appl_top;/* States in the application */

The word IMPORT is a C language macro definition convention used inSL-GMS to clearly indicate that a variable is defined in another sourcemodule. On most platforms, the above statement is equilvalent to

extern id appl_top;

Application command-line argument processingThe gmsWsProcArgs( ) function is used in an application program to pro-cess any options given in the command line. The section Workstation/Win-dow — object on page 469 describes the gmsWsProcArgs( ) function. Itis also called by the gmsMainInit( ) function, as documented in the sectionMain — SL-GMS main functions on page 223.

The gmsWsPsProcArgs() function may be called to process com-mand-line PostScript options. The section PostScript on page 298 providesmore information.

Absolute move

Absolute move

SUMMARY

APPLY an absolute move transformation

NAME

gmsAMove2( ), gmsLAMove2( ), gmsMAMove2( ), gmsAMoveX( ), gmsAMoveY( ), gmsLAMoveX( ), gmsLAMoveY( ), gmsMAMoveX( ), gmsMAMoveY( )

SYNTAX

intgmsAMove2 (obj, point)

d obj;idPoint point;

intgmsLAMove2 (objlist, point)

idLinkRef objlist;idPoint point;

intgmsMAMove2 (point)

idPoint point;

intgmsAMoveX (obj, mx)

id obj;int mx;

intgmsAMoveY (obj, my)

id obj;int my;


Absolute move

intgmsLAMoveX (objlist, mx)

idLinkRef objlist;int mx;

intgmsLAMoveY (objlist, my)

idLinkRef objlist;int my;

intgmsMAMoveX (mx)

int mx;

intgmsMAMoveY (my)

int my;

DESCRIPTIONThese functions define absolute move transformations. Absolutetransformations replace any current transformation matrix. The objectis erased, the transformation applied, and the object is redrawn. Theerase and redisplay occur the next time an update pass occurs —immediately if Immediate Update Mode is set.

The gmsAMove2( ) function operates on an individual object, while thegmsLAMove2( ) function operates on a List of objects. ThegmsMAMove2( ) function sets a modal offset transformation, whichapplies to all objects subsequently created. The point argumentspecifies the location to which the object is moved, and must be apointer to a Point object.

With the gmsAMoveX( ) and gmsAMoveY( ) functions, the othercoordinate is set to 0. The mx and my arguments specify the distancethat the object is to be translated. The user is responsible for scalingthe integer argument by the World Coordinate Scale Factor usinggmsWValue( ).

The gmsAMove2( ) function, or gmsLAMove2( ), should be used tomove an object in both the x and y directions. Calling gmsAMoveX( )and then gmsAMoveY( ) produces a different result than calling


Absolute move

gmsAMove2( ) because an absolute move forces an object to moveback to its initial position before applying the move. ThegmsAMoveX( ) function should be used to move an object in only the xdirection and gmsAMoveY( ) should be used to move an object in onlythe y direction.

EXAMPLETo move an object 10 units in the x direction, the gmsWValue( )function is used to convert World Coordinate units to InternalCoordinates (integer representation).

gmsAMoveX (obj, gmsWValue(10.0));

SEE ALSOgmsRMove2( ), gmsLRMove2( ), gmsCRMv2( ), gmsMRMove2( ),gmsXTran( ), gmsRefPoint( )

The gmsXTran( ) function is used to apply existing gmsWValue( )transformations to the object’s Points. The gmsRMove2( ) function isused to combine the translation with existing transformations.

The Reference Point for an object is set by the gmsRefPoint( )function.

SL-GML COMMANDSname amove x y

name amovex x

name amovey y


Absolute rotation

Absolute rotation

SUMMARY

set an absolute rotation

NAME

gmsARotZ( ), gmsLARotZ( ), gmsMARotZ( )

SYNTAX

intgmsARotZ (obj, angle)

id obj;double angle;

intgmsLARotZ (objlist, angle)

idLinkRef objlist;double angle;

intgmsMARotZ (point, angle)

idPoint point;double angle;

DESCRIPTIONThese functions define absolute z-axis rotation transformations.Absolute transformations replace any current transformation matrix.The object is erased, the transformation applied, and the object isredrawn. The erase and redisplay occur the next time an update passoccurs — immediately if Immediate Update Mode is set.

The gmsARotZ( ) function operates on an individual object, while thegmsLARotZ( ) function operates on a List of objects. The rotation


Absolute rotation

angle is a double argument specified as degrees to rotatecounterclockwise.

The gmsMARotZ( ) function sets a modal rotation transformation whichapplies to all objects subsequently created. The point argument is thecenter of rotation and must be a a pointer to a Point object. If theargument is nil, the Point (0,0) is assumed.

SEE ALSOgmsRRotZ( ), gmsLRRotZ( ), gmsCRRotz( ), gmsMRRotZ( ),gmsXTran( ), gmsRefPoint( )

The gmsXTran( ) function is used to apply existing transformations tothe object’s Points, or gmsRRotZ( ) is used to combine the translationwith existing transformations.

The Reference Point for an object or List of objects is set by thegmsRefPoint( ) function.

SL-GML COMMANDname arotz angle


Absolute scale

Absolute scale

SUMMARY

set an absolute 2D scale transformation

NAME

gmsAScale( ), gmsLAScale( ), gmsMAScale( ), gmsAScaleX( ),gmsAScaleY( ), gmsLAScaleX( ), gmsLAScaleY( ),gmsMAScaleX( ), gmsMAScaleY( ), gmsCASca2( )

SYNTAX

intgmsAScale (obj, sxy)

id obj;double sxy;

intgmsLAScale (objlist, sxy)

idLinkRef objlist;double sxy;

intgmsMAScale (point, sx, sy)

idPoint point;double sx;double sy;

intgmsAScaleX (obj, sx)

id obj;double sx;

intgmsAScaleY (obj, sy)

id obj;double sy;


Absolute scale

intgmsLAScaleX (objlist, sx)

idLinkRef objlist;double sx;

intgmsLAScaleY (objlist, sy)

idLinkRef objlist;double sy;

intgmsMAScaleX (point, sx)

idPoint point;double sx;

intgmsMAScaleY (point, sy)

idPoint point;double sy;

intgmsCASca2 (point, sx, sy)


DESCRIPTIONThese functions define absolute scale transformations. Absolutetransformations replace any current transformation matrix. The objectis erased, the transformation applied, and the object is redrawn. Theerase and redisplay occur the next time an update pass occurs —immediately if Immediate Update Mode is set.

The gmsAScale( ) function operates on an individual object, while thegmsLAScale( ) function operates on a List of objects. ThegmsMAScale( ) function sets a modal scale transformation whichapplies to all objects subsequently created.

The x and y scale factors must be double arguments. If x or y is notspecified, it is set to 1.0. The point argument is the center of scaling


Absolute scale

and must be a pointer to a Point object. If the argument is nil, the Point(0,0) is assumed.

The gmsCASca2( ) function applies to the creation of future Clones orInstances.

The gmsAScale( ) function (or gmsLAScale( )) should be used toscale an object in both the x and y directions. Calling gmsAScaleX( )and then gmsAScaleY( ) produces a different result than callinggmsAScale( ) because an absolute scale forces an object to scaleback to its initial size before applying the scale. The gmsAScaleX( )function should be used to scale an object in only the x direction andgmsAScaleY( ) should be used to scale an object in only the ydirection.

SEE ALSOgmsRScale( ), gmsLRScale( ), gmsCRSca2( ), gmsMRScale( ),gmsXTran( ), gmsRefPoint( )

The gmsXTran( ) function is used to apply existing transformations tothe object’s Points, or gmsRScale( ) is used to combine the translationwith existing transformations.

The Reference Point for an object or List of objects is set by thegmsRefPoint( ) function.

SL-GML COMMANDSname ascale x y

name ascalex x

name ascaley y


Apply Transformation


SUMMARY

apply the transformation to the Points of an object; apply an object’stransformation one level deep

NAME

gmsXTran( ), gmsLXTran( ), gmsXTran1( ), gmsLXTran1( )

SYNTAX

intgmsXTran (obj)

id obj;

intgmsLXTran (objlist)

idLinkRef objlist;

intgmsXTran1 (obj)

id obj;

intgmsLXTran1 (objlist)

idLinkRef objlist;

DESCRIPTIONThese functions apply the transformation that is attached to an object(or to each object in a List of objects) to the Points that make up theobjects. The gmsXTran( ) function operates on an individual object,while the gmsLXTran( ) function operates on a List of objects.

The objects are not erased and redrawn since no change occurs in theirappearance or position.

When transformations are applied to objects, a representation of thetransformation (a matrix) is stored with the object. The Points that



define an object are not modified so that multiple transformations do notinduce incremental errors in the Points.

Storing the transformation matrix around requires overhead which canbe eliminated by applying the transformations directly to the Pointsusing the gmsXTran( ) functions. Often this is done after a Model hasbeen made with SL-DRAW2 or SL-DRAW to reduce the storageoverhead associated with the Model.

In some cases the application of the tranformation has no effect. Forexample, if a Rectangle is rotated, applying the rotation transformationto the two defining Points of the Rectangle is not permitted because theoperation would completely change the Rectangle.

The gmsXTran1( ) function applies an object’s transformation matrix toits sub-objects one level deep. This function is used when a Group isfreed without destroying its parts. The Group object may have atransformation applied that also applies to its parts. If a Group objectis freed, its transformation must be applied to the objects in its PartsList, or those objects are redisplayed where they were created beforebeing transformed as a Group.

The gmsLXTran1( ) function performs the gmsXTran1( ) functionalityfor each object in a List of objects.

SEE ALSOgmsDeGroup( ), gmsQPointList( )

SL-GML COMMAND[name] xtran


Background

Background

SUMMARY

set a Model’s background flag; query a Model’s background flag

NAME

gmsBackgrFlag( ), gmsQBackgrFlag( )

SYNTAX

intgmsBackgrFlag (model, flag)

id model; /* Model */int flag; /* background flag = G_ON/G_OFF */

intgmsQBackgrFlag (model)

id model;

DESCRIPTIONThe gmsBackgrFlag( ) function sets a Model’s background flag. If thebackground flag is set to G_ON, the Model erases objects in the fillcolor of the first object in the Model, if the object is filled. The colorused by the Model to erase objects is called the background color. Ifthe first object is not filled, or there are no objects in the Model, thebackground color is set to the Workstation/Window background color(refer to the section Workstation/Window — background color on page448).

The background color is used as the erase color for all objects in theModel except for parts within a SubModel Instance which has its ownbackground color. To change the background color, the fill color of thefirst object in the Model must be changed.

Usually the first object in the Model is a Filled Rectangle that covers theentire workspace. This is the background object on top of which otherobjects are drawn and erased. Normally, objects are erased using color


Background

0. If the background object is not also color 0 (white), “holes” are left asobjects are dynamically changed.

An example of using the background flag is illustrated below. Theneedle representing the value of a variable moves over the “face” of themeter. The “face” of the meter is a large rectangle. Because it is thefirst object in the Model, it is the background object. Therefore, thebackground color of the Model is set to the same color as the “face” ofthe meter. With the background flag set to G_ON, the needle erases inthe color of the meter “face” as shown in Figure 1.

Figure 1.Model’s background flag set to G_ON and background color set to same color as the “face” of the meter

However, if the Model’s background flag is set to G_OFF, each time theneedle moves it is erased in color 0 (white), and “holes” are left in the“face” of the meter marking the previous positions of the needle. Thisis illustrated in Figure 2. When the needle moves to 50, a white line


Background

appears at 0 because the needle erased in white on the greybackground.

Figure 2.“Hole” in meter “face” with Model’s background flag set to G_OFF

The background object can also be made invisible. In the Modelshown in Figure 3 the first object in the Model is a large yellow rectangleand therefore the background color is yellow when the background flagis set to G_ON.

Figure 3.A sample Model with background flag on

With the background flag set to G_ON, the red circles, using yellow asthe erase color, will leave yellow “holes” in the grey rectangles at the

yellow

grey

red


Background

old position as the circles are moved to a new position. This is shownin Figure 4.

Figure 4.Yellow “holes” left in old positions as red circles are moved

In order to have the red circles erase in the color grey, the first objectmust have a Fill color of grey. Since the first object in the presentModel is a large yellow rectangle, another object (e.g., a largerectangle) with a Fill color of grey must be created and made the firstobject in the Model using the Back Of All option of the Order Pull-DownMenu in SL-DRAW2. In addition, since this grey object is only beingcreated so it can set the background color and it is not to be seen, itmust be made invisible using the Vis Off option of the ConvertPull-Down Menu.

The background flag may be set on Models and SubModels to providedifferent background colors in different portions of a Model. If aSubModel is created with the background flag set to G_ON and it isthen Instanced into a top-level Model which also has the backgroundflag set to G_ON, the objects within the SubModel are erased using thebackground color of the SubModel, but the SubModel Instance iserased using the background color of the top-level Model.

newposition

old position


Background

In Model A, shown in Figure 5, the background flag is set to G_ON and therefore the needle is erased in the background color of Model A as it is rotated. In addition, both SubModels B and C have the background flag set to G_ON. Therefore, the triangle in SubModel B erases in the background color of SubModel B as it moves and the circle in SubModel C erases in the background color of SubModel C as it moves.

Figure 5.Model “A” with SubModels “B” and “C”

If a background is not specified for a SubModel, the objects are erasedin the background color of the parent Model.

In SL-DRAW2, the background flag is toggled ON and OFF by clickingthe Backgr button in the Color Attribute Control Panel. When thebackground flag is ON, the Backgr button becomes selectable. Tochange the background color of the Model (i.e., the fill color of the firstobject in the Model), click the appropriate color in the Color AttributeControl Panel when the Backgr button is highlighted. Both the colorbar to the right of the Backgr button and the fill color of the first objectin the Model will change to the selected background color.

The gmsQBackgrFlag( ) function queries a Model’s background flag.

MODEL A

SubModel B SubModel C


Bitmap object

Bitmap object

SUMMARY

create a Bitmap object; set the tranformation flag for a Bitmap object

NAME

gmsBitmap( ), gmsQRastOp( ), gmsBitmapFlag( ),gmsLBitmapFlag( ), gmsMBitmapFlag( ), gmsQBitmapFlag( )

SYNTAX

idgmsBitmap (name, filename, point)

char *name;char *filename;idPoint point;

intgmsQRastOp (bitmap)

id bitmap;

intgmsBitmapFlag (obj, flag)

id obj; /* Bitmap object */int flag; /* G_BTM_NO_TRANS or

G_BTM_TRANS_IMPULSE */

intgmsLBitmapFlag (list, flag)

id list; /* List of Bitmap objects */int flag; /* G_BTM_NO_TRANS or

G_BTM_TRANS_IMPULSE */

intgmsMBitmapFlag (flag)

int flag; /* G_BTM_NO_TRANS orG_BTM_TRANS_IMPULSE */


Bitmap object

intgmsQBitmapFlag (obj)

id obj; /* Bitmap object */

DESCRIPTIONThe gmsBitmap( ) function creates Bitmap objects. The name isoptional; a null string may be used as an argument. point positions thelower left corner of the Bitmap’s extent in the current Model.

On the X platform, filename is an X Window dump file created with thegmsVuRFile( ) function or an X Window utility. For the Win32platform,1 filename is a Windows Bitmap file created with thegmsVuRFile( ) function or with a utility such as Paint.

On X platforms, the gmsBitmap( ) function will look for filename with a".xwd" extension and then filename with a ".i" extension. The first filethat matches is loaded.

On Win32 platforms, the gmsBitmap( ) function will look for filenamewith a ".bmp" extension and then filename with a ".i" extension. Thefirst file that matches is loaded.

Bitmap objects are displayed by combining the Bitmap’s raster imagewith the raster image beneath the Bitmap. The manner in which theimages are combined depends upon the Raster Operation Mode (orBitmap Write Mode).

Bitmap objects can be moved or scaled but they cannot berotated. Bitmap objects are drawn by copying the raster image to theWorkstation (there is currently no way to modify this raster image torotate). Bitmaps are used to provide fast update and display of staticimages.

The gmsQRastOp( ) function returns a Bitmap object’s rasteroperation.

The gmsBitmapFlag( ) function sets a permanent bitmap flag on aBitmap object. Possible values for flag are:

1. Win32 refers to a platform with a 32-bit architecture running Microsoft Windows NT or Windows 95.


Bitmap object

Setting G_BTM_TRANS_IMPULSE causes a Bitmap to store aReference Extent on itself on the next extent update pass. ThisReference Extent is set to be the Internal Coordinate (IC) extent of theBitmap. It is analogous to the lower-left and upper-right corner Pointsthat define a Rectangle. This fixes the size of the Bitmap relative toother objects in the Model. When created, this reference is dependentupon any transformation in the Graphical Modeling Hierarchy (in theAppendix entitled SL-GMS System Organization of the SL-GMSAdvanced Tutorial).

Examples of transformations2 would include the following:

• scaling objects in the Model

• resizing the Window-Manager window the Bitmap is displayed in

• zooming or panning the View containing the Bitmap

The reference is computed by the inverse of these transformations.

From this point onward, the Bitmap uses the Reference Extent torescale its image whenever a transformation to the window, View,Model, or objects within the Model occurs. The Bitmap can only scaleand translate its image; it cannot rotate the image.

If the G_BTM_TRANS_IMPULSE flag is set, the Bitmap will rescale itsimage using an impulse filter kernel. This is the fastest possible filterkernel, but it often causes aliasing in the target image. An impulsefilter is better at magnification than minification. When magnifiying animage with an impulse filter, pixels in the source image are replicated in

Bitmap Flag Description

G_BTM_NO_TRANS

do not transform the Bitmap object

G_BTM_TRANS_IMPULSE

transform the Bitmap object using an impulse resampling filter

2. The chapter entitled Display of Models of the SL-GMS Reference provides an illustration of these transformations.


Bitmap object

the target image. When minifiying an image with an impulse filter,pixels in the source image are missing in the target image.

When a Bitmap has its flag changed from G_BTM_TRANS_IMPULSE toG_BTM_NO_TRANS, theReference Extent is freed. It is recalculated, dependent upon anytransformations in the Graphical Modeling Hierarchy, the next time theG_BTM_TRANS_IMPULSE flag is set on the object.

SEE ALSOgmsRastOp( ), gmsLRastOP( ), gmsVuRFile( )

SL-GML COMMANDS[name:] bitmap fname x y

[name:] bitmapflag bitmapflag


Center point

Center point

SUMMARY

set or get the center Point of Circle, Sector, and Pie objects

NAME

gmsCenter( ), gmsLCenter( ), gmsQCenter( )

SYNTAX

intgmsCenter (obj, center)

id obj;idPoint center;

intgmsLCenter (objlist, center)

idLinkRef objlist;idPoint center;

idPointgmsQCenter (obj)

id obj;

DESCRIPTIONThe gmsCenter( ) function sets the center Point for Circle, Sector, andPie objects. Changing the center does not affect the radius. ThegmsLCenter( ) function changes the center for a List of objects.

The gmsQCenter( ) function returns a copy of the center Point only forCircle, Sector and Pie objects, and returns zero for all other types ofobjects. The returned Point should be freed with pntFree( ). Forobjects other than a Circle, Sector, or Pie, the gmsQExtCenter( )function (described on page 144) should be used to find the center ofthe extent of the object. The table page 26 illustrates, using an "X", the


Center point

center Point of a Circle, Sector, and Pie object,1 as well as extentcenters for various SL-GMS objects.

1. The center Point illustrated in the table, is the default center Point set when the object is created. If the center Point has been changed using gmsCenter( ), then the Point set using gmsCenter( ) will be the Point returned by gmsQCenter( ).


Center point

Center Point and center of extent

ObjectCenter Point

returned fromgmsQCenter( )

Center of extentreturned from

gmsQExtCenter( )

Rectangle zero

(Use the function gmsQExtCenter( ) on page 144)

Model Instance

zero


Group of objects

zero


Circle


Center point

SEE ALSOgmsLQExtCenter( ), gmsQExtCenter( )

The function returning the center of the extent for a List of objects isgmsLQExtCenter( ). The gmsQExtCenter( ) function returns a Pointwhich locates the center of the extent of any SL-GMS object.

SL-GML COMMANDname center x y

Sector

Pie

Center Point and center of extent<Helv7>(continued)

ObjectCenter Point



gmsQExtCenter( )


Circle object

Circle object

SUMMARY

create a Circle object

NAME

gmsCirc( ), gmsCir2( ), gmsFCirc( ), gmsFCir2( )

SYNTAX

idgmsCirc (name, point, radius)

char *name;idPoint point;double radius;

idgmsCir2 (name, pointlist)

char *name;idLinkRef pointlist;

idgmsFCirc (name, point, radius)

char *name;idPoint point;double radius;

idgmsFCir2 (name, pointlist)


DESCRIPTIONThe gmsCirc( ) function is used to create a Circle, given a center Pointand a radius. The Circle is created using the current attributes. The


Circle object

radius is in World Coordinates and is multiplied by the WorldCoordinate Scale Factor.

The gmsCir2( ) function creates a Circle, given a center Point and aPoint which is on the radius. The Points must be passed in a Point List.

The gmsFCirc( ) and gmsFCir2( ) functions are similar to theircounterparts without the "F," but the Circles they create are filled.

The name argument may be a null string, otherwise it is the nameassigned to the object when it is added to the current Model. Thecurrent Edge attributes are applied to the object when it is created.

SL-GML COMMANDS[name:] circ x y radius

[name:] cir2 x y x y

[name:] fcirc x y radius

[name:] fcir2 x y x y


Class query

Class query

SUMMARY

reply whether an object belongs to a class

NAME

gmsObjIsClass( ), gmsObjIsClassName( )

SYNTAX

intgmsObjIsClass (obj, aClass)

id obj;struct ClassDef *aClass;

intgmsObjIsClassName (obj, classname)

id obj;char *classname;

DESCRIPTION The gmsObjIsClass( ) function is used to test whether a given object isa member of a specific class. This function returns 1 when the objectis a member of the class and 0 when it is not. Classes are defined inthe C include file "gmscodes.h" in the lib subdirectory. The name ofthe object defined in the ".h" file is used with the gmsObjIsClass( )function.

The gmsObjIsClassName( ) function works in a similar manner to thegmsObjIsClass( ) function, returning 1 when an object is a member ofthe given class and 0 when it is not. The difference between the twofunctions is that gmsObjIsClassName( ) takes a class name string, ora macro as one of its parameters, while gmsObjIsClass( ) takes apointer to a class definition object.


Class query

Class name strings and their corresponding macros can be found in the include file "gmscodes.h", in the section beginning with

/*** CLASS VERSION CODES ***/

For example, Prim is the class name string for the G_PRIM class, andMarker is the class name for the G_MARKER class. The macro for theG_PRIM class name string is G_PRIM_NAME. It is recommended thatthe macros be used instead of the class name strings to ensure upwardcompatibility.

Class names also appear in object dumps to identify the type of objects.

EXAMPLE The name of the Part Primitive class is defined in the file "prp.h"distributed in the lib directory. The name of the object is PartPrim.The following code tests whether an object is a member of the PartPrimclass:

if(gmsObjIsClass(anObject, PartPrim)) {

. . . /* an Object is member */

} else {

. . . /* an Object is not a member */

}


Clear

Clear

SUMMARY

clear a View, clear a Workstation, or clear all Workstations

NAME

gmsClear( ), gmsWsClear( ), gmsClrAllWs( )

SYNTAX

intgmsClear (view)

id view;

intgmsWsClear (workst)

id workst;

intgmsClrAllWs( )

DESCRIPTIONThe gmsClear( ) function is used to clear the rectangular region definedby a View object. If nil is used as an argument, all Workstations arecleared.

The gmsWsClear( ) function is used to clear an entire Workstation. AllWorkstations are cleared by calling gmsClrAllWs( ).

DIAGNOSTICSAt present, there is no way to specify a background color for a View.The clear color is determined by the Workstation. This functionality willbe provided in a future release.

SL-GML COMMANDS[name] clear

[wsname] clear


Clone

Clone

SUMMARY

create a Clone of a Graphical Primitive object or List of objects

NAME

gmsClone( ), gmsLClone( )

SYNTAX

idgmsClone (name, obj)

char *name;id obj;

intgmsLClone (objlist)

idLinkRef objlist;

DESCRIPTIONThe gmsClone( ) function is used to create a Clone of a SL-GMSGraphical Primitive object and add it to the current Model. ThegmsLClone( ) function makes a copy of each object in the given Listand adds the objects to the current Model’s Part List. A 1 is returned ifall objects on the List are successfully duplicated, 0 if duplicating failsbefore traversing the entire List.

SL-GML COMMAND[name:] clone


Closure attribute

Closure attribute

SUMMARY

set or reset closure

NAME

gmsClosed( ), gmsLClosed( ), gmsMClosed( ), gmsQClosed( )

SYNTAX

intgmsClosed (obj, closed)

id obj;int closed;

intgmsLClosed (objlist, closed)

idLinkRef objlist;int closed;

intgmsMClosed (closed)

int closed;

intgmsQClosed (obj)

id obj;

DESCRIPTIONThe gmsClosed( ) function sets or resets the closure attribute for anobject. With closure set to 1, the first and last Points in an object areconnected with an Edge using the same Edge attributes used with theother Edges in the object. Lines, Splines, and Sectors may have theclosure attribute. Resetting this attribute (making it 0) removes the


Closure attribute

Edge that connects the last two Points in the object. ThegmsMClosed( )function sets the modal closure attribute.

The gmsLClosed( ) function sets the closure attribute for all the objectsin the given List. The gmsQClosed( ) function returns the closureattribute of the given object.

SL-GML COMMANDS[name] closed int


Color

Color

SUMMARY

sets the color attribute for objects; set modal color for all objects ortypes of objects; query an object’s color attribute; change color table

NAME

gmsMColor( ), gmsEColor( ), gmsFColor( ), gmsTColor( ),gmsLMColor( ), gmsLEColor( ), gmsLFColor( ), gmsLTColor( ),gmsMMColor( ), gmsMEColor( ), gmsMFColor( ), gmsMTColor( ),gmsQColor( ), gmsQMColor( ), gmsQEColor( ), gmsQFColor( ),gmsQTColor( ), gmsCTB( )

SYNTAX

intgmsMColor (obj, index)

id obj;int index;

intgmsEColor (obj, index)

id obj;int index;

intgmsFColor (obj, index)

id obj;int index;

intgmsTColor (obj, index)

id obj;int index;


Color

intgmsLMColor (objlist, index)

idLinkRef objlist;int index;

intgmsLEColor (objlist, index)


intgmsLFColor (objlist, index)


intgmsLTColor (objlist, index)


intgmsMMColor (index)

int index;

intgmsMEColor (index)

int index;

intgmsMFColor (index)

int index;

intgmsMTColor (index)

int index;

intgmsQColor (obj)

id obj;


Color

intgmsQMColor (obj)

id obj;

intgmsQEColor (obj)

id obj;

intgmsQFColor (obj)

id obj;

intgmsQTColor (obj)

id obj;

intgmsCTB (index, r,g,b, pen)

int index;double r,g,b;int pen;

DESCRIPTIONThis is a complete set of functions for the manipulation of the differentcolor attributes supported by SL-GMS. The first group of functionsapplies to individual objects, the second to Lists of objects, and thethird to the modal attributes. The fourth group of functions are colorattribute Query functions. The character preceding the word "color" in


Color

the function name indicates whether the attribute applies to the color ofEdges ("E"), Markers ("M"), Filled Objects ("F"), or Text ("T").

If a nil List is given to the List functions, the modal attribute is changed.

The query functions return the index for the particular color attributeused in an object. For example, the gmsQFColor( ) function returnsthe Fill color attribute used in a Fill object.

The gmsQColor( ) function returns either the color index for any objectthat has a single color attribute, or the Fill color if the object has severalcolor attributes, such as a Filled Text Rectangle.

The gmsCTB( ) function is used to set the Red-Green-Blue colordefinition for a particular color index. This definition becomes a part ofthe current View. The pen number may be specified for devices like apen-plotter which do not deal with RGB color. Color definitions aresystem-wide, and may also be established by using the "colordef.dat"file.

DIAGNOSTICSNo bounds checking is done for attributes. It is assumed that thedevice driver software, at the SL-GWS layer of SL-GMS, deals with theattributes appropriately. If an object is queried for an attribute notpresent in that object, the query function returns 0. For instance,querying a Text object for Edge color returns 0.

SEE ALSOThe chapter entitled Color in the SL-GMS Reference

SL-GML COMMANDS[name] color index

[name] mcolor index

[name] lcolor index

[name] fcolor index

[name] tcolor index

ctb index real real real


Current object

Current object

SUMMARY

set or query the current Group, Model, or View

NAME

gmsCurrent( ), gmsCurModel( ), gmsCurView( ), gmsCurGroup( ),gmsQCurrent( ), gmsQCurModel( ), gmsQCurView( ),gmsQCurGroup( ), gmsEndCurrent( )

SYNTAX

intgmsCurrent (obj)

id obj; /* Group, Model, or View */

intgmsCurModel (model)

id model;

intgmsCurView (view)

id view;

intgmsCurGroup (group)

id group;

idgmsQCurrent( )

idgmsQCurModel( )

idgmsQCurView( )


Current object

idgmsQCurGroup( )

intgmsEndCurrent( )

DESCRIPTIONThe gmsCurrent( ) function makes the given object the current object.This function applies only to Group, Model, and View objects.

The gmsCurModel( ) function is used to make a previously-createdModel active. This Model is the current Model until closed withgmsEndModel( ). A 0 is returned if the model argument is invalid.

The gmsCurView( ) function sets the notion of the current View. Anytop Model objects created go into the current View.

The gmsCurGroup( ) function is used to make a previously-createdGroup active. This Group is the current Group until closed withgmsEndGroup( ). A 0 is returned if the group argument is invalid.

The gmsQCurrent( ) query function returns a pointer to the currentGroup, Model, or View that is the lowest-level current object.

The gmsQCurModel( ) query function returns a pointer to the currentModel. The notion of the current Model is maintained by the Systemobject.

The gmsQCurView( ) query function returns a pointer to the currentView.

The gmsQCurGroup( ) query function returns a pointer to the currentGroup. The notion of the current Group is maintained by the Systemobject.

The gmsEndCurrent( ) function ends (closes) the lowest-level currentobject.

EXAMPLETo close all open Models, the following code may be used:

while (gmsQCurModel( ))

gmsEndModel( );


Current object

SEE ALSOgmsEndModel( ), gmsEndView( ), gmsGroup( ), gmsEndGroup( )

The Appendix entitled SL-GMS System Organization in the SL-GMSAdvanced Tutorial


Cursor

Cursor

SUMMARY

set, or query, the mouse cursor for SL-GMS windows

NAME

gmsWsCursor( ), gmsWsAddCursor( ), gmsQWsCursor( ),gmsQWsCursorNames( ), gmsQWsCursorInfo( )

SYNTAX

intgmsWsCursor (workst, cursor_name)

id workst; /* Workstation object*/char *cursor_name

intgmsWsAddCursor (workst, cursor_name, cursor_type,

cursor_data)id workst;char *cursor_name;int cursor_type;t_addr cursor_data;

char *gmsQWsCursor (workst)

id workst;

char **gmsQWsCursorNames (workst)

id workst;


Cursor

idgmsQWsCursorInfo (workst, cursor_name, cursor_type,

cursor_data)id workst;char *cursor_name;/* in */int cursor_type;/* out */t_addr cursor_data;/* out */

DESCRIPTIONThe cursor functions allow applications to change the mouse cursor inSL-GMS windows. Since mouse cursors are inherently platformdependent, the approach taken by SL-GMS is to register and accesscursors by name. This allows applications to performplatform-dependent initialization followed by platform-independentusage.

Without explicit initialization, SL-GMS supports 13 predefined cursorsunder 32-bit Windows and 77 font cursors under X Windows. These arepre-registered using names formed by removing the system-dependentprefix (e.g. "IDC_" or "XC_") from the system #defines (and in the 32-bitWindows case lower-casing the result).

For instance, the default SL-GMS cursor on Windows is "arrow",derived from IDC_ARROW; on X it is "top_left_arrow", derived fromXC_top_left_arrow.

The gmsWsCursor( ) function sets the mouse cursor for the specifiedWorkstation/Window. If the cursor matching the cursor_name argumentexists in the current SL-GMS list of cursors, the function returnsnon-zero and that cursor immediately becomes active. If workst is theexemplar Workstation/Window object (e.g. the object returned bygmsQDefaultWsClass( )) then that cursor will be used as the defaultcursor for subsequently created Workstation/Windows.

The gmsWsAddCursor( ) function is used to add a cursor to theSL-GMS list of cursors. If a cursor matching cursor_name alreadyexists, it is replaced. The cursor_type and cursor_data arguments areplatform dependent. Values and data structures for 32-bit Windowsapplications are supplied in the C include file "gmswin.h".


Cursor

X WindowsValues and data structures for X Windows applications are supplied inthe C include file "gmsX.h". The cursor_type argument must be one ofthe following values:

1. G_WS_FONT_CURSOR

2. G_WS_PIXMAP_CURSOR

If cursor_type is G_WS_FONT_CURSOR, then cursor_data must be apointer to an integer value from "X11/cursorfont.h" such asXC_top_left_arrow.

NOTE: The only reason to "add" a font cursor would be to rename it (forinstance to have a portable name between X and Windows) sinceSL-GMS already supports all available font cursors with namesformed by removing the "XC_" prefix from the "X11/cursorfont.h"definition.

If cursor_type is G_WS_PIXMAP_CURSOR then cursor_data must be apointer to a gmsXcursorStruct, defined in "gmsX.h":

typedef struct {Pixmap source,

mask;XColor *foreground,

*background;unsigned int hotspot_x,

hotspot_y;} gmsXcursorStruct;


Cursor

32-bit WindowsValues and data structures for 32-bit Windows applications are suppliedin the C include file "gmsWin.h". The cursor_type argument must beone of the following values:

1. G_WS_PREDEF_CURSOR

2. G_WS_FILE_CURSOR

3. G_WS_IMAGE_CURSOR

If cursor_type is G_WS_PREDEF_CURSOR, then cursor_data must bea pointer to an integer containing a predefined cursor value, e.g.IDC_ARROW.

If cursor_type is G_WS_FILE_CURSOR, then cursor_data must be a"LPCTSTR" containing the name of the ".cur" or ".ani" file to be loaded.

If cursor_type is G_WS_IMAGE_CURSOR, then cursor_data must be apointer to a gmsW32cursorStruct, defined in "gmsWin.h":

typedef struct {HINSTANCE hinst;LPCTSTR res_name;int mono_flag;

} gmsW32cursorStruct;

The gmsQWsCursor( ) query function returns a read-only cursor namestring for the cursor that is currently active for the specifiedWorkstation/Window object. If the workst argument is the exemplarWorkstation/Window object, the name of the current default cursor fornewly-created Workstation/Windows is returned.

The gmsQWsCursorNames( ) query function returns aNULL-terminated array of pointers to strings containing the names ofcurrently registered cursors. The application must not modify thestrings but should free the array of pointers.

The gmsQWsCusorInfo( ) query function returns information about anamed cursor. This function is provided primarily for debugging. Itreturns the device-dependent cursor_type and cursor_data informationas described in the section on gmsWsAddCursor( ).


Cursor

EXAMPLE Configure an application for six mouse cursors with the following code:

#include "gms.h"#include "gms_sms.h"#include <ctype.h>

#ifdef _WIN32

#include "gmsWin.h"

static intsimpleCursorType = G_WS_PREDEF_CURSOR;static intsimple_cursor1 = IDC_CROSS;static intsimple_cursor2 = IDC_SIZEALL;static intsimple_cursor3 = IDC_IBEAM;static intsimple_cursor4 = IDC_NO;static intsimple_cursor5 = IDC_WAIT;

#else /* ifdef _WIN32 */

#include "gmsX.h"#include <X11/cursorfont.h>

static intsimpleCursorType = G_WS_FONT_CURSOR;static intsimple_cursor1 = XC_crosshair;static intsimple_cursor2 = XC_fleur;static intsimple_cursor3 = XC_xterm;static intsimple_cursor4 = XC_iron_cross;static intsimple_cursor5 = XC_watch;

#endif/* ifdef/else _WIN32 */

static voidinitialize_cursors (){#ifndef _WIN32

int x_uparrow = XC_sb_up_arrow;


Cursor

#endif/* set default cursor to be an "uparrow"; onwin32, this is a predefined name usingIDC_UPARROW, but needs to be renamed forX, where it's known as XC_sb_up_arrow */

#ifndef _WIN32gmsWsAddCursor(gmsQDefaultWsClass(), "uparrow",

G_WS_FONT_CURSOR, &x_uparrow);#endif

gmsWsCursor(gmsQDefaultWsClass(), "uparrow");gmsWsAddCursor(gmsQDefaultWsClass(),

"simple_cursor1",simpleCursorType,&simple_cursor1);

gmsWsAddCursor(gmsQDefaultWsClass(),"simple_cursor2",simpleCursorType,&simple_cursor2);




}

Set the mouse cursor when needed. The code below changes themouse cursor each time the mouse is clicked.

static intloc_press (state, event)

idCLASS state;id event;


Cursor

{char *cur_cursor,

new_cursor[20];intlen;

cur_cursor = gmsQWsCursor(gmsQStWorkst(state));if (!cur_cursor) return 0;

strcpy(new_cursor, cur_cursor);len = strlen(new_cursor);switch (new_cursor[len - 1]) {

case 'w':strcpy(new_cursor,"simple_cursor1");break;

case '1':new_cursor[len - 1] = '2';break;




case '5':default:

new_cursor[len - 1] = '1';}

gmsWsCursor(gmsQStWorkst(state), new_cursor);


Cursor

return 1;}


Datasource — ".dat" files

Datasource — ".dat" files

SUMMARY

free memory associated with processing of ".dat" files

NAME

gmsDatDsFreeAll( )

SYNTAX

intgmsDatDsFreeAll ( )

DESCRIPTIONThe gmsDatDsFreeAll( ) function frees the memory for all ".dat" filesthat have been loaded since the last time it was called.

This function should not be called while a ".dat" file is being processed(usually in the deactivate method for a State).

The gmsDatDsFreeAll( ) function is used to clear out any variables setup in ".dat" files. It clears the simulation information associated withthe variable but does not free the SL-GMS internal Variable Definitions.The Variable Definitions can be freed only by using thegmsFreeAllVarDefs( ) function.

SEE ALSOgmsFreeAllVarDefs( )


Datasource — class


SUMMARY

create and install Datasource class

NAME

gmsDsClass( ), gmsDsClassInstall( ), gmsDsClassFindByName( ),gmsClassAddMethod( )

SYNTAX

idgmsDsClass (classname, instsize)

char *classname;/* name of class */int instsize; /* size of class object */

intgmsDsClassInstall (dsclassdef)

idCLASS dsclassdef;/* a Datasource class */

idgmsDsClassFindByName (classname)

char *classname;/* name of a class */

intgmsClassAddMethod (class, methname, methaddr, fctntype,

argtypes)id class; /* Datasource class created by

gmsDsClass( ) */char *methname; /* name of method */void (*methaddr)( );/* address of method */int fctntype; /* return type of method */long argtypes; /* not used */



DESCRIPTION

The gmsDsClass( ) function dynamically creates a Datasource classobject, given the class name and the size of the object in bytes. It isintended that it be called once from the Datasource’s globalinitialization function, which by convention is named xxxClassInit( )where "xxx" is the classname. If successful, the non-0 return valuemay be passed to all gmsDs*( ) functions which act on a singleDatasource class.

The gmsDsClassInstall( ) function installs a Datasource class object,previously created with gmsDsClass( ) into the run-time environment.It is intended that it be called once from the Datasource’s globalinitialization function, which by convention is named xxxClassInit( )where "xxx" is classname. It should be called after allgmsClassAdd*( ) functions have returned successfully. A non-0return value indicates success.

The gmsDsClassFindByName( ) function looks up a Datasource classobject, given a class name. If successful, the non-0 return value maybe passed to all gmsDs*( ) functions which act on a single Datasourceclass.

The gmsClassAddMethod( ) function adds a method to a Datasourceclass’ set of methods. The function returns 1 for success, 0 for failure.Valid codes for fctntype are G_INTEGER and G_POINTER. argtypesis not used and should be passed with a 0.


Datasource — Instance


SUMMARY

create, activate, deactivate a Datasource Instance; retrieve, add, deleteVariable Definitions (VarDefs) for a Datasource Instance

NAME

gmsDsActivate( ), gmsDsAddVarDef( ), gmsDsDeactivate( ),gmsDsFindVarDef( ), gmsDsInst( ), gmsDsInstFree( ),gmsDsVarDefFree( ), gmsDsUpdate( )

SYNTAX

intgmsDsActivate (dsinst)

idCLASS dsinst; /* a Datasource Instance */

intgmsDsAddVarDef (self, varname, varinfo, vartype, count,

size)idCLASS self; /* a Datasource Instance */char *varname; /* a variable name */char *varinfo; /* variable application info */int vartype; /* variable type, e.g., G_INTEGER */int count; /* number of data elements */int size; /* size of each data element */

intgmsDsDeactivate (dsinst)


idgmsDsFindVarDef (self, varname)

idCLASS self; /* a Datasource Instance */char *varname; /* a variable name */



idgmsDsInst (instname, classname)

char *instname; /* a Datasource Instance */char *classname;/* name of a Datasource class */

intgmsDsInstFree (dsinst)


intgmsDsVarDefFree (dsinst, vardef)

idCLASS dsinst; /* a Datasource Instance */id vardef; /* a VarDef object */

intgmsDsUpdate (dsinst)


DESCRIPTIONThe gmsDsActivate( ) function activates a single Datasource Instance.The Datasource’s superclass activate method allocates memory, ifnecessary, for each VarDef attached to the Instance, notifies SL-GMSthat the variable has changed, and finally uses the gmsDsMsg( )interface to invoke the Datasource-specific activate method. Failure(0) return indicates a memory-allocation problem.

The gmsDsAddVarDef( ) function dynamically adds a VarDef to the

idLinkRef vardefs;field of a Datasource Instance. It is intended that it be calledrepetitively from the application after the gmsDsInst( ) function andbefore the Instance is activated. The reason for this calling sequenceis for proper memory allocation; although the memory for the VarDef isallocated in gmsDsAddVarDef( ), the variable space (the space to whichthe address argument of gmsVarDefine( ) points) is allocated in theInstance’s superclass activate method. The varinfo argument isprovided for application convenience: the input string is copied intospace allocated for the VarDef ’s



char * varinfo;field and is ignored by SL-GMS. Otherwise, this function behavesmuch as gmsVarDefine( ).

The gmsDsDeactivate( ) function deactivates a single DatasourceInstance. Currently nothing is done at the superclass level except touse the gmsDsMsg( ) interface to invoke the Datasource-specificdeactivate method.

The gmsDsFindVarDef( ) function accepts a pointer to a DatasourceInstance and a variable name. If successful, it returns a pointer to theassociated VarDef; null is returned upon failure.

The gmsDsInst( ) function dynamically creates a named DatasourceInstance, given an Instance name and the name of an initializedDatasource class. The Instance name must be currently unused withinthe class. The class must have been initialized by the Datasource’sglobal initialization function, by convention named xxxClassInit( )where "xxx" is the "classname". If successful, the non-0 return valuemay be passed to all gmsDs*( ) functions which act on a singleDatasource Instance.

The gmsDsInstFree( ) function frees the memory associated with asingle Datasource Instance. It is the caller’s responsibility to null thedsinst pointer if there is a chance that dsinst will be accessed again inits current state.

The gmsDsVarDefFree( ) function frees a Datasource Instance’sindividual VarDef object.

The gmsDsUpdate( ) function updates an individual DatasourceInstance.

SEE ALSOgmsDsMsg( ), gmsVarDefine( ), gmsDsListDeactivate( ),gmsDsClass( ), gmsDsObjNew( ), gmsDsListUpdate( )


Datasource — Lists


SUMMARY

manipulate Lists of Datasource Instances

NAME

gmsDsListActivate( ), gmsDsListDeactivate( ), gmsDsListFree( ),gmsDsListGet( ), gmsDsListSave( ), gmsDsListUpdate( ),gmsDsObjFree( ), gmsDsObjNew( )

SYNTAX

intgmsDsListActivate (dslist)

idLinkRef dslist;/* a list (idLinkRef) of DatasourceInstances */

intgmsDsListDeactivate (dslist)

idLinkRef dslist;/* a list of Datasource Insts */

intgmsDsListFree (dslist)


idLinkRefgmsDsListGet (filename)

char *filename; /* name of file */

intgmsDsListSave (dslist, filename)

idLinkRef dslist;/* a list of Datasource Insts */char *filename; /* name of file */

intgmsDsListUpdate (dslist)




intgmsDsObjFree (datasource)

id datasource;

idgmsDsObjNew (classname)

char *classname;

DESCRIPTIONThe gmsDsListActivate( ) function activates a linked List ofDatasource Instances. It is the equivalent of calling gmsDsActivate( )for each Instance in the List.

The gmsDsListDeactivate( ) function deactivates a linked List ofDatasource Instances. It is the equivalent of callinggmsDsDeactivate( ) for each Instance in the List.

The gmsDsListFree( ) function frees a List of Datasource Instances.

The gmsDsListGet( ) function retrieves a List of Datasources stored infilename.

The gmsDsListSave( ) function saves a List of Datasources infilename.

The gmsDsListUpdate( ) function updates a List of Datasources.

The gmsDsObjFree( ) function frees a Datasource object.

The gmsDsObjNew( ) function creates a new Datasource object.

SEE ALSOgmsDsActivate( ), gmsDsDeactivate( ), gmsDsUpdate( )


Datasource — messages


SUMMARY

send message to Datasource Instance

NAME

gmsDsMsg( ), gmsDsPMsg( ), gmsDsMsg1( ), gmsDsPMsg1( ),gmsDsMsg2( ), gmsDsPMsg2( ), gmsDsMsg3( ), gmsDsPMsg3( ),gmsDsMsg4( ), gmsDsPMsg4( )

SYNTAX

intgmsDsMsg (self, msgstr)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */

void *gmsDsPMsg (self, msgstr)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */

intgmsDsMsg1 (self, msgstr, arg1)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* method argument */

void *gmsDsPMsg1 (self, msgstr, arg1)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* method argument */



intgmsDsMsg2 (self, msgstr, arg1, arg2)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* method arguments */long arg2; /* method arguments */

void *gmsDsPMsg2 (self, msgstr, arg1, arg2)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* a method argument */long arg2; /* a method argument */

intgmsDsMsg3 (self, msgstr, arg1, arg2, arg3)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* a method argument */long arg2; /* a method argument */long arg3; /* a method argument */

void *gmsDsPMsg3 (self, msgstr, arg1, arg2, arg3)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* a method argument */long arg2; /* a method argument */long arg3; /* a method argument */

intgmsDsMsg4 (self, msgstr, arg1, arg2, arg3, arg4)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* a method argument */long arg2; /* a method argument */long arg3; /* a method argument */long arg4; /* a method argument */



void *gmsDsPMsg4 (self, msgstr, arg1, arg2, arg3, arg4)

idCLASS self; /* a Datasource Instance */char *msgstr; /* a message string */long arg1; /* a method argument */long arg2; /* a method argument */long arg3; /* a method argument */long arg4; /* a method argument */

DESCRIPTIONThese functions send messages to a specific Datasource Instance.The msgstr parameter must match the method name registered for the Instance’s class with thegmsClassAddMethod( ) function.

The value returned by the functions gmsDsMsg( ), gmsDsMsg1( ),gmsDsMsg2( ), gmsDsMsg3( ), and gmsDsMsg4( ) is that of the invokedmethod. The value returned by the functions gmsDsPMsg( ),gmsDsPMsg1( ), gmsDsPMsg2( ), gmsDsPMsg3( ), and gmsDsPMsg4() is the pointer value returned by the message.

The arguments arg1, arg2, arg3, and arg4, passed to these functionsmust be declared or cast to long. The DataSource Instance receivingthe message will be passed longs.

SEE ALSOgmsClassAddMethod( ) in the section Datasource — class on page 52


Directories and paths


SUMMARY

set the current directory for SL-GMS; add or free library search paths

NAME

gmsChdir( ), gmsAddLibPath( ), gmsFALibPaths( )

SYNTAX

intgmsChdir(dirname)

char *dirname;

intgmsAddLibPath (pathname)

char *pathname;

intgmsFALibPaths( )

DESCRIPTIONThese three functions control where SL-GMS searches for Models,Projects, "fontdef.dat", "colordef.dat", and "pscolordef.dat" files.

The gmsChdir( ) function changes the location of the current directory,returning 0 if the request to change directory fails.

The gmsAddLibPath( ) function adds another directory to the defaultSL-GMS search path (shown in the table on the following page).

The gmsFALibPath( ) function limits the search to the current directoryby permanently removing all library directories from the search path.



SL-GMS Directory Search Path Order

1. The current directory

2. The default SubModel subdirectories of the current directoryUNIX Systems. /GISMOS, . /GRAPHS, . /SUBMODSVAX/VMS Systems[.gismos], [.graphs], [.submods]NT Systems.\gismos\, .\graphs\, .\submods\

3. The default SubModel directories on the same level as the current directory

UNIX Systems.. /GISMOS, .. /GRAPHS, .. /SUBMODSVAX/VMS Systems[-.gismos], [-.graphs], [-.submods]NT Systems..\gismos\, ..\graphs\, ..\submods\

4. Any directories added with the -i command-line option or with the gmsAddLibPath( ) function in the order in which they were added

5. The standard lib directoryUNIX Systems$GMS_HOME/libVAX/VMS Systemsgms$home:[lib]NT Systems%GMS_HOME%\lib



EXAMPLE

UNIX SystemsgmsAddLibPath("/usr/mydir");

VAX/VMS SystemsgmsAddLibPath("[usr.mydir]");

NT Systems1

gmsAddLibPath("\\usr\\mydir");

or

gmsAddLibPath("/usr/mydir");

6. The default SubModel directories in the gismos, graphs, and models subdirectories of the demo directory

UNIX Systemsdemo/gismos/GISMOS, demo/graphs/GRAPHS, demo/models/SUBMODSVAX/VMS Systems[demo.gismos.gismos], [demo.graphs.graphs], [demo.models.submods]NT Systemsdemo\gismos\GISMOS, demo\graphs\GRAPHS, demo\models\SUBMODS

7. The SL-GMS home directoryUNIX Systems$GMS_HOMEVAX/VMS Systemsgms$homeNT Systems%GMS_HOME%

1. Two backslashes (\\) are required by the compiler on NT Systems to "escape" the usual interpretation of the single backslash.

SL-GMS Directory Search Path Ordercontinued)


Display, erase, highlight


SUMMARY

display, erase, or highlight an object or List of objects

NAME

gmsDisplay( ), gmsLDisplay( ), gmsErase( ), gmsLErase( ),gmsHilite( ), gmsLHilite( )

SYNTAX

intgmsDisplay (obj)

id obj;

intgmsLDisplay (objlist, nclass, class1, class2, ...)

idLinkRef objlist;int nclass;struct ClassDef *class1, *class2, ... ;

intgmsErase (obj)

id obj;

intgmsLErase (objlist, nclass, class1, class2, ...)

idLinkRef objlist;int nclass;struct ClassDef *class1, *class2, ... ;

intgmsHilite (obj, flash)

id obj;int flash;



intgmsLHilite (objlist, flash)

idLinkRef objlist;int flash;

DESCRIPTIONThis set of functions is used to display, erase, or highlight individualobjects or Lists of objects. The system must be in Immediate UpdateMode (gmsImmu( )) for these functions to work. If the system is inDeferred Update Mode, nothing will happen.

The gmsDisplay( ) and gmsLDisplay( ) functions set a flag in objectsmarking them for redraw.

The gmsErase( ) and gmsLErase( ) functions mark objects to beerased.

The gmsLDisplay( ) and gmsLErase( ) functions are used withclass-definition arguments. When used with class-definitionarguments, only the objects on the List in one of the class argumentsare displayed or erased. Using this, a List of objects is passed to oneof these functions and only a certain class of objects is displayed orerased while other objects are unaffected. The argument nclass mustbe set to the number of class definition arguments. The include files(".h") in the lib directory should be examined for the names of theseclasses and more information regarding class-definition objects.

The argument nil is used in place of a List of class definitions when nofiltering of objects by class is desired, in which case nclass is set to 0.

The gmsHilite( ) and gmsLHilite( ) functions take an argument whichindicates how to highlight the object. When flash is equal to 1, theobject(s) is made visible and then invisible (through the use ofgmsSVis( )). When flash is equal to 0, the object(s) is erased thendisplayed.

DIAGNOSTICSSetting the visibility is a solution to highlighting for those devices thatdo not support it in hardware. Presently, the gmsHilite( ) functiondoes not support the use of hardware blink.



EXAMPLE

To mark for a display a List of objects, regardless of class:

idLinkRef objlist = gmsQPartList(aGroup);

gmsLDisplay(objlist, 0, nil);

To mark for a display only Edge and CompEdge class objects from aList of objects:

gmsLDisplay(objlist, 2, Edge, CompEdge);

SEE ALSOgmsImmu( )


Dump

Dump

SUMMARY

dump an SL-GMS object for debugging purposes

NAME

gmsDump( ), gmsDumpViews( )

SYNTAX

intgmsDump (obj)

id obj;

intgmsDumpViews( )

DESCRIPTIONThe gmsDump( ) function is used to dump the contents of any objectcreated by SL-GMS. If the argument given is nil, this function dumpsthe contents of the current Model. The gmsDump( ) function isprimarily useful to those with an intimate knowledge of the internals ofthe SL-GMS system, although the format is simple enough to beunderstood in most cases.

The gmsDumpViews( ) function is useful in debugging applications. Itprints out all Views and their Models in a readable format (not the usualdump format).

SEE ALSOThe chapter entitled Variables Dumped for SL-GMS Object Classes inthe SL-GMS Quick Reference

SL-GML COMMAND[name] dump


Dynamics — double-buffering

Dynamics — double-buffering

SUMMARY

enable or disable software double-buffering for an object

NAME

gmsDoubleBufferFlag( )

SYNTAX

intgmsDoubleBufferFlag (obj, flag)

idPrim obj;int flag; /* 0 = disable, 1 = enable */

DESCRIPTIONThe gmsDoubleBufferFlag( ) function enables or disables softwaredouble-buffering on an object. The object must be an SL-GMSGraphical Primitive (Model, Group, Line, Circle, and the like).2 Thefunction does not allow a View or a Workstation/Window to be markedfor double-buffering.

SEE ALSOgmsNoErase( )

Workstation/Windows can be marked for double-buffering with theG_WS_DBUFF_ERASE or G_WS_DBUFF_CLEAR flags. Furtherinformation about these flags is provided in the Installation Notes.

The chapter entitled Dynamics in the SL-GMS Reference

SL-GML COMMANDname dbflag flag

2. The table SL-GMS Object Classes in the Appendix entitled SL-GMS System Organization in the SL-GMS Advanced Tutorial contains a list of the available SL-GMS Graphical Primitives.


Dynamics — DynProps/RenamedVariables


SUMMARY

create DynProps and Renamed Variables at run-time; query an object’sDynProp and Renamed Variables

NAME

gmsDynStr( ), gmsRenamedStr( ), gmsRenamedStrNoRelink( ),gmsRenVarStrConstReplSO( ), gmsQDynStr( ), gmsQDynStrList( ),gmsQRenamedStr( )

SYNTAX

intgmsDynStr (obj, string)

id obj;char *string;

intgmsRenamedStr (obj, string)


intgmsRenamedStrNoRelink (obj, string)


intgmsRenVarStrConstReplSO (modinst, var_name, new_string)

id modinst;id var_name;id new_string;

char *gmsQDynStr (object)

id object;



char *gmsQDynStrList (object)

id object;

char *gmsQRenamedStr (inst)

id inst;

DESCRIPTIONThe gmsDynStr( ) function enables an application to create dynamicdescriptions. Although most applications use Models where thedynamic descriptions have already been created by using SL-DRAW2or SL-DRAW, objects can have new dynamic descriptions associatedwith them by using this function. The string used as an argument mustinclude a set of parentheses for each line of a dynamic description (asdisplayed by the Edit Dyn option of the Dyn Pull-Down Menu in SL-DRAW2 orSL-DRAW). The limit on the number of characters for the string is8192. Adding a new description removes any previous description.The gmsVarDefine( ) function must be called to associate the variablesin the new description with data addresses. This description does notbecome a permanent part of the Model unless the Model is saved (e.g.,with gmsMSave( )).

The gmsRenamedStr( ) function permits an application to renamevariables associated with a Model Instance. This function works likethe Rename Vars option of the Dyn Pull-Down Menu in SL-DRAW2 orSL-DRAW. The first argument is the pointer to the Model Instance.The string contains pairs of variable names and the new namesseparated by a double colon. The limit on the number of charactersfor the string is 8192. For example, to rename the variable x_value tomagnitude, the string

x_value :: magnitudeis used. If there are many variables to be renamed, the string willcontain many pairs of values, each pair separated by a space. Aftercalling gmsRenamedStr( ), the Model must be re-initialized withgmsDynInit( ).



NOTE: All Variable Definitions must be unlinked before gmsDynStr( ) orgmsRenamedStr( ) is called. After the gmsDynInit( ) functionhas been called, gmsUnlinkVarDefs( ),gmsRemVarDefLinks( ), or gmsDynEnd( ) must be calledbefore calling either gmsDynStr( ) or gmsRenamedStr( ) or acrash may result. Following these calls, gmsDynInit( ) must becalled on the changed object to re-initialize its dynamic variables.

gmsUnlinkVarDefs(obj);gmsDynStr(obj, str); or gmsRenamedStr(obj, str);gmsDynInit(obj);

The gmsRenamedStrNoRelink( ) function creates a Renamed VariableList for a Model Instance (obj) from string. Unlike gmsRenamedStr( ),gmsRenamedStrNoLink( ) does not relink Instances. ThegmsRenamedStrNoLink( ) function is used when in SubModel ReplicateMode, reached by calling gmsSubModReplicateMode( ), or afterrenaming the variables of a Model Instance (obj).

The gmsRenVarStrConstReplSO( ) function replaces the stringconstant referenced by a Renamed Variable in a Model Instance with adifferent string constant. The var_name argument specifies the nameof the Renamed Variable defined in the given Model Instance. Thenew_string argument, a String object, specifies the new value of thestring constant. If new_string is NULL, the new value of the variablespecified by var_name will be an empty string.

If the gmsDynInit( ) function has been previously called, all VariableDefinitions must be unlinked from the Model containing the given ModelInstance before gmsRenVarStrConstReplSO( ) is called. ThegmsUnlinkVarDefs( ) function must be called before callinggmsRenVarStrConstReplSO( ) or a crash may result. Following thecall, gmsDynInit( ) must be called on the changed Model to re-initializeits dynamic variables. Therefore, it is best to callgmsRenVarStrConstReplSO( ) before gmsDynInit( ).

gmsRenVarStrConstReplSO( ) returns 1 for success, 0 for failure.



EXAMPLE

Change the label of an m_quit GISMO.

In the following Model "top.g":

top_mod: modelexit_button: inst m_quit 0 0. move 40 15. scale 40 15 2 2renamedvars \

button_label :: "QUIT" \edge_width :: 3 \text_align_x :: 2 \text_height :: 1

endm

the variable button_label has the constant string "QUIT" as itsvalue. If "QUIT" is to be replaced with "EXIT" during runtime,gmsRenVarStrConstReplSO( ) can be called, as illustrated in thefollowing example:

id top_mod, button_ins;id var_name, new_string;

top_mod = gmsMGet("top", "top");button_ins = gmsFindByName("exit_button");var_name = gmsStringC("button_label");new_string = gmsStringC("EXIT");gmsRenVarStrConstReplSO(button_ins, var_name,

new_string);gmsDynInit();



The gmsQDynStr( ) function returns an object’s dynamic description string.

The gmsQDynStrList( ) function returns a dynamic description stringwith level codes.

The gmsQRenamedStr( ) function returns the object’s RenamedVariable string. This function works only on Model Instance objects.The string contains pairs of variables and renamed variables separatedby whitespace. For example, in the Renamed Variable string

x::x1 y::y1 z::z1

x, y, and z are renamed x1, y1, and z1.

EXAMPLEWhile working in SL-DRAW2, a Rectangle with the following dynamicdescription was created:

*

fpercent b1

To add the same dynamics to a Rectangle created by an application,the following functions could be used:

id Rect;

Rect = gmsRect("", pntArray);

if (gmsDynStr(Rect, "(* (fpercent b1))"))

printf("Dynamic description added to Rect.\n");



EXAMPLE

A DynProp with several variables and ranges is shown as it wouldappear in Edit Dyn, and as it would appear when converted to a string.

DynProp as it would appear in "Edit Dyn":angle

= 0.:500.

rotate -30.:30.

pres

= 1500.:2000.

fpercent 0.:100.

With the proper parentheses inserted, the string appears as follows:

DynProp as it would appear when converted to a string:gmsDynStr(obj, "(angle (= 0.:500.(rotate -30.:30.)))(pres (= 1500.:2000.(fpercent 0.:100.)))");

The creation of the string based upon values of variables isaccomplished with the following:

sprintf(dyn_buffer,

"(* (movex alt_atx%02d)(movey alt_aty%02d))", i,i);

if(!gmsDynStr(inst,dyn_buffer))

printf("gmsDynStr on alt_all %dfailed.\n", i);



EXAMPLE

The following code fragment shows a loc_press method that renames astring associated with an Instance.

static intloc_press(state, event)

id state;id event;

{char rnmstr[1000];id obj;

/* retrieve object clicked */obj = gmsQEvObject(event);

/* remove links between VariableDefinitions and VariableReferences */

gmsUnlinkVarDefs(obj);

/* set up rename string */sprintf(rnmstr,"format :: \"%%d A\" label ::

\"Amps\" highlimit :: 20 highdanger:: 19 alarmcolor :: 1 lowdanger ::0 lowlimit :: 0 m :: b1");

/* apply renamed string to object */gmsRenamedStr(obj, rnmstr);

/* reinitialize dynamics withoutmarking for update */

gmsDynInitNoMarks(obj);

/* change b1 and mark for change */b1++;gmsVarDefineChanged("b1", &b1, G_INTEGER, 1, 1);

gmsDynUpdate(gmsQStModel(state));gmsUpdate(gmsQStView(state));



return 1;}

EXAMPLEAny unconditionally-renamed variables should be followed with a call togmsRenamedStr( ). Next, if other variables are conditionally renamed,the renaming should be followed by a call togmsRenamedStrNoRelink( ) for efficiency.

If SubModel Replicate Mode has been turned on,gmsRenamedStrNoRelink( ) should be used (again, for efficiency).

sprintf(ren_vars_buf,"volts :: volts%02d",meter_index);

gmsRenamedStr(meter_inst, ren_vars_buf);

if (count_volt_changes == 1) {sprintf(cond_ren_vars_buf,

"volt_changes :: volt_changes%02d",meter_index);

gmsRenamedStrNoRelink(meter_inst,cond_ren_vars_buf);

}

SEE ALSOgmsVarDefine( ), gmsDynInit( ), gmsUnlinkVarDefs( ),gmsRemVarDefLinks( ), gmsDynEnd( ), gmsString( )

Internationalization — String object on page 208


SL-GML COMMANDSname dynprop string

name renamedvars string


Dynamics — erasure


SUMMARY

set flag options and Batch Erase Modes for object erasure

NAME

gmsBatchErase( ), gmsBatchEraseMode( ), gmsNoErase( )

SYNTAX

intgmsBatchErase (object, flag)

id object;int flag; /* "batch erase" flag = G_ON/G_OFF

*/

intgmsBatchEraseMode (flag)

int flag;

intgmsNoErase (object, flag)

id object;int flag; /* "no-erase" flag = G_ON/G_OFF */

DESCRIPTIONThe gmsBatchErase( ) function sets an object’s batcherase flag. Thebatcherase flag has meaning only for objects with parts: Models andGroups. When the batcherase flag is set to G_ON, all dynamicerasures are done first, before redrawing the object. The batcheraseflag is useful for objects which require, for example, a move action onmultiple objects which may collide.

The batcherase flag can be used in conjunction with the repair flag. ThegmsRepairFlag( ) function sets an object’s repair flag. When the repairflag is set to G_ON, then if any object in the Group is redrawn, allobjects in the Group are redrawn.



EXAMPLE

Figure 1-1: illustrates a diamond object with attached dynamics thatmove the diamond over a static line.

Figure 1-1: .Diamond with dynamics to move over a static line

The dynamics for the diamond are as follows:

. dynprop \

(x_pos \

(= * \

(movex x_pos)))

With the present dynamics, each time the diamond moves, a portion ofthe line is erased. A "hole" marking each previous position of thediamond appears in the static line.

Figure 1-2: .Diamond moving and erasing portions of the line

In order to move the diamond without erasing portions of the line,dynamics must be attached that will erase both the line and diamondobjects each time, x_pos, the variable driving the movex dynamicaction of the diamond, changes and then redraw them.

The line and the diamond are made into a Group. The dynamics for theline and diamond Group are as follows:

group



. repairflag 1

. batcherase 1

With the repair flag set to G_ON for the Group, whenever the diamondis redrawn the line is automatically redrawn. With the batcherase flagset to G_ON for the Group, both the line and the diamond are erasedfirst and then redrawn as illustrated in Figure 1-3:. The diamond movesover the line without erasing it.

Figure 1-3: .Diamond moving over line

The gmsBatchEraseMode( ) function sets Batch Erase Mode G_ON orG_OFF globally for all SL-GMS objects. When turned to G_ON, thedisplay and erase passes occur separately (split at View level). This isequivalent to having the batcherase flag set to G_ON for all Models.

For displays that have many objects moving across each other, such asa radar screen, it is not practical to use batcherase. It is more efficientto make use of noerase in conjunction with double-buffering or clearingof Views. This scheme avoids the overhead of marked erasure andsimply redraws everything. The gmsNoErase( ) function sets thenoerase flag on an object. With the noerase flag set to G_ON, anobject is never erased.

SEE ALSOgmsDoubleBufferFlag( )

gmsRepairFlag( )


SL-GML COMMANDSname batcherase

name noerase


Dynamics — initialize, update, restore, end


SUMMARY

initialize, update, or end dynamics; restore a Graphical Primitive to itsoriginal state

NAME

gmsDynInit( ), gmsDynInitNoMarks( ), gmsVarInitFctn( ),gmsDynUpdate( ), gmsDynRestore( ), gmsDynEnd( )

SYNTAX

intgmsDynInit (model)

id model;

intgmsDynInitNoMarks (obj)

id obj;

intgmsVarInitFctn (fctn)

id (*fctn)( );

intgmsDynUpdate (model)

id model;

intgmsDynRestore (obj)

id obj;

intgmsDynEnd( )



DESCRIPTIONThe gmsDynInit( ) function initializes the dynamic descriptions of partswithin Models. When the model argument is nil, the dynamic attributesin all loaded Models are initialized.

The gmsDynInit( ) function internally creates a Variable Referenceobject for each variable referenced in the Model and performs otherhousekeeping work necessary to set up dynamics. This functionreturns 0 for failure, such as "out of memory." It must be called explicitly by the application tore-associate dynamic descriptions after gmsDynEnd( ) orgmsRenamedStr( ) is called.

NOTE: If gmsDynInit( ) is called repeatedly on a Model, without callingone of the functions gmsDynEnd( ), gmsRemVarDefLinks( ), orgmsUnlinkVarDefs( ) each time, memory leakage will result.

The gmsDynInit( ) function looks for variable definitions in the globaltable. It also automatically looks for variable definitions in StateVariable Tables, whenever the gmsDynInit( ) function is called implicitlyduring the State activation. The search begins at the State which isbeing activated; if a variable definition is not found in that State, eachSuperState is then searched until the variable is found. If it is still notfound after searching all SuperStates, the global table is searched.

NOTE: The lookup of variables in State Variable Tables is automatic onlyif done by the State activation. If the gmsDynInit( ) function isdone manually, it must be set by global identificationg_dyninit_state to be the State in which to start the search.

The gmsDynInitNoMarks( ) function initializes dynamics for a Primitivewithout marking anything for update. If the nil argument is given, thisfunction initializes dynamics for all Models.

The gmsVarInitFctn( ) function sets a single internal function pointerthat is called during dynamics initialization (gmsDynInit( )). Theuser-defined callback is called whenever a Variable-Reference isencountered during initialization. The user-defined callback functionmust take two arguments: the variable’s name (char *) and the



variable’s typecode (int). The user-defined callback should return theVariable Definition object (VarDef) created.

During dynamics initialization, gmsVarInitFctn( ) is called once with atype code of 0 ("variable type unknown") and a second time with thetype code of 0x100 (string) for an object with the following DynProp :

t1= *

stext t1 "%s"

The gmsVarInitFctn( ) function passes 0 for the first occurrence of t1(because it is followed by = *) to indicate that the variable type of t1 isstill unknown. The gmsVarInitFctn( ) function callbacks are typicallyused to access information or further variables from a database or tocheck for errors (i.e., how a variable is used in a DynProp comparedwith its type in the database).

EXAMPLEgmsVarInitFctn(my_var_init_func);. . .idmy_var_init_func (varname, vartype)

char *varname;int vartype;

{id vardef;

/* application specific code goes here... *//* define the variable */

vardef=gmsVarDefine(varname,&varname,vartype,0,0);

return vardef;}

The gmsDynUpdate( ) function updates the dynamic descriptions ofparts within Models. When the model argument is nil, the dynamicattributes in all loaded Models are updated.



NOTE: Before the dynamic descriptions can be updated, they must beassociated with data addresses by using gmsVarDefine( ).

The gmsDynUpdate( ) function initiates a dynamic update pass on aModel. This pass accesses the data and makes changes to objectsaccording to the dynamic descriptions of those objects. This functiondoes not result in the display of changed objects until gmsUpdate( ) iscalled, (unless SL-GMS is in Immediate Update Mode). ThegmsDynUpdate( ) function must be called prior to callinggmsUpdate( ) in order to be certain all dynamic attributes areup-to-date with the variables. SL-SMS calls the gmsDynUpdate( ) andgmsUpdate( ) functions automatically.

The gmsDynRestore( ) function restores a Primitive to its originalstate, before its dynamics were executed. If the nil argument is given,it restores all Graphical Primitives to their original states.

The gmsDynEnd( ) function disconnects Variable Definitions from theobjects with which they are associated.

An application may also call gmsDynEnd( ) when a dynamic actionmakes a Model invisible, thus preventing SL-GMS from updating thedynamics associated with the Model’s parts. (If a Model is madeinvisible through a direct function call, such as

gmsSetVis(model, 0);

calling gmsDynEnd( ) is unnecessary.) The Variable Definitions canbe re-associated by calling gmsDynInit( ) on the Model once again.

SEE ALSOgmsVarChanged( ), gmsVarDefine( ), gmsRenamedStr( ),gmsRemVarDefLinks( ), gmsUnlinkVarDefs( )



Dynamics — optimization


SUMMARY

set or query internal SL-GMS optimization flags to implement optimizeddynamics

NAME

gmsAutoUpdateMode( ), gmsQAutoUpdateMode( ),gmsFastDynPropMode( ), gmsQFastDynPropMode( ),gmsDynUpdateMode( ), gmsQDynUpdateMode( ),gmsAllVarsChanged( ), gmsUseShadowMode( ),gmsQUseShadowMode( ), gmsExtentMode( ), gmsQExtentMode( ),gmsNoFlags( ), gmsNoFlagsMode( ), gmsQNoFlagsMode( ),gmsDynUpdArrayFlag( )

SYNTAX

intgmsAutoUpdateMode (mode)

int mode; /* G_ON or G_OFF */

intgmsQAutoUpdateMode ( )

intgmsFastDynPropMode (mode)

int mode; /* G_ON or G_OFF (default) */

intgmsQFastDynPropMode ( )

intgmsDynUpdateMode (mode)

int mode; /* G_UPDATE_PASS or G_DYNUPDATE_PASS(default) */

intgmsQDynUpdateMode ( )



intgmsAllVarsChanged ( )

intgmsUseShadowMode (mode)


intgmsQUseShadowMode ( )

intgmsExtentMode (mode)


intgmsQExtentMode( )

intgmsNoFlags(obj, flag)

idPrim obj; /* Graphical Primitive object */int flag; /* 0 = OFF, 1 = ON */

intgmsNoFlagsMode (mode)


intgmsQNoFlagsMode( )

intgmsDynUpdArrayFlag (object, flag)

id object;int flag;



DESCRIPTIONThese functions work independently to implement optimized dynamics.

The gmsAutoUpdateMode( ) function causes gmsDynUpdate(nil)and gmsUpdate(nil) to be done after each Event is processed ingmsMainLoop( ).

The gmsQAutoUpdateMode( ) function returns the current Auto UpdateMode, either G_ON or G_OFF.

The gmsFastDynPropMode( ) function controls the use of optimizeddynamics, while the gmsDynUpdateMode( ) function affects the way inwhich the update and display processes occur.

The Fast DynProp Mode set to G_ON with thegmsFastDynPropMode( ) function tells SL-GMS that all DynProps inthe application are structured for optimization as described in thechapter entitled of the SL-GMS Reference, and DynProps that areconditional or use expressions should automatically be skipped withoutany diagnostic messages. Setting of the Fast DynProp Mode mustoccur before gmsDynInit( ) is called on a Model.

Calling gmsDynInit( ) triggers the conversion from ordinary dynamicsinto optimized dynamics. If the application does not know the names ofthe variables to define, gmsDynInit( ) and gmsVarRefName( ) may beused to acquire the names of the variables. After defining the variableswith gmsVarDefine( ), gmsDynInit( ) is called a second time to convertto optimized dynamics.

Calling the gmsFastDynPropMode( ) function with G_ON presumesthat all variables are resident in memory each time that gmsUpdate( )or gmsDynUpdate( ) is called. In applications where there are somany variables that not all variables are mapped into memory at alltimes, this function should not be called.

The gmsQFastDynPropMode( ) function returns the current FastDynProp Mode, either G_ON or G_OFF.

The DynUpdate Mode set to G_UPDATE_PASS with thegmsDynUpdateMode( ) function causes the functionality ofgmsDynUpdate( ) to be performed when the gmsUpdate( ) function is



called. Setting of the DynUpdate Mode must occur before thegmsDynUpdate( ) or gmsUpdate( ) functions are called.

The gmsQDynUpdateMode( ) function returns the current DynUpdateMode, either G_UPDATE_PASS or G_DYNUPDATE_PASS.

Calling the gmsAllVarsChanged( ) function tells SL-GMS that allvariables have changed between every update. The normal procedureis to call gmsVarChanged( ) to mark each changed variable. WhengmsAllVarsChanged( ) is called, gmsVarChanged( ) is never calledon any variable. The gmsDynUpdate( ) function must still be called toupdate the dynamics unless the gmsAllVarsChanged( ) function isalso called.

The gmsUseShadowMode( ) function called with G_OFF disables theuse of a Shadow to erase objects when attributes are changed. Theuse of this function is appropriate only if the application never needserasure, uses double-buffering, or clears and redraws screens witheach update.

The gmsQUseShadowMode( ) function returns the current ShadowMode, either G_ON or G_OFF.

The gmsExtentMode( ) function disables extent calculation on objectsthat are not detectable. This disablement makes the update passquicker, but disables clipping — non-detectable objects must not passoutside of the WC-window.

The gmsQExtentMode( ) function returns the current Extent Mode,either G_ON or G_OFF.

The gmsNoFlags( ) function minimizes unnecessary flag propagationwhen attribute changes occur. Calling this function is only useful whenit is known that an object is going to redraw on every update pass.

The gmsNoFlagsMode( ) function is intended for use whengmsAllVarsChanged( ) is used and graphics are redrawn with eithergmsRedraw( ) or the G_WS_DBUFF_CLEAR Workstation option.

The gmsQNoFlagsMode( ) function returns the current No Flags Mode,either G_ON or G_OFF.

The gmsDynUpdArrayFlag( ) function sets an object’s dynarray flag.The dynarray flag is used to optimize dynamics for objects whichreference array values.



SEE ALSOThe chapter entitled in the SL-GMS Reference

SL-GML COMMANDname dynarray int


Dynamics — query and set Variable Definition attributes


SUMMARY

allow the address, count, size, and type attributes of a Variable Definition object to be set and queried; query name of aVariable Definition object.

NAME

gmsVarDefAddress( ), gmsQVarDefAddress( ), gmsVarDefCount( ),gmsQVarDefCount( ), gmsVarDefSize( ),gmsQVarDefSize( ),gmsVarDefType( ), gmsQVarDefType( ),gmsQVarDefName( )

SYNTAX

intgmsVarDefAddress (vardef, address)

id vardef; /* id of Variable Definitionobject*/

void *address; /* address of variable */

void *gmsQVarDefAddress (vardef)


intgmsVarDefCount (vardef, count)


int count; /* number of data elements*/

intgmsQVarDefCount(vardef)




intgmsVarDefSize (vardef, size)


int size; /* size of each data element*/

intgmsQVarDefSize(vardef)


intgmsVarDefType(vardef, type)

id vardef; /* id of Variable Definition object*/

int type; /* type of variable */

intgmsQVarDefType(vardef)


char *gmsQVarDefName(vardef)


DESCRIPTIONA Variable Definition object is created using gmsVarDefine( ) orgmsVarDefineNoTable( ).3 A Variable Definition object’s address, size,and count attributes may be accessed individually.

The gmsVarDefAddress( )4 function sets the address of an existingVariable Definition object, gmsVarDefCount( ) sets the number of data

3. The corresponding functions for State variables are defined in the section State — variables on page 382.

4. The corresponding functions for State variables are defined in the section State — variables on page 382.



elements, and gmsVarDefSize( ) sets the size of each data element ofan existing Variable Definition object.

The gmsVarDefType( ) function sets the type attribute of an existingVariable Definition object. Currently, gmsVarDefType( ) must be calledbefore the first gmsDynUpdate( ) pass occurs on objects referencingthis Variable Definition, otherwise errors may occur in the evaluation ofdynamics descriptions.

The gmsQVarDefType( ) function returns the value of the type attributeof an existing Variable Definition object.

The gmsVarDefType( ) function is typically used to set the type attributeof a Variable Definition in a Variable Definition Table. Furtherinformation about Variable Definition Tables and usage examples ofgmsVarDefType( ) are provided in the section SubModel Preparation onpage 101.

Because both gmsVarDefine( ) and gmsStVarDefine( ) set the typeattribute of a Variable Definition, it is not necessary to usegmsVarDefType( ) in conjunction with these functions.

The gmsQVarDefAddress( ), gmsQVarDefCount( ), andgmsQVarDefSize( ) functions are used to query individual attributes onan existing Variable Definition object. They are passed the id of theVariable Definition object. The gmsQVarDefAddress( ) function returnsthe address. The gmsQVarDefCount( ) function returns the number ofdata elements in the Variable Definition object. The gmsQVarDefSize( )function returns the size of each data element. ThegmsQVarDefType( ) function returns the value of the type attribute of anexisting Variable Definition object.

NOTE: A Variable Definition object’s name attribute cannot be changedin this way. To specify a new Variable Definition object name, anew Variable Definition object must first be created usinggmsVarDefine( ) or gmsVarDefineNoTable( ). ThegmsDynInit( ) function must then be called to re-establish the



links between the Variable Definition object and the VariableReference objects which reference it.

The gmsQVarDefName( ) function returns a string containing the nameof a Variable Definition object. This string should not be freed by thecaller.

The gmsQVarDefName( ) function is typically used to identify a VariableDefinition. For example, an application may have initially created aVariable Definition using gmsVarDefineNoTable( ) and retained apointer to that Variable Definition:

id vardef;static int data;vardef = gmsVarDefineNoTable("var1", &data,

G_INTEGER, 1, 1);

Later, the application needs to determine the name associated withvardef. If the application did not save the name, it could be:

char *name;name = gmsQVarDefName(vardef);

SEE ALSOgmsVarDefine( ), gmsVarDefineNoTable( ), gmsStVarDefine( ),gmsDynInit( )

State — variables on page 382


Dynamics — query Variable References


SUMMARY

query number, name, or address of variables used in Models

NAME

gmsQNumVarRefs( ), gmsQVarRefName( ), gmsQVarRefAddr( )

SYNTAX

intgmsQNumVarRefs (obj)

id obj;

char *gmsQVarRefName (obj, varnum)

id obj;int varnum; /* Variable-Reference number

(1-relative) */

char *gmsQVarRefAddr (obj, varnum)

id obj;int varnum; /* Variable-Reference number

(1-relative) */

DESCRIPTIONThese functions query an object for its Variable References. Byproviding a way for the application to query the List of variablesreferenced in each Model, the application can obtain a subset of thecomplete database for use on each of several display screens. Theapplication also responds to loading new Models by making theconnections between the Models’ variables, using gmsVarDefine( )and gmsDynInit( ) if these connections have not been made previously.

Both gmsQNumVarRefs( ) and gmsQVarRefName( ) can be called onany Graphical Primitive, including Models or Graph objects. Anapplication can discover all variable names used in an object or Model



through the use of these functions, enabling each variable to be definedwithout the application knowing in advance which variables are present.

The gmsQNumVarRefs( ) function returns the number of VariableReferences in the object given as the argument. ThegmsQVarRefName( ) function is then called to return the variable nameof each Variable Reference. Variable References are numberedbeginning with 1 (rather than 0 as in the way arrays start in C language5

applications). The string returned by this function should not bealtered; it is intended for use with gmsVarDefine( ),gmsVarChanged( ), and information retrieval in the application’s owndatabase.

The gmsQVarRefAddr( ) function can be called on any GraphicalPrimitive, including Models or Graph objects. An application canretrieve the variable addresses that were defined for an object or Modelthrough the use of this function. The gmsVarDefine( ) function mustbe used to define the variable’s name, address, and type before thegmsQVarRefAddr( ) function can be called.

SEE ALSOgmsDynInit( ), gmsVarDefine( ), gmsVarChanged( )


5. This function has a FORTRAN counterpart, and FORTRAN does not permit an array index of 0.


Dynamics — Variable Definition Table attached to Models


SUMMARY

initialize dynamics and create a Variable Defintion Table, query VariableDefinition Table associated with an object, query Variable Definition byindex and name in Variable Definition Table, query Variable DefinitionTable count, flag data in Variable Definition Table as "changed"

NAME

gmsModDynInitVarDefTable( ), gmsQVarDefTable( ),gmsQVDTCount( ), gmsQVDTVarDefAtIndex( ),gmsQVDTVarDefByName( ), gmsVDTIndicesChanged( )

SYNTAX

intgmsModDynInitVarDefTable (model, preserve_sub_vdt)

id model;int preserve_sub_vdt;/* G_ON or G_OFF */

idgmsQVarDefTable (object)

id object;

intgmsQVDTCount (vdtable)

id vdtable;

idgmsQVDTVarDefAtIndex (vdtable, index)

id vdtable;unsigned int index;

idgmsQVDTVarDefByName (vdtable, name, index)

id vdtable;char *name;int *index;



intgmsVDTIndicesChanged (vdtable, indices, indices_count)

id vdtable;int indices[];int indices_count;

DESCRIPTIONThe gmsModDynInitVarDefTable( ) function initializes the dynamicdescriptions of all parts in the given Model. It also creates and stores aVariable Definition Table in the Model. If the Model already contains aVariable Definition Table, that table will be destroyed.

The Variable Definitions in the Variable Definition Table are referencedonly by Variable References contained in the Model. Unlike VariableDefinitions in global or State tables, Variable Definitions in a VariableDefinition Table contained in a Model cannot be used by any otherModel.

If the preserve_sub_vdt parameter is set to G_OFF, Variable DefinitionTables contained in SubModels of the given Model will be destroyed bygmsModDynInitVarDefTable( ). If preserve_sub_vdt is set to G_ON,Variable Definition Tables contained in SubModels of the given Modelwill not be affected by gmsModDynInitVarDefTable( ).

The gmsModDynInitVarDefTable( ) function can be used to initializedynamics descriptions on SubModels prior to their replication. If this isdone, there is no need to perform the initialization on thereplicates. When a SubModel is replicated, its Variable Definition Tableis also replicated.Further information about SubModel replication is provided in thesection Model Instance (ModInst) object on page 261.

Once gmsModDynInitVarDefTable( ) has been called on a top-level Model, any gmsDynInit( ) call on that Model has no



effect. The presence of a Variable Definition Table in a top-level Model blocks the effect of gmsDynInit( ) on that Model.

Once gmsModDynInitVarDefTable( ) has been called on a SubModel,any gmsDynInit( ) call on parents of that SubModel has no effect onthe SubModel.

The blocking effect is local; SubModels which do not contain a VariableDefinition Table are processed normally by gmsDynInit( ) calls onparents of the SubModel.

Variable Definition Tables are generally used in the following types ofapplications:

• applications which must use dynamic descriptions in non-replicated SubModels

• applications which have a strong correlation between data-driving structures and Model Instances

• applications which have a strong correlation between data-driving structures and top-level Models

The gmsModDynInitVarDefTable( ) function must be used on anon-replicated SubModel if that SubModel contains dynamicsdescriptions. The gmsDynInit( ) function does not work correctly inthis situation. Only limited forms of dynamics descriptions workcorrectly on a non-replicated SubModel, even when Variable DefinitionTables are used. Further information about these limitations isprovided in the SL-GMS® Reference.

Applications having a strong correlation between data-drivingstructures and Model Instances may use Variable Definition Tables asan alternative to State Variable Definitions (created throughgmsStVarDefine( )).

The Variable Definition names in a Variable Definition Table are local inscope to a single top-level Model or Model Instance. If an applicationuses a separate structure to contain the data driving the dynamics ineach Model Instance in a top-level Model, Variable Definition Tablesprovide a convenient mechanism for binding the data in thosestructures to the Model Instances. Renamed Variables are not needed



in the Model Instances because the names in each Variable DefinitionTable are local in scope to each Model Instance.

A Variable Definition Table can also be used on a top-level Modelwithout interfering with any Variable Definition Tables on ModelInstances in that Model.

Variable Definition Tables should not be used on Model Instancescontained in SubModels.

The gmsQVarDefTable( ) function returns a pointer to the VariableDefinition Table associated with the given Model or Model Instanceobject.

When gmsQVarDefTable( ) is passed a pointer to a Model, the functionreturns a pointer to the Variable Definition Table contained in the Model.

When gmsQVarDefTable( ) is passed a pointer to a Model Instancewhich references a replicated SubModel, the function returns a pointerto the Variable Definition Table contained in the SubModel replicate. ASubModel's Variable Definition Table is replicated when the SubModelis replicated.

When gmsQVarDefTable( ) is passed a pointer to a Model Instancewhich references a non-replicated SubModel, the function returns apointer to a Variable Definition Table contained in the Model Instance.

A Model Instance which references a non-replicated SubModel alwayscontains a replicate of the Variable Definition Table contained in theSubModel. This is done to enable gmsQVarDefTable( ) to return aunique Variable Definition Table for each Model Instance.

The gmsQVDTCount( ) function returns the number of VariableDefinition objects stored in the given Variable Definition Table.

The gmsQVDTVarDefAtIndex( ) function returns a pointer to theVariable Definition object found at the given index in the given VariableDefinition Table.

The gmsQVDTVarDefByName( ) function returns a pointer to theVariable Definition object with the given name found in the givenVariable Definition Table. If a non-NULL index pointer is passed as aparameter, gmsQVDTVarDefByName( ) also sets index to the locationof the found Variable Definition object within the Variable DefinitionTable. If a Variable Definition with the given name is not found in the



Variable Definition Table or a NULL index pointer is passed, the valueof index is not modified.

The gmsVDTIndicesChanged( ) function informs SL-GMS that one ormore application variable values have changed. The function is passeda pointer to a Variable Definition Table (vdtable), an array of indices intothat Table (indices), and the number of indices contained in the array(indices_count). For each index stored in the indices array,gmsVDTIndicesChanged( ) looks up the Variable Definition located atthat index in the Variable Definition Table. This Variable Definition isthen flagged "changed," which later causes dynamics expressionsreferencing that Variable Definition to be evaluated.

The gmsVDTIndicesChanged( ) function is similar togmsVarChanged( ), except gmsVDTIndicesChanged( ) is restricted toa Variable Definition Table located on a single Model or Model Instance.

EXAMPLEThis example describes the use of Variable Definition Tables on Model Instances in a top-level Model. In this example, top-level Model topmodel1 contains two Model Instances whichreference SubModel submodel1. One Model Instance is named inst1,the other is named inst2.

The SubModel submodel1 contains a Text Rectangle. The TextRectangle has the following dynamics description:

*fcolor fcolor_varstext stext_var "%d"

This is the only dynamics description contained in submodel1. A totalof two Variable References are in submodel1: fcolor_var andstext_var.



The application defines the following structures:

/* Structure corresponding to each VariableDefinition */

struct var_template {int data; /* data driving Variable

Definition */int vdt_index;/* index of Variable Definition

in Variable Definition Table */};

/* Structure corresponding to Model Instance of"submodel1" */

struct instance_template {id vdtable;/* Variable Definition Table */struct var_template fcolor;struct var_template stext;

};

/* Array corresponding to parts in "topmodel1" */static struct instance_template topmodel1_parts[2];

In this simple application, the structures (and the topmodel1_partsarray) are hard-coded to correspond exactly to SL-GMS objects. Amore flexible application would use generic structures allocated at runtime.

SubModel PreparationCurrently, Variable Definition Tables cannot be saved in ".m1" or ".g"files. They must be created at run time. To associate a VariableDefinition Table with a Model Instance, the SubModel referenced by thatModel Instance must also have an associated Variable Definition Table,created using gmsModDynInitVarDefTable( ). This call must occurbefore Model Instances referencing that SubModel are created or



loaded from disk. The SubModel must be pre-loaded usinggmsMXGet( ) or gmsM2XGet( ):

id submodel1;submodel1 = gmsMXGet("submodel1", "submodel1");

The SubModel should be marked permanent so it is not inadvertentlyfreed by SL-GMS (causing the Variable Definition Table to be lost):

gmsModPermanent(submodel1, G_ON);

The dynamics descriptions are then initialized, and a Variable DefinitionTable is created by calling the gmsModDynInitVarDefTable( ) function:

gmsModDynInitVarDefTable(submodel1, G_OFF);

The second parameter to gmsModDynInitVarDefTable( ),preserve_sub_vdt, is used only on top-level Models so its value isirrelevant in this example.

The Variable Definition Table stored in submodel1 will never be bounddirectly to data. This table serves only as a template for the VariableDefinition Tables accessed through the Model Instances whichreference submodel1.

Type, size, and count information is loaded into the Variable Definitionsin the Variable Definition Table attached to submodel1. First a pointerto the Variable Definition Table is obtained:

id vdtable;

vdtable = gmsQVarDefTable(submodel1);

The application finds the Variable Definitions called "fcolor_var" and"stext_var" using gmsQVDTVarDefByName( ). This function alsodetermines the indices of the Variable Definitions in the VariableDefinition Table:

id fcolor_vd;id stext_vd;int fcolor_index;int stext_index;



fcolor_vd = gmsQVDTVarDefByName(vdtable,"fcolor_var", &fcolor_index);

stext_vd = gmsQVDTVarDefByName(vdtable,"stext_var", &stext_index);

These indices are stored in the topmodel1_parts array for lateruse. The indices will be the same for both Model Instances:

topmodel1_parts[0].fcolor.vdt_index = fcolor_index;topmodel1_parts[0].stext.vdt_index = stext_index;

topmodel1_parts[1].fcolor.vdt_index = fcolor_index;topmodel1_parts[1].stext.vdt_index = stext_index;

The type, count, and size attributes are set in each Variable Definition:

gmsVarDefType(fcolor_vd, G_INTEGER);gmsVarDefCount(fcolor_vd, 1);gmsVarDefSize(fcolor_vd, 1);

gmsVarDefType(stext_vd, G_INTEGER);gmsVarDefCount(stext_vd, 1);gmsVarDefSize(stext_vd, 1);

At this time, the application may optionally create a SubModel cache forsubmodel1:

gmsModCacheCapacity(submodel1, 2);gmsModCacheCount(submodel1, 2);

If the cache is created, and it is populated usinggmsModCacheCount( ), it is important that gmsModCacheCount( )be called after the SubModel has been initialized using the aboveprocedures. In this way, the Variable Definition Table and the VariableDefinition attribute information stored in the template SubModel will becloned and available in the replicates.



Non-Replicated SubModel InitializationTo make submodel1 non-replicated, gmsModNonReplicate( ) shouldbe called after submodel1 is loaded, but beforegmsModDynInitVarDefTable( ) is called:

gmsModNonReplicate(submodel1, G_ON);

If gmsModNonReplicate( ) is called aftergmsModDynInitVarDefTable( ), the dynamics descriptions insubmodel1 will not be initialized properly.

Top Model PreparationAfter submodel1 has been loaded and initialized, the top-level Modeltopmodel1 can be loaded:

id topmodel1;topmodel1 = gmsMGet("topmodel1", "topmodel1");

Often, top-level Models are loaded implicitly through State activation.

Pointers to the Model Instances named inst1 and inst2 are obtained:

id inst1;id inst2;

inst1 = gmsFindByName("topmodel.inst1");inst2 = gmsFindByName("topmodel.inst2");

A pointer to the Variable Definition Table associated with each ModelInstance is obtained and stored in the topmodel1_parts array:

topmodel1_parts[0].vdtable =gmsQVarDefTable(inst1);

topmodel1_parts[1].vdtable =gmsQVarDefTable(inst2);



For each Variable Definition Table, pointers to the Variable Definitions from within are obtained. It is at this point that the previously-stored Variable Definition indices are used:

id inst1_fcolor_vd;id inst1_stext_vd;id inst2_fcolor_vd;id inst2_stext_vd;

inst1_fcolor_vd = gmsQVDTVarDefAtIndex(topmodel1_parts[0].vdtable,topmodel1_parts[0].fcolor.vdt_index);

inst1_stext_vd = gmsQVDTVarDefAtIndex(topmodel1_parts[0].vdtable,topmodel1_parts[0].stext.vdt_index);

inst2_fcolor_vd = gmsQVDTVarDefAtIndex(topmodel1_parts[1].vdtable,topmodel1_parts[1].fcolor.vdt_index);

inst2_stext_vd = gmsQVDTVarDefAtIndex(topmodel1_parts[1].vdtable,topmodel1_parts[1].stext.vdt_index);

Data addresses are stored in the Variable Definitions:

gmsVarDefAddress(inst1_fcolor_vd,&topmodel1_parts[0].fcolor.data);

gmsVarDefAddress(inst1_stext_vd,&topmodel1_parts[0].stext.data);

gmsVarDefAddress(inst2_fcolor_vd,&topmodel1_parts[1].fcolor.data);

gmsVarDefAddress(inst2_stext_vd,&topmodel1_parts[1].stext.data);



Inform SL-GMS of Data ChangesWhen data associated with a Variable Definition are modified, SL-GMSmust be informed. This causes dynamics descriptions which referencethe Variable Definition to be re-evaluated.

When using a Variable Definition Table, currently only one function caninform SL-GMS of changes to data referenced by that Table:gmsVDTIndicesChanged( ). This function takes as parameters aVariable Definition Table, an array of indices into that Variable DefinitionTable, and the number of indices contained in that array. The indicesspecify which Variable Definitions in the Table should be flagged"changed."

The gmsVDTIndicesChanged( ) function is typically called from theState update( ) method. In this example, for inst1, the data for"fcolor_var" and "stext_var" changed:

int indices[2];int indices_count;

indices[0] = topmodel1_parts[0].fcolor.vdt_index;indices[1] = topmodel1_parts[0].stext.vdt_index;indices_count = 2;

gmsVDTIndicesChanged(topmodel1_parts[0].vdtable,indices, indices_count);

For inst2, the data for "stext_var" changed:

indices[0] = topmodel1_parts[1].stext.vdt_index;indices_count = 1;

gmsVDTIndicesChanged(topmodel1_parts[1].vdtable,indices, indices_count);

SEE ALSOgmsVarDefType( ), gmsVarDefCount( ), gmsVarDefSize( ),gmsDynInit( ), gmsVarChanged( ), gmsStVarDefine( ), gmsMXGet( ),gmsM2XGet( ), gmsModCacheCount( ), gmsModCacheCapacity( ),gmsModNonReplicate( )


Dynamics — variables


SUMMARY

bind Variable References in Models to application program variables;notify SL-GMS that values of application program variables havechanged

NAME

gmsVarDefine( ), gmsVarDefineNoTable( ), gmsVarTypeDefine( ),gmsVarChanged( ), gmsVarChangedAll( ), gmsVarDefChanged( ),gmsVarDefineChanged( ), gmsUnlinkVarDefs( ),gmsRemVarDefLinks( ), gmsFreeAllVarDefs( ), gmsFindVarDefAll( )

SYNTAX

idgmsVarDefine (name, address, type, count, size)

char *name; /* name of variable in Model */void *address; /* address of variable */int type; /* type of variable */int count; /* number of data elements */int size; /* size of each data element */

idgmsVarDefineNoTable (name, address, type, count, size)

char *name; /* name of variable */void *address; /* address of variable */int type; /* type of variable */int count; /* number of data elements */int size; /* size of each data element */

intgmsVarTypeDefine (typecode, size)

int typecode; /* type of variable */int size; /* size of each data element */



intgmsVarChanged (name, address)

char *name; /* name of variable */void *address; /* address of variable */

intgmsVarChangedAll (name, address)


intgmsVarDefChanged (vardef)

id vardef; /* pointer to Variable Definitionobject returned fromgmsVarDefine( ) */

idgmsVarDefineChanged (name, address, type, count, size)

char *name; /* name of variable */void *address; /* address of variable */int type; /* type of variable */int count; /* number of data elements */int size; /* size of each data element */

intgmsUnlinkVarDefs (obj)

id obj; /* object to remove VarDefs from*/

intgmsRemVarDefLinks( )

intgmsFreeAllVarDefs( )

idgmsFindVarDefAll(name, address)




DESCRIPTION

The gmsVarDefine( ) function internally creates Variable Definitionobjects and links them to the Variable Reference objects, created bygmsDynInit( ) in the global Variable Table — connecting VariableReferences in Models to the location where the variable’s value isstored in the application program.

In addition to the location of the variable, SL-GMS must also beinformed about the type of the variable because variables are storedinternally in different forms, depending upon their type. The name ofthe variable as it appears in one or more dynamic descriptions is usedas the first argument, name. The address argument is a location in theapplication where the value for this variable is stored. The typeargument defines the data type of the value found at this address. Thedata type codes, defined in the file "gmscodes.h" distributed in the libdirectory, are shown in the following table:



gmsVarDefine( ) — Valid Codes for "type" Argument

Code Description Hex ValueDecimal Val-

ueBase Types

G_SHORT 2-byte integer 0x1 1G_INTEGER 4-byte integer 0x2 2G_LONG long integer

(size is machine dependent)

0x3 3

G_FLOAT 4-byte real 0x4 4G_PTR_TO_PTR

pointer to an arbitrary pointer

0x5 5

G_DOUBLE 8-byte real 0x8 8G_REALG_CHAR 1-byte char 0x10 16G_STRING pointer to pointer

to a null-terminatedstring

0x100 256

G_POINTER pointer to a byte or character(arbitrary address)

0x200 512

Meta Type (OR’d with Base Types)1

1. Other types can be created using gmsVarTypeDefine( )

G_ARRAY array — OR’d with any of the other types; count argument indicates length of the array

0x4000 16384



EXAMPLE

G_INTEGER|G_ARRAYspecifies an array of integers with a hex value of 0x4002 and a decimal value of 16386.

G_DOUBLE|G_ARRAYspecifies an array of doubles with a hex value of 0x4008 and a decimal value of 16392.

G_CHAR|G_ARRAYspecifies an array of characters with a hex value of 0x4010 and adecimal value of 16400.

Using the correct data type code is important. If the wrong type codeis used, incorrect values may be implemented for updating dynamics, ora bus error can result from an attempt to access memory outside of theprocess limits.

count denotes the number of data elements in a defined variable. sizeis the size of those data elements. If either count or size is greaterthan 1, SL-GMS forces the data type to G_ARRAY.

NOTE: gmsVarDefine( ) must be called on variables whose memoryhave been allocated (e.g., via malloc( )) before an updatepass. Variables which are locally defined to functions are notvalid arguments to gmsVarDefine( ).

The gmsVarDefine( ) function returns a pointer to the Variable Definitionobject created.

A variable may be redefined whenever necessary to change the nameand type attributes to which this variable refers by callinggmsVarDefine( ) again. The gmsDynInit( ) function must then becalled to re-establish the links between the Variable Definition objectand the Variable Reference objects which reference it.



EXAMPLE

The base of an array (i.e., the address of the Variable Definition objectdefining the array) is defined with the the following call :

/* define array to start at "base1" */gmsVarDefine("y_array", &y_array[base1],

G_DOUBLE | G_ARRAY, 100, 1);

If at a later point in the code, the base of the array is to be re-defined in order to scroll the portion of data displayed in a graph,there are two ways to modify the address of the Variable Definitionobject. One method is to use gmsVarDefine( ), in which case thefollowing call is made:

/* define array to start at "base2" */gmsVarDefine("y_array", &y_array[base2],


The Variable Definition object created with gmsVarDefine( ) may also begiven a new address by calling gmsVarDefAddress( ). The count andsize attributes can also be changed by calling gmsVarDefCount( ) andgmsVarDefSize( ).

The gmsVarDefineNoTable( ) function defines variables similar to theway gmsVarDefine( ) does, however no internal global Variable Table iscreated thereby making this function faster than gmsVarDefine( ). Thecalling format (arguments) for gmsVarDefineNoTable( ) is the same asfor gmsVarDefine( ). A Variable Definition object is returned from thisfunction. Eliminating the internal look-up table requires thatgmsVarDefChanged( ) be used to indicate that variables have changedrather than gmsVarChanged( ).

The gmsVarDefineNoTable( ) function must be used in conjunction withgmsVarInitFctn( ) — an application maintains its own list of variablenames and creates only the Variable Definition objects it needs byreturning the appropriate pointers from the callback function set up bygmsVarInitFctn( ).



Variable Definition objects created with gmsVarDefineNoTable( ) are freed with the gmsObjFree( ) function. Variable Definition objects created with gmsVarDefine( ) cannot be freed with gmsObjFree( ).

The gmsVarTypeDefine( ) function defines a new type to SL-GMS.Types are known only by the typecode index and a size (in bytes).typecode must be greater than G_POINTER and less than 0x2000.size must be between 1 and 32,767. A maximum of 256 variable typescan be defined. The gmsVarTypeDefine( ) function is used to definenew data types to SL-GMS, such as arrays, structures, and so on.The data type codes already established by SL-GMS are listed in thetable on page 110.

The gmsVarChanged( ), gmsVarChangedAll( ), andgmsVarDefChanged( ) functions are used to inform SL-GMS that anapplication variable’s value has changed. These functions flag objectsthat are affected by a variable as "needs to be changed" which informsSL-GMS that the graphical objects referring to the named variable mustbe dynamically updated.

If a single graphical object is dependent upon a number of variables,SL-GMS needs only to be notified that one variable has changed, asSL-GMS accesses the values of the other variables while updating theobject. Likewise, if multiple graphics objects are dependent upon asingle variable, SL-GMS needs to be informed only once that the valueof the variable has changed. The gmsVarChanged( ) function is usedin applications that do not contain multiple variables with the sameaddress, whereas gmsVarChangedAll( ) is used in applications that docontain multiple variables with the same address.

The gmsVarChanged( ) function is faster than gmsVarChangedAll( )because it looks only for the first variable referring to a particularaddress, whereas gmsVarChangedAll( ) affects all VariableReferences, not just the first one.

The update is not performed until the gmsDynUpdate( ) function iscalled. The gmsDynUpdate( ) function performs the task ofreferencing the variable’s value and making changes to the object(s).

The gmsVarChanged( ) and gmsVarChangedAll( ) functions can becalled with a nil argument for either the variable name or the variableaddress. The variable name is the same name as the string given ingmsVarDefine( ) and used in the DynProp. If the variable address in



the application is present it should be used, since the search for theVariable Reference is somewhat faster than if the search were basedupon the variable’s name.

EXAMPLEMultiple variables may share the same address. If temp1 and temp2are both defined as having address &temp, when gmsVarChangedAll( )is called, all objects with references to the variables temp1 and temp2are updated.

int temp;gmsVarDefine ("temp1", &temp, G_INTEGER, 1, 1);gmsVarDefine ("temp2", &temp, G_INTEGER, 1, 1);gmsVarChangedAll (nil, &temp);

The gmsVarDefChanged( ) function, like gmsVarChanged( ), is usedto notify SL-GMS that a variable has changed. ThegmsVarDefChanged( ) function is more efficient thangmsVarChanged( ) because it takes a pointer to a Variable Definitionreturned by gmsVarDefineNoTable( ), whereas gmsVarChanged( )must perform a lookup using the address of the variable (passed as aparameter) in the global Variable Table to retrieve the pointer to theVariable Definition.

The gmsVarDefineChanged( ) function defines a variable and marks itas changed. This function is equivalent to calling bothgmsVarDefine( ) and gmsVarChanged( ) on a variable, and it returnsa pointer to the Variable Definition object created.

In most cases, gmsVarDefineChanged( ) is used for first-timedefinition of variables to SL-GMS. In the case where separate calls fordefinition and change are used, a call to gmsVarChanged( ) is requiredto enable a variable defined by gmsVarDefine( ). A variable isrecognized by SL-GMS the first time gmsVarChanged( ) is called for it,and is valid and usable thereafter. Once gmsVarChanged( ) has beencalled, however, there is no way to mark a variable as "not usable."

When using SL-SMS, gmsVarDefine( ) is usually put in a State’sdefinevars method, and gmsVarChanged( ) in the State’s updatemethod or user-defined GISMO Action function.



EXAMPLE

/* initialize variables */static int aa[3] = { 0, 0, 1 };static int ddd = 2;static char fieldbuf[12] = { 0 };static char *string_array[3];static char buf_array[3][6] = { "ABCDE", "FGHIJ",

"KLMNO" };...

/* define variables to SL-GMS and markthem as changed */

/* "aa" has three elements in it */gmsVarDefineChanged ("aa", aa, G_INTEGER, 3, 1);

/* "ddd" has only one element */gmsVarDefineChanged ("ddd", &ddd, G_INTEGER, 1, 1);

/* "fieldbuf" has one element of size12 */

gmsVarDefineChanged ("fieldbuf", fieldbuf,G_CHAR | G_ARRAY, 1, 12);

/* "buf_array" has 3 elements of size6 */

gmsVarDefineChanged ("buf_array", buf_array,G_CHAR | G_ARRAY, 3, 6);

/* "string_array" has three elementsin it */

gmsVarDefineChanged ("string_array", string_array,G_STRING | G_ARRAY, 3, 1);



NOTE: The variable string_array can be used in Variable References asstring_array[indexvar]where buf_array cannot since it is a two-dimensional array.

The gmsRemVarDefLinks( ) function removes the links betweenVariable Reference objects and Variable Definition objects created bythe gmsDynInit( ) and gmsVarDefine( ) functions. Removing theselinks is useful for use in conjunction with the gmsRenamedStr( )function.

In earlier versions of SL-GMS, if the user wished to free an object, twofunction calls were required.

gmsRemVarDefLinks( );

was required before freeing the object to remove all of the linksbetween Variable References and Variable Definitions in the globalVariable Table and

gmsDynInitNoMarks(nil);

was required after freeing the object to re-establish the links for allModels. These two function calls were sometimes time-consuming.

The gmsUnlinkVarDefs( ) function is more efficient and only a singlecall6

gmsUnlinkVarDefs(model);

is required before freeing the object:

gmsObjFree(model);

NOTE: All Variable Definitions must be unlinked before a Model is freed.A crash will occur if a Model is freed with a call to gmsObjFree( )after gmsDynInit( ) is called and before gmsDynEnd( ) is called.All variables defined with gmsVarDefine( ),

6. The gmsUnlinkVarDefs( ) function should be called only once. Multiple calls to gmsUnLinkVarDefs( ) may cause SL-GMS to crash. Multiple calls to gmsDynInit( ) may also cause SL-GMS to crash.



gmsVarDefineNoTable( ), or gmsVarDefineChanged( ) mustbe unlinked using the function gmsUnlinkVarDefs( ) orgmsRemVarDefLinks( ) (or gmsDynEnd( )) before the Model isfreed, otherwise the Variable Definitions will contain pointers tofreed objects.

The gmsFreeAllVarDefs( ) function frees the variable names andvariable addresses in the Variable Definition table. Variable Definitionscannot be freed individually.

The gmsObjFree( ) function is used to free Variable Definition objectscreated with the gmsVarDefineNoTable( ) function.

To avoid erratic behavior, the gmsFreeAllVarDefs( ) function should becalled only after calling either gmsDynEnd( ) or gmsUnlinkVarDefs( ).

The gmsFindVarDefAll( ) function returns a pointer to a VariableDefinition object in the global Variable Table. The gmsFindVarDefAll( )function can be called with a nil argument for either the variable nameor the variable address. The variable name is the same name as thestring given in gmsVarDefine( ) and used in the DynProp. If thevariable address in the application is present it should be used, sincethe search for the Variable Reference is somewhat faster than if thesearch were based upon the variable’s name. If both the address andthe name are passed to gmsFindVarDefAll( ), first it searches byaddress, and then by name.

SEE ALSOgmsDynInit( ), gmsDynUpdate( ), gmsVarDefAddress( ),gmsVarDefCount( ), gmsVarDefSize( ), gmsVarDefType( ),gmsObjFree( )

State — variables on page 382


Edge width attribute


SUMMARY

set the edge width attribute for objects or query the current edge widthattribute

NAME

gmsEWidth( ), gmsLEWidth( ), gmsMEWidth( ), gmsQEWidth( )

SYNTAX

intgmsEWidth (obj, width)

id obj;double width;

intgmsLEWidth (objlist, width)

id objlist;double width;

intgmsMEWidth (width)

double width;

doublegmsQEWidth (obj)

id obj;

DESCRIPTIONThis is a complete set of functions for the manipulation of the differentwidth attributes supported by SL-GMS. The gmsEWidth( ) functionapplies to individual objects, gmsLEWidth( ) applies to Lists of objects,and gmsMEWidth( ) applies to the modal attributes. The queryfunction, gmsQEWidth( ), returns the width attribute of the object, or



the modal attribute if a nil pointer is used. If an object without the widthattribute is queried, 0 is returned.

The modal attribute is referred to as the current width and is appliedwhenever new Primitive objects are created.

DIAGNOSTICSEdge width is specified as a double argument. In most cases, it isdesirable to represent it as an integer. This may be modified in futurereleases of SL-GMS.

No bounds checking is done for attributes. It is assumed that thedevice driver software, at the SL-GWS layer of SL-GMS, deals with theattributes appropriately.

SL-GML COMMAND[name] ewidth real


Events — create

Events — create

SUMMARY

create and modify events; add events to the SL-GMS Workstation eventqueue

NAME

gmsEvent( ), gmsWsAddEvent( ), gmsEvAction( ), gmsEvData( ), gmsEvExtent( ), gmsEvKeysym( ), gmsEvModifiers( ), gmsEvObject( ), gmsEvPoint( ), gmsEvStringC( ), gmsEvStringSO( ), gmsEvTime( ), gmsEvTrigger( ), gmsEvType( ), gmsEvView( ), gmsEvWorkst( )

SYNTAX

idgmsEvent (event_type, workst, destroyCB)

int event_type; /* event type code */id workst; /* Workstation object */int (*destroyCB)();/* optional destroy callback */

intgmsWsAddEvent (workst, event)

id workst; /* Workstation object */id event; /* SL-GMS event object */

intgmsEvAction (event, action)

id event; /* Message event */int action; /* event action code */

intgmsEvData (event, data)

id event; /* Message event */long data; /* event data */


Events — create

intgmsEvExtent (event, extent)

id event; /* Window event */id extent; /* event extent */

intgmsEvKeysym (event, keysym)

id event; /* Key event */unsigned long keysym;/* event keysym */

intgmsEvModifiers (event, modifiers)

id event; /* Key or Locator event */unsigned int modifiers;/* modifier codes */

intgmsEvObject (event, object)

id event; /* Key or Locator event */id object; /* SL-GMS object */

intgmsEvPoint (event, point)

id event; /* Locator event */id point; /* SL-GMS point object */

intgmsEvStringC (event, char_str)

id event; /* Key event */char *char_str; /* C string */

intgmsEvStringSO (event, str_obj)

id event; /* Key event */id str_obj; /* SL-GMS string object */

intgmsEvTime (event, sec, usec)

id event; /* Any SL-GMS event */unsigned long sec;/* event time - seconds */unsigned long usec;/* event time - microseconds */


Events — create

intgmsEvTrigger (event, trigger)

id event; /* Locator event */int trigger; /* event trigger code */

intgmsEvType (event, type)

id event; /* Any SL-GMS event */int type; /* event type code */

intgmsEvView (event, view)

id event; /* Key or Locator event */id view; /* SL-GMS View object */

intgmsEvWorkst (event, workst)

id event; /* Any SL-GMS event */id workst; /* SL-GMS Workstation object */

DESCRIPTIONThe gmsEvent( ) function creates an SL-GMS event. The firstargument, event_type, is an integer code for the desired event type.There are four event subclasses in SL-GMS: Locator, Key, Window, andMessage Events. The event codes refer to event types within the eventsubclasses. The valid event types are found in the header"gmscodes.h" in the lib subdirectory and are listed below by eventsubclass for convenience.

G_LOC_PRESS/* Locator Events */G_LOC_RELEASEG_LOC_MOTION

G_KEY_PRESS/* Key Events */G_KEY_RELEASE

G_WIN_EXPOSE/* Window Events */G_WIN_EXPOSE_RECTG_WIN_RESIZE


Events — create

G_WIN_FOCUS_ING_WIN_FOCUS_OUTG_WIN_ENTERG_WIN_LEAVEG_WIN_MAPG_WIN_UNMAPG_WIN_DESTROY

G_MSG_CLIENT/* Message Events */G_USER_EVENT

The second argument, workst, is an SL-GMS Workstation object. Thethird argument, destroyCB, is a pointer to an optional "destroycallback" function for SL-GMS to call when it has finished processingthe event. If NULL, or if the callback returns 0, SL-GMS will deallocatethe event.

If successful, gmsEvent( ) returns an event object of the specified type.Otherwise, it returns NULL.

gmsEvent( ) creates an event of the specified type that has itsWorkstation, type, and timestamp attributes set. Before an event isadded to the Workstation event queue, it must be populated with dataappropriate for the event type. For instance, locator events need aPoint object, key events need a key, window events need an extent,and message events should have data. Functions are provided that setan event’s data fields. After an event’s data is set, it is added to theWorkstation event queue with the gmsWsAddEvent( ) function.

The gmsEvAction( ) function sets the action attribute of a MessageEvent. The action argument is an integer value. The values assigned tothe action attribute are application dependent.

The gmsEvData( ) function sets the data attribute of a Message Event.The data argument is a long integer value. The values assigned to thedata attribute are application dependent.

The gmsEvExtent( ) function sets the extent attribute of a WindowEvent. The extent argument is a Point list which contains two Pointsthat define a rectangular area. See Point object on page 292 andLinkRef object on page 215 of this document for functions that create


Events — create

Point and LinkRef objects. After the call to gmsEvExtent( ) has beenmade, the LinkRef and Point objects should be freed.

The gmsEvKeysym( ) function sets the keysym attribute of a KeyEvent. The keysym argument is a key code that represents a characterthat does not have a drawn representation such as a function key, or acontrol key. Valid keysym codes are found in the "keysymdef.h" headerlocated in the lib directory.

The gmsEvModifiers( ) funciton sets the modifiers attribute of a Key orLocator Event. The modifiers argument is an unsigned integer thatcontains one or more modifier codes. Event modifiers are the buttons orkeys held down at the time of an Event. Event modifiers provideadditional information about Locator and Keyboard Events. The valid


Events — create

Event modifier codes are contained in "gmscodes.h". This functionused to be called gmsSEvModifiers( ) in earlier versions of SL-GMS.

Event Modifier Codes

Code DescriptionG_LOC_BUTTON_1 Mouse button 1G_LOC_BUTTON_2 Mouse button 2G_LOC_BUTTON_3 Mouse button 3G_LOC_BUTTON_4 Mouse button 4G_LOC_BUTTON_5 Mouse button 5G_LOC_BUTTON_LEFT

(syn. for G_LOC_BUTTON_1)

G_LOC_BUTTON_MIDDLE


G_LOC_BUTTON_RIGHT


G_SHIFT_KEY <SHIFT> keyG_LOCK_KEY <SHIFT LOCK> keyG_CONTROL_KEY <CONTROL> keyG_MOD1_KEY Workstation-dependent

modifier key 1G_MOD2_KEY Workstation-dependent




modifier key 5G_BPAD_BUTTON_0 Bitpad button 1G_BPAD_BUTTON_1 Bitpad button 2G_BPAD_BUTTON_2 Bitpad button 3G_BPAD_BUTTON_3 Bitpad button 4


Events — create

The gmsEvObject( ) function sets the object attribute of a Key orLocator Event. The object argument contains a graphical primitive,group, or SubModel instance object.

The gmsEvPoint( ) function sets the point attribute of a Locator Event.The point argument is a Point object that defines the coordinates of theevent in SL-GMS Internal Coordinates. See Point object on page 292 ofthis document for functions that create Point objects.

SL-GMS Key events contain a String object that supportsinternationalized applications. There are two functions provided forsetting a Key event’s String object. The gmsEvStringC( ) function’schar_str argument points to a C string (NULL terminated characterarray). The gmsEvStringSO( ) function’s str_obj argument is a Stringobject. See Internationalization — String object on page 208 of thisdocument for an explanation of String objects, and functions that createthem.

The gmsEvTime( ) sets the timestamp attribute of any SL-GMS event.The sec argument contains the seconds portion of the timestamp. Theusec argument contains the microseconds portion of the timestamp.

The gmsEvTrigger( ) function sets the trigger attribute of a LocatorEvent. The trigger argument contains the code for the button that


Events — create

triggered the event. The valid codes for this function are the locatorbutton codes found in "gmscodes.h".

.

The gmsEvType( ) function sets the type attribute for any SL-GMSevent. The type argument can contain any valid event type. Thisfunction was called gmsEvCode( ) in earlier versions of SL-GMS.

The gmsEvView( ) function sets the SL-GMS View associated with Keyand Locator Events. The view argument must contain a valid Viewobject.

The gmsEvWorkst( ) function sets the SL-GMS Workstationassociated with any event type. The workst argument must contain avalid Workstation object.

DESTROY CALLBACKA destroy callback can be used to manage a pool of event objects. Theevent pool is created during application initialization and events areadded to the Workstation queue as needed. When SL-GMS executesthe destroy callback, it is an indication that SL-GMS is done with theevent, and the event can be tagged for later reuse. If an event pool isused, care should be taken to clear an event’s data before it is reused.

Locator Event Trigger Codes

Code DescriptionG_LOC_BUTTON_1 Mouse button 1G_LOC_BUTTON_2 Mouse button 2G_LOC_BUTTON_3 Mouse button 3G_LOC_BUTTON_4 Mouse button 4G_LOC_BUTTON_5 Mouse button 5G_LOC_BUTTON_LEFT


G_LOC_BUTTON_MIDDLE


G_LOC_BUTTON_RIGHT



Events — create

KEY EVENTSThe keysym and String object attributes of a Key event are mutuallyexclusive. Only one of them should be set for any given Key event.

EXAMPLECreate a Locator event, and set its point and object attributes.

The following code is designed for use in a State method or aDsModelState callback function.

id customEvent;id inputObject;id workst, evModel;coordVar x,y;idPoint tempPoint;

/* Get the Workstation ID */STMSG_P(gmsQStName(state), "get_window_id",

&workst);

/* Get the Model ID */STMSG_P(gmsQStName(state), "get_model_id",

&evModel);

/* Create a Locator release event */customEvent = gmsEvent(G_LOC_RELEASE , workst, 0);

/* Set the current Model and find the objectnamed "test2" */

gmsCurModel(evModel);inputObject = gmsFindByName("test2");

/* Get the coordinates for the object’sreference point */

x = pntX(gmsQRefPoint(inputObject));y = pntY(gmsQRefPoint(inputObject));

/* Create a Point object */


Events — create

tempPoint = pntNewXY(x,y);

/* Set the event’s object and pointattributes */

gmsEvObject(customEvent, inputObject);gmsEvPoint(customEvent,tempPoint);

/* Free the temporary Point object */pntFree(tempPoint);

/* Add the event to the Workstation eventqueue */

gmsWsAddEvent(workst, customEvent);

SEE ALSOEvents — miscellaneous on page 130

The chapter entitled Event Handling in the SL-GMS Reference


Events — miscellaneous


SUMMARY

miscellaneous Event functions

NAME

gmsWaitEvent( ), gmsDispatchInputEvents( ), gmsDispatchTimerEvents( ), gmsEventPriority( ), gmsQGismoEvent( )

SYNTAX

intgmsWaitEvent (workst)

id workst; /* Workstation/Window object */

intgmsDispatchInputEvents ( )

intgmsDispatchTimerEvents ( )

intgmsEventPriority (flag)

int flag;

idgmsQGismoEvent ( )

DESCRIPTIONThe gmsWaitEvent( ) function causes SL-GMS to wait for an Event tooccur on any Workstation/Window. The workst argument can be set tonil. In the future it may be possible to wait for an Event on a particularWorkstation/Window.

The gmsDispatchInputEvents( ) function dispatches all input Events(non-timer events) from each Workstation/Window. The function



returns 0 if there are no available input Events on any activeWorkstation/Windows.

The gmsDispatchTimerEvents( ) function dispatches all timer Eventsfrom each Workstation/Window. The function returns 0 if no timerEvents have arrived.

The gmsEventPriority( ) function affects the priority of Eventsdispatched in the gmsMainLoop( ) function. It can set the relativedispatching priority of timer and non-timer events. The table belowdescribes how gmsMainLoop( ) dispatches events each time aroundthe event loop, according to the value of flag set bygmsEventPriority( ).

The gmsQGismoEvent( ) function queries the Event which caused aGISMO to trigger. In previous versions of SL-GMS, it was required toIMPORT the SL-GMS internal variable g_event for this purpose.

SEE ALSOThe chapter entitled Event Handling in the SL-GMS Reference

Flag Value Description

G_TIMERS_FIRST dispatch all timer events;dispatch a single no-timer event. This prevents complete starvation of non-timer events when timers are going off very rapidly

G_TIMERS_LAST dispatch all non-timer events;if there are no non-timer events, dispatch all timer events

G_EQUAL_PRIORITY

dispatch all non-timer events;dispatch all timer events

G_NO_TIMERS dispatch all non-timer events;timer events are not dispatched at all


Events — query

Events — query

SUMMARY

query any Event

NAME

gmsQEvAction( ), gmsQEvButtons( ), gmsQEvData( ), gmsQEvExtent( ), gmsQEvKeysym( ), gmsQEvModifiers( ), gmsQEvObject( ), gmsQEvPoint( ), gmsQEvStringC( ), gmsQEvStringSO( ), gmsQEvTime( ), gmsQEvTrigger( ), gmsQEvType( ), gmsQEvView( ), gmsQEvViewIndex( ), gmsQEvWorkst( )

SYNTAX

intgmsQEvAction (event)

id event; /* Message Event */

intgmsQEvButtons (event)

id event; /* Locator Event */

intgmsQEvData (event)

id event; /* Message Event */

idgmsQEvExtent (event)

id event; /* Window Event */

unsigned longgmsQEvKeysym (event)

id event; /* Key Event */

intgmsQEvModifiers (event)

id event; /* Key or Locator Event */


Events — query

idgmsQEvObject (event)


idgmsQEvPoint (event)


intgmsQEvStringC (event, buffer, buffer_size, needed_size)

id event; /* Key event */char *buffer;int buffer_size;int *needed_size;

intgmsQEvStringSO (event, buffer)

id event; /* Key Event */id buffer; /* String Object */

intgmsQEvTime (event, sec, usec)

id event; /* any SL-GMS Event */unsigned long *sec;unsigned long *usec;

intgmsQEvTrigger (event)


intgmsQEvType (event)

id event; /* any SL-GMS Event */

idgmsQEvView (event)



Events — query

intgmsQEvViewIndex (event)


idgmsQEvWorkst (event)

id event; /* any SL-GMS Event */

DESCRIPTIONThe gmsQEvAction( ) function queries the data attribute of a MessageEvent.

The gmsQEvButtons( ) function queries the buttons held down for aLocator Event. This function returns a mask which may contain any ofthe G_LOC_* or G_BPAD_BUTTON_* codes.

For a Locator Event triggered by G_LOC_PRESS, this function returnsthe state of the buttons just after the Event occurred. For a LocEventtriggered by G_LOC_RELEASE, it returns the state of the buttons justbefore the Event occurred. For a LocEvent triggered byG_LOC_MOTION, it returns the current state of the buttons.

The gmsQEvData( ) function queries the data attribute of a MessageEvent.

The gmsQEvExtent( ) function queries a Window’s extent and is usedwith Window Event objects. The function returns a pointer to a linkedlist which contains two Point objects. The values in the Point objectsare in device coordinates (usually pixels). See Point object on page 292and LinkRef object on page 215 of this document for functions thathandle Point and LinkRef objects.

The gmsQEvKeysym( ) function queries the keysym associated with aKey Event. The keysym definitions are found in "keysymdef.h". Thisfunction replaces the gmsQEvKeyCode( ) function in earlier versionsof SL-GMS.

The gmsQEvModifiers( ) function queries the buttons and/or keys helddown when a Locator Event or Key Event occurred. This functionreturns a mask which may contain any of the Event modifier codes:G_LOC_BUTTON or G_BPAD_BUTTON codes, as well asG_SHIFT_KEY, G_CONTROL_KEY, and G_LOCK_KEY. This function


Events — query

returns the state of the modifier keys held down immediately before theEvent occurred.

The gmsQEvObject( ) function queries the object selected by aLocator Event with a G_LOC_PRESS Event code. This function onlyreturns an object for States that have their gismoflag set to G_ON. Ifa State’s gismoflag is turned to G_OFF, this function returns 0.Internally, the gmsQEvObject( ) function calls gmsFindObject( ) onlyif a State’s gismoflag is turned to G_ON for performance optimization.If a State’s gismoflag is turned to G_OFF, the user’s applicationprogram can call gmsFindObject( ) in the loc_press or loc_releasecallback functions, for example. The gmsQEvObject( ) function, whencalled in loc_motion or loc_release, returns the object saved inloc_press.

The gmsQEvPoint( ) function queries the Point at which a LocEventoccurred. The Point object is returned in World Coordinates. Theactual values can be retrieved with the pntX( ) and pntY( ) functions.These return values are in Internal Coordinates.

The gmsQEvStringC( ) function copies the string contained in thegiven Key Event object to the given character buffer. The buffer_sizeargument specifies the maximum number of bytes which can be copiedto the given buffer, including the terminating character. If theneeded_size argument is not equal to NULL, gmsQEvStringC( )stores in the memory location referenced by needed_size an integerspecifying the buffer size required to copy the entire string in the KeyEvent or String Event to the buffer. This is the number of bytes needed,including the terminating character.

The string copied to buffer is always terminated by the null character('\0'), even when the function returns G_OVERFLOW.

If buffer is NULL, the function will still return in needed_size the buffersize required to copy the entire string in the Text or TextRectangle. This enables an application to determine the exact buffersize needed before allocating the buffer.


Events — query

The gmsQEvStringC( ) function returns one of the values indicated in the following table:

If gmsQEvStringC( ) returns G_OVERFLOW, the number returned byneeded_size can be used to allocate a larger buffer. After allocating alarger buffer, if buffer_size is greater than or equal to the number inneeded_size, a second call to gmsQEvStringC( ) will not returnG_OVERFLOW.

The gmsQEvStringSO( ) function copies the string contained in thegiven Key Event object to the given String object. If the buffer in thegiven String object is not large enough to contain the entire string, it isfreed and a larger one is allocated. The String object itself is notreallocated. The function returns 1 if it succeeds and 0 if it fails.

The gmsQEvTime( ) function returns the timestamp of an SL-GMSevent. The timestamp is returned in two portions. The sec argument willcontain the seconds portion if the timestamp. The the usec argumentwill contain the microseconds portion of the timestamp. This function

Value Meaning

G_SUCCESSFUL The function succeeded.

G_OVERFLOW The given buffer was NULL or not large enough to copy the entire contents of the string contained in the Key Event or String Event. If buffer was not NULL, buffer_size characters were copied.

G_INVALID_INPUT One of the parameters to the function was invalid

G_CONVERSION_FAILURE

Information was lost when the wide-character text string in the given object was converted to multi-byte form.


Events — query

replaces the gmsQEvTimeSec( ) and gmsQEvTimeUSec( ) functionsin earlier versions of SL-GMS.

The gmsQEvTrigger( ) function queries the button which triggered aLocator Event. The function is only applicable for Locator Events witha code of G_LOC_PRESS or G_LOC_RELEASE. The trigger may beany one of the G_LOC_* or G_BPAD_BUTTON_* codes.

The gmsQEvType( ) function queries any Event’s code (e.g.,G_LOC_PRESS). This function was called gmsQEvCode( ) in earlierversions of SL-GMS.

The gmsQEvView( ) function queries the View in which the input Event(Locator Event, or Key Event) occurred.

The gmsQEvViewIndex( ) function queries the index of the View in theSL-GMS View list in which the input Event (Locator Event, or KeyEvent) occurred.

The gmsQEvWorkst( ) function queries any Event to determine theWorkstation in which it occurred.

SEE ALSOEvents — miscellaneous on page 130

Internationalization — String object on page 208

The chapter entitled Event Handling in the SL-GMS Reference


Events — timer

Events — timer

SUMMARY

install callback function for timer Event; set timer period for anapplication; enable or disable timer Events for an application; querytimer Event mask

NAME

gmsTimerEventFctn( ), gmsTimerPeriod( ), gmsTimerEventMask( ), gmsQTimerEventMask( )

SYNTAX

intgmsTimerEventFctn (fctn)

int (*fctn)( );

intgmsTimerPeriod (interval)

int interval; /* interval in milliseconds */

intgmsTimerEventMask (action)

int action; /* G_ENABLE or G_DISABLE */

intgmsQTimerEventMask ( )

DESCRIPTIONThe gmsTimerEventFctn( ) function installs a Workstation/Windowcallback function for a timer Event. Under X, the callback function isalways installed for the first Workstation/Window. ThegmsTimerEventFctn( ) function immediately enables timer Events andoverrides the handling of timer Events by SL-SMS (i.e., overridesexecuting an update message for each active State).

The gmsTimerPeriod( ) function resets the timer period to interval aftera timer Event function has been set. If interval is set to 0 (the default),


Events — timer

updates are performed as fast as possible. The gmsTimerPeriod( )function does not alter the Event dispatching order, rather, it affects therate at which Event-handling functions are called. ThegmsTimerPeriod( ) function requires a Workstation to be already inexistence, otherwise it just returns.

NOTE: A call to gmsTimerPeriod( ) must be done after agmsInitStatesOnWs( ) call for timer intervals greater than 0.The gmsInitStatesOnWs( ) function sets the timer interval to 0.

The gmsTimerEventMask( ) function enables or disables all timerEvents. Timer Events are enabled by default when using SL-SMS (i.e.,with a call to gmsInitStates( )). Timer Events are disabled by defaultwhen not using SL-SMS.

NOTE: To disable timer Events for a particular State, the updflag flag forthe State must be set to G_OFF.

The gmsQTimerEventMask( ) function returns the current timer Eventmask, either G_ENABLE or G_DISABLE.

DIAGNOSTICSOn X platforms, if a non-zero timer period is set with thegmsTimerPeriod( ) function, a timer application, gmstimer, is started.gmstimer sends a client message to the main SL-GMS applicationnotifying it that a time interval has passed. There is overheadassociated with the message being passed from one client to another.If the timer period is too small, messages may be sent from thegmstimer process to the main application faster than the system andmain application can process them, thereby causing increasedoverhead and actually slowing down the main application.

Therefore, for X platforms, SL recommends that the timer period be setgreater than the time it takes for the main application to update thescreen. For instance, if the main application takes 250 ms to updatethe screen, the timer period should be set to be somewhat greater than250 ms (say, 300 ms). This setting allows the main application toprocess the timer Events as quickly as they are being sent to it,avoiding a backlog in the X event queue.


Events — Xt and X applications


SUMMARY

enable a main loop external to SL-GMS for dispatching of events; passevents to SL-GMS gathered by an external loop function

NAME

gmsExternalEventLoopFlag( ), gmsQExternalEventLoopFlag( ), gmsProcessLowEvent( )

SYNTAX

intgmsExternalEventLoopFlag (flag)

int flag; /* 0 - normal1 - no gather, may collapse2 - no collapse */

intgmsQExternalEventLoopFlag ( )

intgmsProcessLowEvent (xev)

XEvent *xev;

DESCRIPTIONThe gmsExternalEventLoopFlag( ) function is used to specify thatSL-GMS should not gather events, but that an application event loopfunction external to SL-GMS will do this instead. A three-level flag isused to control how events are gathered. The value of flag has thefollowing effect:



A value of 0 for flag indicates that SL-GMS is to do the event gathering.A value of 1 or 2 indicates that SL-GMS should not gather eventsbecause an application event loop function external to SL-GMS is beingused for this purpose. The value of 1 for flag specifies that SL-GMS isnot to gather events but may compress and/or extract related eventswhile processing an event that it has received from the application’sevent loop function. For example, this will avoid multiple redraws inresponse to an expose and/or a configuration change of thewindow-manager window where SL-GMS is drawing dynamic graphics.The value of 2 for flag specifies that SL-GMS is not to gather orcompress and/or extract related events while processing an event thatit has received from the application’s event loop function. Theapplication is assumed to have complete responsibility for suchartifacts as multiple redraws in response to expose and/or configurationchanges to the window-manager window where SL-GMS is drawingdynamic graphics.

The gmsQExternalEventLoopFlag( ) function returns the current value of the flag set by the gmsExternalEventLoopFlag( )function. The default value is 0 (in the case that the flag value is not set by an explicit call tothe gmsExternalEventLoopFlag( ) function).

Flag Value Description

0 normal SL-GMS event gathering

1 SL-GMS does not gather, but may compress and/or extract related events

2 SL-GMS does not gather nor compress and/or extract related events



SEE ALSOgmsWsLowEventFctn( ), gmsNonWsLowEventFctn( ) — for furtherinformation about their use, especially in conjunction with the internalSL-GMS event loop function, gmsMainLoop( )

Without the functions documented in this section, the dispatching ofEvents is done inside of gmsMainLoop( ).

The gmsmotifrun program of the gmsmotif on-line example showshow these functions are used.

The appendix entitled SL-GMS Interface with the X Toolkit and XWindows in the SL-GMS Reference.


Extent

Extent

SUMMARY

return the extent and center of an object; set system-wide extentcalculation flag

NAME

gmsQExtent( ), gmsLQExtent( ), gmsQPartExtent( ), gmsQExtCenter( ), gmsLQExtCenter( )

SYNTAX

idLinkRefgmsQExtent (obj)

id obj;

idLinkRefgmsLQExtent (objlist)

idLinkRef objlist;

idLinkRefgmsQPartExtent (owner, object)

id owner; /* the owning object */id object; /* the object to query */

idPointgmsQExtCenter (obj)

id obj;

idPointgmsLQExtCenter (objlist)

idLinkRef objlist;

DESCRIPTIONThe gmsQExtent( ) function is used to obtain a Point List containingtwo Points which define the extent of any SL-GMS Graphical Primitiveobject. The gmsQExtent( ) function returns the extent of an object


Extent

only within its own coordinate system, that is, it takes into account onlythe Points defining the object and any transformation on that object. Ifa Model or Group containing that object has a transformation applied toit, that transformation is not applied to the extent Points returned whengmsQExtent( ) is called on that object itself. The gmsLQExtent( )function does the same thing, but merges the extents of all the objectson the given List. The returned LinkRef should be freed withrefKilAll( ).

The gmsQExtCenter( ) function returns, for any SL-GMS object, asingle Point object which is the center of the extent of the object. ThegmsLQExtCenter( ) function does the same thing, but for the mergedextent of all the objects in the List. The returned Point should be freedwith pntFree( ).

The table Center Point and center of extent illustrates the center of theextent of various types of SL-GMS objects and compares it to thecenter Point returned with the function gmsQCenter( )1 described on

1. The gmsQCenter( ) function can be used only for Circle, Pie, and Sector objects because they are the only objects that are defined using a center Point.


Extent

page 1-24. The dashed line around the objects indicates the extent ofthe object, and the "X" indicates the center of the extent.

Center Point and center of extent

ObjectCenter Point



gmsQExtCenter( )

Rectangle zero

(Use the function gmsQExtCenter( ) on page 1-144)

Model Instance

zero


Group of objects

zero



Extent

The gmsQPartExtent( ) function queries the extent of an object withinthe coordinate system of an owner object. This function combines thetransformation of the given owner and all Groups, Models, or Instancesbetween it and the given object, and applies it to the extent of the objectwhen it is returned.

DIAGNOSTICSThe extent and center of Text objects is not set until the Text object isdisplayed because the extent of Text objects is Workstation-dependent.

Circle

Sector

Pie

Center Point and center of extent<Helv7>(continued)

ObjectCenter Point



gmsQExtCenter( )


Extent

SEE ALSOgmsCenter( ), gmsQCenter( )

SL-GML COMMANDSname extent

name center


Fill direction and fill percent attributes


SUMMARY

set the fill direction or fill percent attribute for percent-filled objects

NAME

gmsFDir( ), gmsLFDir( ), gmsMFDir( ), gmsFPercent( ), gmsLFPercent( ), gmsMFPercent( ), gmsQFDir( ), gmsQFPercent( )

SYNTAX

intgmsFDir (obj, filldir)

id obj;int filldir;

intgmsLFDir (objlist, filldir)

idLinkRef objlist;int filldir;

intgmsMFDir (filldir)

int filldir;

intgmsFPercent (obj, fpercent)

id obj;double fpercent;

intgmsLFPercent (objlist, fpercent)

idLinkRef objlist;double fpercent;

intgmsMFPercent(fpercent)

double fpercent;



intgmsQFDir (obj)

id obj;

doublegmsQFPercent (obj)

id obj;

DESCRIPTIONThese are a complete set of functions for the manipulation of thespecial attributes for percent-filled objects supported by SL-GMS.

The gmsFDir( ) function applies to individual objects, gmsLFDir( ) toLists of objects, and gmsMFDir( ) to the modal attributes.

The four possible fill directions are represented in the following table.

Other values are silently converted to the default of 0.

The gmsFPercent( ) function changes the percent-filled attribute of thegiven object. This function works on all FillEdge objects.

Valid fill percents range from 0 to 100. Values less than 0 are set to 0,and values greater than 100 are set to 100.

The gmsLFPercent( ) function changes the "percent-filled" attribute forobjects on the List.

The gmsMFPercent( ) function sets the modal fill percent attribute.The fpercent argument is a real number between 0.0 and 1.0.

The gmsQFPercent( ) function queries an object’s fill percent attribute.

The modal attribute is referred to as the "current" fill direction or fillpercent and is applied whenever new percent-filled objects are created.

Fill DIrections

0 fill from bottom 1 fill from left 2 fill from top 3 fill from right



DIAGNOSTICSAs noted above, attributes are silently constrained to the stated limits.

SL-GMS was enhanced in version 4.0e1 to percent-fill objects otherthan Rectangles. In earlier releases, all subclasses of G_FillEdge_30,except G_Rect_30, were displayed as if the percent-fill attribute wereset to 100%. The actual value of the percent-fill attribute was ignored.As of version 4.0e1, all subclasses of G_FillEdge_30 reflect the valueof the percent-fill attribute when displayed.

Because the percent-fill attribute was ignored for many Polygons,Models created with pre-4.0e1 releases of SL-GMS may containfpercent errors which were not noticeable before.

For upward compatibility, the 4.0e release converts all pre-4.0e1 ".m1"files when they are loaded; all subclasses of G_FillEdge_30, exceptG_Rect_30, are given an fpercent value of 100%. By performing anm1g (using release 4.0e of SL-GML) for all existing pre-4.0e1 ".m1"files, all ".g" files are converted. Since ".m1" files containing Graphobjects cannot be saved with m1g, ".g" files for Graphs which havefpercent errors must be edited with a text editor.

SEE ALSOgmsFRect( ), gmsRFRect( )

SL-GML COMMANDS[name] percent real

[name] direction int


Filled

Filled

SUMMARY

set, reset, or query the filled attribute an object

NAME

gmsFilled( ), gmsLFilled( ), gmsMFilled( ), gmsQFilled( )

SYNTAX

intgmsFilled (obj, filled)

id obj;int filled;

intgmsLFilled (objlist, filled)

idLinkRef objlist;int filled;

intgmsMFilled (filled)

int filled;

intgmsQFilled (obj)

id obj;

DESCRIPTIONThe gmsFilled( ) function sets or resets the filled attribute for an object— set to 1, the object is filled and when set to 0, the object is unfilled.If an object which is not closed is filled, a line connecting the first and


Filled

last Points in that object form the border to the filled area, although noEdge is created.

The gmsLFilled( ) function sets the filled attribute for all the objects inthe given List.

The gmsMFilled( ) function sets the modal filled attribute, whichapplies to all objects subsequently created.

The gmsQFilled( ) function returns the filled attribute of the givenobject.

SL-GML COMMAND[name] filled int


Find file

Find file

SUMMARY

install a user-defined find file function

NAME

gmsSetFileFindFctn( )

SYNTAX

intgmsSetFindFileFctn (funct, base_filter,

extension_filter)char *(*funct)();char *base_filter;char *extension_filter;

DESCRIPTIONThe gmsSetFindFileFctn( ) installs a user-defined find file function. Afind file function is used to enhance, or override the path and file nameused by SL-GMS when reading color definition, font definition, Model,and bitmap data. This capability allows SL-GMS to read informationfrom directories that are not in the library search path, or to read datafrom a temporary file that contains information retrieved from adatabase or network connection.

funct specifies the address of the user-defined find file function.

base_filter specifies a list of base file names seperated by the pipecharacter, ’|’. The user-defined find file function is called when SL-GMSneeds data from a file with a base name that matches one in the list. If a


Find file

a matching file is found from the contents of base_filter, theextension_filter is ignored.

extension_filter specifies a list of file extensions seperated by periods.The user-defined find file function is called when SL-GMS needs datafrom a file with an extension that matches one in the list.

The user-defined find file function is deactivated by callinggmsSetFindFileFctn( ) with all three arguments set to NULL.

The user-defined find file function must accept three character pointerarguments, and return a character pointer as shown below.

char *myfunct (base_name, ext, pathname)

char *base_name;char *ext;char *pathname;

{}

Where base_name is the base file name of the file from which SL-GMSneeds data, ext is the list of file extensions that SL-GMS used in itssearch for the desired file, and pathname is the complete path andname of the file. The pathname argument will only contain informationwhen SL-GMS has already found the file.

A NULL return value tells SL-GMS to continue file operations using theexisting file path and name. A non-NULL return value supplies SL-GMSwith a replacement path and name.

To override color and font defintion files, there are several additionalconditions that must be met. The first condition is that the user-definedfind file function must be installed before the first Workstation/Windowis created. Secondly, the user-defined find file function will be calledtwice for a color definition file.

Note that if a find file function is installed for .m2 files, it will also becalled for .m1 files.


Find file

LIMITATIONSOnly one find file function is allowed. Multiple functions cannot beinstalled for different base and extension filters.

Find file functions do not currently work with the PostScriptWorsktation.

EXAMPLETo force the reading of all bitmap files from a common project directory:

/* install function */gmsSetFindFileFctn(bmfunc, "", ".i.bmp.xwd");...char *bmfunc (base, ext, full)

char *base;char *ext;char *full;

{char newpath[G_MAXFILENAME];char pathbase[G_MAXFILENAME];char extlist[80];char *sptr;FILE *fp;strcpy(extlist, ext);strcpy(pathbase, "/acct_proj/bitmaps/");strcat(pathbase, base);sptr = strtok(extlist, ".");while (sptr) {

strcpy(newpath, pathbase);strcat(newpath, ".");strcat(newpath, sptr);fp = fopen(newpath, "r")if (fp) break;sptr = strtok(NULL, ".");

}if (fp) {

fclose(fp);


Find file

return newpath;}else {

return NULL;}

}


Find object

Find object

SUMMARY

find an object

NAME

gmsFindObject( ), gmsVuFindObject( ), gmsFindByName( )

SYNTAX

idgmsFindObject (locevent, aperture, depthFlag)

id locevent;double aperture;int depthFlag;

idgmsVuFindObject (view, point, aperture, depthFlag)

id view;idPoint point;double aperture;int depthFlag;

idgmsFindByName (name)

char *name;

DESCRIPTIONThe gmsFindObject( ) function is intended to be used within a StateEvent handler. This function finds the object closest to the Point and inthe View, specified by a Locator Event. If Views overlap, only objectsin the top View (the last View displayed) are found. The description forthe gmsView( ) function in this manual provides additional information.

depthFlag specifies how deep to look before returning a pointer to anobject. If depthFlag is 0 (zero), it searches at the highest level in theModel (i.e., a Group, rather than an object in the Group, is returned). IfdepthFlag is 1, the search is one level deep within Groups and the


Find object

nearest object one level deep is returned. If depthFlag is 2, the objectreturned may be part of a Group within another Group (two levelsdeep). If depthFlag is 4, for example, and there are only two levels ofparts in the Model, depthFlag is treated as 2 (i.e., as far down aspossible). In summary, the larger the depthFlag, the deeper the levelof the object returned.

The aperture controls the resolution of the mouse, that is, it specifiesan extent around a mouse pick in which to search for objects. Typically3.0 is used for aperture.

EXAMPLETo find the object closest to a Locator Event and print its name:

intloc_press (state, event)

id state;id event;

{

id object;object = gmsFindObject (event, 3.0, 1);printf ("Object Name = %s\n",

gmsQObjNameStr (object));}

The gmsVuFindObject( ) function does not require a Locator object,and hence is intended for use outside of a State Event handler.

The gmsFindByName( ) function searches for an object with the givenname in the Name List of the current Model. If not found, it searches inthe Name List of the Model specified by concatenating Model names,as in "gms.model.model1.obj". The object named must either be in thecurrent Model or in the Name List of the SubModel or Model specifiedby the concatenated Name List.

A concatenated Name List always begins with "gms", followed by a dot(.) and the name of a Model. The names of SubModels or InstancedModels may follow, separated by dots. The last name in the string isthe name of the object itself. The name "gms" followed by Model or


Find object

Instance names directs SL-GMS to search by descending Model NameLists to the Name List where the object’s name resides.

The gmsFindByName( ) function can be used to search for Models,objects, External Models, Workstations, and Views that have beennamed.

EXAMPLEIf a Model named "valve" is instanced in a Model named "engine," andthe user wants a pointer to an object named "seal" in the model "valve,"the concatenated name list is "gms.engine.valve.seal".

id object;object = gmsFindByName("gms.engine.valve.seal");

SEE ALSOgmsView( ), gmsWind( ), gmsLPFndPt( )


Font Name Index

Font Name Index

SUMMARY

determine font index from a font name

NAME

gmsQWsFontNameIndex( )

SYNTAX

intgmsQWsFontNameIndex (ws, font_name, font_index)

id ws;char *font_name;int *font_index;

DESCRIPTIONThe gmsQWsFontNameIndex( ) function determines the SL-GMSindex associated with the given font name on the given Workstation. Ifthe given name is associated with an index, the function stores theSL-GMS index in the memory location referenced by the font_indexparameter and returns 1. If the given name is not associated with anindex, the function returns 0 and does not modify the memory locationreferenced by the font_index parameter. Currently, this function worksonly for the Windows NT Workstation class.

Font name syntax is described in the SL-GMS® Reference.

EXAMPLEAssume an SL-GMS application running under Windows NT uses thesystem font dialog to select a font to be used within SL-GMS.

The application uses a "fontdef.dat" file that enumerates all possiblefonts and styles available on the system. The application then createsa font name consistent with the format of "fontdef.dat" and thegmsQWsFontNameIndex( ) function retrieves the SL-GMS index


Font Name Index

associated with that font name. The index is used to modify the fontindex of a Text or Text Rectangle object.

The following is an example of a call to gmsQWsFontNameIndex( ):

intset_text_font (ws, text_object, fontname)

id ws;id text_object;char *fontname; /* Ex: "Times New Roman-Bold-Italic"

*/{

int success, index;

success = gmsQWsFontNameIndex(ws, fontname,&index);

if (!success) {printf("Cannot find font %s\n", fontname);return 0;

}gmsTFont(text_object, index);return 1;

}

The file "/demo/fonts/fontdef.nt_all" enumerates the basic Windows NTTrueType fonts available to SL-GMS. The "/demo/fonts/README" fileprovides more information about "fontdef.dat" and its uses.


Free object

Free object

SUMMARY

free an object or List of objects

NAME

gmsObjFree( ), gmsLObjFree( )

SYNTAX

intgmsObjFree (obj)

id obj;

intgmsLObjFree (objlist)

id objlist;

DESCRIPTIONThe gmsObjFree( ) function is used to delete any Graphical Primitive,View, inactive State, or Model objects, created using SL-GMS functioncalls from the Graphical Modeling Hierarchy, that is, by freeing memoryallocated for them. It is also used to delete ColDef objects created bygmsQWsColDef( ) and Variable Definition objects created withgmsVarDefineNoTable( ).1 Programs should always free objects whenthey are no longer needed, otherwise the data area allotted to theprogram continues to grow, eventually degrading system performance.

Any pointer to the object should always be set to 0 after freeing theobject.

1. Variable Definitions created with gmsVarDefine( ) or gmsStVarDefine( ) cannot be freed with this function.


Free object

EXAMPLEid an_object;

. . .

gmsObjFree(an_object)

an_object = 0;

The gmsLObjFree( ) function performs the same function on a List ofSL-GMS objects. The List itself is not freed. The refFree( ) function isused to free the List.

NOTE: A crash will occur if a Model is freed with a call to gmsObjFree( )after gmsDynInit( ) is called and before gmsDynEnd( ) is calledif the Variable-Definitions remain linked.

All variables defined with gmsVarDefine( ) orgmsVarDefineChanged( ) must be unlinked using the functiongmsUnlinkVarDefs( ) or gmsRemVarDefLinks( ) (orgmsDynEnd( )) before the Model is freed so that theVariable-Definitions do not contain pointers to freed objects.

For example, the following functions can be called in sequence tofree a Model after gmsDynInit( ) has been called on that Model:

gmsUnlinkVarDefs(model);gmsObjFree(model);

SEE ALSOgmsObjFree( ) does not work on Variable-Definition objects, except forthose created with gmsVarDefineNoTable( ), nor low-level objectssuch as LinkRefs or Points. Variable-Definition objects must be freedusing gmsFreeAllVarDefs( ) or gmsStFreeAllVarDefs( ). LinkRefsmust be freed using refKilAll( ), and Points must be freed usingpntFree( ).

SL-GML COMMAND name free


General transformation — absolute


SUMMARY

set an absolute general transformation

NAME

gmsASTran( ), gmsLASTran( ), gmsCASTran( ), gmsMASTran( )

SYNTAX

intgmsASTran (obj,d0,d1,d2,d3,d4,d5)

id obj;double d0; d1, d2, d3, d4, d5;

intgmsLASTran (objlist,d0,d1,d2,d3,d4,d5)

idLinkRef objlist;double d0; d1, d2, d3, d4, d5;

intgmsCASTran (objlist, d0,d1,d2,d3,d4,d5)

id objlist;double d0; d1, d2, d3, d4, d5;

intgmsMASTran (d0,d1,d2,d3,d4,d5)

double d0; d1, d2, d3, d4, d5;

DESCRIPTIONThese functions define an absolute generalized 2x3 transformation.The six double arguments are placed into a 2x3 transformation matrix



and added to the objects. The order of the function arguments in thematrix is:

| d0 d3 || d1 d4 || d2 d5 |

Any previously existing transformation matrices belonging to theobjects are lost. The gmsXTran( ) function is used to apply an existingtransformation to an object’s Points, or gmsRSTran( ) is used tocombine transformations.

The gmsASTran( ) function operates on an individual object, while thegmsLASTran( ) function operates on a List of objects. The object(s) isfirst erased, the transformation applied, and the object(s) is redrawn.The erase and redisplay occur immediately only if SL-GMS is inImmediate Update Mode.

The gmsCASTran( ) function applies to the creation of future Clones orInstances. The gmsMASTran( ) function sets a modal transformationwhich applies to all objects subsequently created.

EXAMPLES

Translation:The function call

gmsASTran(obj, 1, 0, Dx, 0, 1, Dy);

where Dx is the translation in the x-axis direction, and Dy is thetranslation in the y-axis direction, produces the matrix:

| 1 0 || 0 1 || DxDy|



Scaling:The function call

gmsASTran(obj, Sx, 0, 0, 0, Sy, 0);

where Sx is the scaling factor in the x axis direction, and Sy is thescaling factor in the y axis direction, produces the matrix:

| Sx0 || 0 Sy|| 0 0 |

Rotation:The function call

gmsASTran(obj, cos(theta), -sin(theta), 0,sin(theta), cos(theta), 0);

where theta (θ) is the angle of rotation about the origin produces thematrix:

| cosθ sinθ || -sinθcosθ|| 0 0 |

If a combination of transformations is set, for example a translation,then a scaling, the values inside of the matrix are arrived at by use ofstandard matrix multiplication.

SEE ALSOgmsRSTran( ), gmsLRSTran( ), gmsCRSTran( ), gmsMRSTran( ), gmsXTran( )


General transformation — relative


SUMMARY

apply a relative general transformation to an object

NAME

gmsRSTran( ), gmsLRSTran( ), gmsCRSTran( ), gmsMRSTran( )

SYNTAX

intgmsRSTran (obj,d0,d1,d2,d3,d4,d5)

id obj;double d0, d1, d2, d3, d4, d5;

intgmsLRSTran (objlist, d0,d1,d2,d3,d4,d5)

idLinkRef objlist;double d0, d1, d2, d3, d4, d5;

intgmsCRSTran (d0,d1,d2,d3,d4,d5)

double d0, d1, d2, d3, d4, d5;

intgmsMRSTran (d0,d1,d2,d3,d4,d5)

double d0, d1, d2, d3, d4, d5;

DESCRIPTIONThese functions define a relative generalized 2x3 transformation. Thesix double arguments are placed into a 2x3 transformation matrix andapplied to the objects. (The discussion on page 164 providesadditional information about the 2x3 matrix.) Any transformationmatrices belonging to the objects are combined with this transformationmatrix.

The gmsRSTran( ) function operates on an individual object, while thegmsLRSTran( ) function operates on a List of objects. The object(s) is



first erased, the transformation applied, and the object(s) is redrawn.The erase and redisplay occur automatically only if SL-GMS is inImmediate Update Mode.

The gmsCRSTran( ) function applies to the creation of future Clones orInstances. The gmsMRSTran( ) function sets a modal transformationwhich applies to all objects subsequently created.

SL-GML COMMANDS[name] tran d0 d1 d2 d3 d4 d5

mtran d0 d1 d2 d3 d4 d5


GISMOs — initialization

GISMOs — initialization

SUMMARY

initialize the GISMO Manager

NAME

gmsInitGismos( )

SYNTAX

intgmsInitGismos( )

DESCRIPTIONThe gmsInitGismos( ) function initializes the GISMO Manager; it iscalled automatically as part of gmsMainInit( ). The standard GISMOvariables defined by gmsInitGismos( ) are: _ _selected_object, _ _button_hilite, _ _button_index,_ _locator, and button_label. It should be noted that, with theexception of button_label, these are hidden variables and should notbe renamed. The GISMO Action functions are also defined bygmsInitGismos( ). A complete list of the GISMO Action functions isfound in the appendix entitled SL-GMS GISMO Library Reference in theSL-GMS Reference.


GISMOs — processing

GISMOs — processing

SUMMARY

invoke an object’s GISMO function as a result of a key press

NAME

gmsFKeyProcess( )

SYNTAX

intgmsFKeyProcess (string)

char *string;

DESCRIPTIONThe gmsFKeyProcess( ) function processes a function key press bylooking in the current Model, of the current State, for an object named"string". If found, it invokes the object’s GISMO function so the objectbehaves as if it were selected with the mouse. If not found, it attemptsto send a message to the current State class (only if the Screen StateManager is active).


Gradient fill attribute


SUMMARY

set the gradient attribute for filled objects

NAME

gmsFGradient( ), gmsLFGradient( ), gmsQFGradient( )

SYNTAX

intgmsFGradient (obj, points)

id obj;id LinkRefpoints;

intgmsLFGradient (objlist, points)

id LinkRefobjlist;id LinkRefpoints;

idLinkRefgmsQFGradient (obj)

id obj;

DESCRIPTIONThese functions set and query the gradient attribute for filled objects.The gmsFGradient( ) function sets the gradient attribute on a singleobject, while the gmsLFGradient( ) function works on a list of objects.

The gradient attribute passed to these functions is a list of points. Thelist must contain a minimum of four points (or be NULL) and can containup to seven points. A NULL list is used to remove the gradient attributefrom an object.

The first point in the gradient attribute point list contains the gradientstyle and height. The height information is used only for the elliptic styleof gradient. The second and third points are explained under each



gradient style in the table below. The fourth through seventh pointsdefine gradient color intervals.

The following table summarizes point list information.

NOTE: The height, x and y values are in internal coordinates. Thepercent values are percentages multiplied by 100. Therefore,90.4 percent would be 9040.

The gradient color intervals allow more than one color change to occurin the gradient. There can be up to four color intervals. Each intervaltakes up a percentage of the total gradient distance (the distance fromthe start to the end point or the elliptic height). The gradient shadesfrom fcolor to color 1 then from color 1 to color 2, and so on, up to color4 in the distances defined by each percent. All interval percents add upto 10000 (100 percent). The fcolor attribute defines the start color andthe color in the last interval is the end color.

The following three styles of gradient fill are available.

G_FGRADIENT_STYLE_LINEAR_CYCLIC This style is defined by a start and end point. The start and end pointsare in the second and third points of the gradient attribute List. Theobject is filled starting with the fcolor at the start point and shades tothe end color at the end point. Past the start and end points the colorshading will cycle back and forth between the start and end colors.

Point Description Containspoint 1 gradient style style and heightpoint 2 start point or focus 1 x and ypoint 3 end point or focus 2 x and ypoint 4 color interval 1 percent and color[point 5] color interval 2 percent and color[point 6] color interval 3 percent and color[point 7] color interval 4 percent and color



G_FGRADIENT_STYLE_LINEAR_ACYCLICThis style is defined by a start and end point. The start and end pointsare in the second and third points of the gradient attribute List. Thisstyle fills the object starting with the fcolor at the start point and shadesto the end color at the end point. The color before the start point will befcolor. The color after the end point will be end color. The color shadingwill not cycle with this style.

G_FGRADIENT_STYLE_ELLIPTICThis style is defined by a height and two focus points. The second andthird points in the gradient attribute List are the two foci (focus 1 andfocus 2) of an ellipse. The object will be filled starting with the fcolor atthe line that connects the two foci and shade to the end color at theperpendicular distance, height, away from the line. This forms a shadedellipse around the foci. This style does not cycle the colors (the areapast the ellipse defined by the height will be filled with the end color). Ifthe two foci points are equal, the gradient will be circular and the heightparameter is equivalent to the circle's radius.

The gmsQFGradient( ) function returns the gradient attribute point listfrom a filled object. A NULL pointer will be returned if there is nogradient attribute set on the object. The returned LinkRef should befreed with refKilAll( ).

SL-GML COMMANDSname fgradient int real x y x y real int [real int[real int[real int]]]

LIMITATIONSThe gradient fill is unavailable for dynamics. Percent fill does not workwith the gradient fill. The gradient attribute is not a modal attribute.


GraphAxis object

GraphAxis object

SUMMARY

create a GraphAxis object and set its attributes

NAME

gmsGraphAxis( ), gmsCoordLimits( ), gmsValueLimits( ), gmsMajorSpacing( ), gmsMinorSpacing( )

SYNTAX

idgmsGraphAxis (name, axisline, majtick, mintick,

ticklabel)char *name;id axisline;id majtick;id mintick;id ticklabel;

intgmsCoordLimits (obj, pointlist)

id obj; /* GraphAxis or GraphTrace */idLinkRef pointlist;

intgmsValueLimits (obj, min, max)

id obj;double min;double max;

intgmsMajorSpacing (obj, spacing)

id obj;double spacing;


GraphAxis object

intgmsMinorSpacing (obj, spacing)

id obj;double spacing;


GraphAxis object

DESCRIPTIONThese functions create and set the attributes of GraphAxis objects. AGraphAxis requires several objects for use as templates and someattributes to be set before a single, labeled axis can be displayed. AGraphAxis object uses axisline as the template object for the axis.The original template object is not "consumed," only its attributes arecopied and used. The template Line’s Point List is also not used. Theends of an axis are defined by using the gmsCoordLimits( ) function.

A GraphAxis object also requires three other template objects: two tickmarks and a label (Text) object. The two tick marks are line segmentsdefined with the point (0,0) at one end. The orientation and length ofthese Lines are copied when these Lines are cloned to be used as tickmarks. For example, a major tick mark for the x-axis two units long has(0,0) and (0,-2) as end points. Because the gmsPlotClear( ) functionerases the entire area within the axes, it is not advisable to extend tickmarks into the area where traces are drawn and erased.

The tick label is a Text object that is cloned and placed relative to majortick marks. It should be built relative to the major tick mark Linetemplate. For example, if the same two-unit major tick mark in thepreceding example is used, the Text object used for the tick labelshould have its center below the point (0,-2). The text within the Textobject is replaced when the axis is displayed depending upon the majortick mark spacing.

The gmsValueLimits( ) function sets the values used to label theendpoints of the axis. The minimum endpoint is always labeled,however, the maximum endpoint is labeled only if the major tick spacingis chosen appropriately. The major tick spacing is set with thegmsMajorSpacing( ) function. The major tick spacing determineswhere major tick marks are drawn. The maximum endpoint is labeled ifthe major tick spacing evenly divides the range between the maximumand the minimum established by the call to gmsValueLimits( ). ThegmsMinorSpacing( ) function sets the minor tick spacing and shouldevenly divide the major spacing range.

SEE ALSOgmsGraphTrace( ), gmsPlotData( )

The chapter entitled in the SL-GMS Reference


GraphAxis object

SL-GML COMMANDSname graphaxis axisline-obj majortick-obj minortick-obj ticklabel-obj

name valuelimits min-real max-real

name coordlimits xmin-real ymin-real xmax-real ymax-real

name majorspacing spacing-real

name minorspacing spacing-real


GraphTrace object

GraphTrace object

SUMMARY

create a GraphTrace object, set or query its attributes

NAME

gmsGraphTrace( ), gmsXValueLimits( ), gmsYValueLimits( ), gmsQMaxTraceLength( )

SYNTAX

idgmsGraphTrace (name, maxpoints, traceline,tracemarker)

char *name;int maxpoints;id traceline;id tracemarker;

intgmsXValueLimits (obj, xmin, xmax)

id obj;double xmin;double xmax;

intgmsYValueLimits (obj, ymin, ymax)

id obj;double ymin;double ymax;

intgmsQMaxTraceLength (obj)

id obj;

DESCRIPTIONThese functions create and set the attributes of GraphTrace objects. AGraphTrace requires that two objects be used as templates and some


GraphTrace object

attributes to be set before any plots are plotted. A GraphTrace objectuses the traceline and the tracemarker as the template objects. Ifeither of these templates is nil, the GraphTrace is composed of theremaining object’s attributes. These template objects are not"consumed," only its attributes are copied and used. The templateobjects’ Point Lists are also not used.

The maxpoints argument sets the maximum number of Points that canbe plotted within the GraphTrace. If additional Points are plotted, theoldest Points are discarded.

The gmsCoordLimits( ) function is used to establish the area withinwhich Points are plotted. This function requires a Point List with thelower left and upper right corner Points of a Rectangle in WorldCoordinates.

The gmsXValueLimits( ) and gmsYValueLimits( ) functions determinethe minimum and maximum values for Points to be plotted with aGraphTrace. The range between the minimum and maximum values isscaled so that it corresponds to the region defined by the call togmsCoordLimits( ).

The gmsQMaxTraceLength( ) function returns the number of Pointsthat may be plotted using the given GraphTrace object.

SEE ALSOgmsGraphAxis( ), gmsCoordLimits( ), gmsPlotData( )

The chapters entitled The Graphical Modeling Language and in theSL-GMS Reference


GraphTrace object

SL-GML COMMANDSname graphtrace maxtracelength-int traceline-obj tracemarker-obj

name xvaluelimits xmin-real xmax-real

name yvaluelimits ymin-real ymax-real

name coordlimits xmin-real ymin-real xmax-real ymax-real

name tracelength numpoints-int

name plotdata xvalue-real yvalue-real

name plotreset

name plotclear


Grid object

Grid object

SUMMARY

create and modify a Grid object

NAME

gmsGrid( ), gmsGridSize( ), gmsLGridSize( ), gmsGridSizeX( ), gmsGridSizeY( ), gmsLGridSizeX( ), gmsLGridSizeY( ), gmsMGridSize( ), gmsMGridSizeX( ), gmsMGridSizeY( ), gmsQGridSizeX( ), gmsQGridSizeY( )

SYNTAX

idgmsGrid (name, sizex, sizey, color, edgestyle, markstyle)

char *name;double sizex;double sizey;int color;int edgestyle;int markstyle;

intgmsGridSize (obj, sizex, sizey)

id obj; /* Grid object */double sizex; /* x spacing */double sizey; /* y spacing */

intgmsLGridSize (objlist, sizex, sizey)

idLinkRef objlist;double sizex;double sizey;

intgmsGridSizeX (obj, sizex)

id obj;double sizex;


Grid object

intgmsGridSizeY (obj, sizey)

id obj;double sizey;

intgmsLGridSizeX (objlist, sizex)

idLinkRef objlist;double sizex;

intgmsLGridSizeY (objlist, sizey)

idLinkRef objlist;double sizey;

intgmsMGridSize (sizex, sizey)

double sizex;double sizey;

intgmsMGridSizeX (sizex)

double sizex;

intgmsMGridSizeY (sizey)

double sizey;

doublegmsQGridSizeX (obj)

id obj;

doublegmsQGridSizeY (obj)

id obj;


Grid object

DESCRIPTIONThe gmsGrid( ) function is used to create a Grid object. The sizexand sizey arguments define the spacing between consecutive elements(Lines or Markers) of the Grid in the x and y dimensions, respectively.

Grid elements are Lines by default. The edgestyle argumentdetermines the style of the Grid’s Lines. If edgestyle equals 0, theGrid is drawn with Markers rather than Lines.

The name argument is optional and is the name assigned to the objectwhen it is added to the current Model.

The gmsGridSize( ) function modifies the spacing of a Grid’s elementsin the x and y dimensions.

The gmsLGridSize( ) function modifies, for a List of Grid objects, thespacing of their elements in the x and y dimensions.

The gmsGridSizeX( ) function sets the x spacing for a Grid object.

The gmsGridSizeY( ) function sets the y spacing for a Grid object.

The gmsLGridSizeX( ) function changes the x Grid spacing for allobjects on the List.

The gmsLGridSizeY( ) function changes the y Grid spacing for allobjects on the List.

The gmsMGridSize( ) function sets the modal spacing of Grid elementsin the x and y dimensions, which applies to all objects subsequentlycreated.

The gmsMGridSizeX( ) function sets the modal x spacing for Grids.

The gmsMGridSizeY( ) function sets the modal y spacing for Grids.

The gmsQGridSizeX( ) function queries a Grid object’sx spacing.

The gmsQGridSizeY( ) function queries a Grid object’sy spacing.


Grid object

DIAGNOSTICSGrids in Graphs are created using GraphAxes, not Grid objects.

SL-GML COMMAND[name:] grid xspace yspace color edgestyle markerstyle


Group object

Group object

SUMMARY

create or destroy a Group object or a List of Group objects

NAME

gmsGroup( ), gmsEndGroup( ), gmsDeGroup( ), gmsLDeGroup( ), gmsOpenGroup( ), gmsLOpenGroup( ), gmsCloseGroup( ), gmsLCloseGroup( ), gmsFillGroup( ), gmsFillGroupFlags( ), gmsLFillGroupFlags( ), gmsUnFillGroup( ), gmsLUnFillGroup( )

SYNTAX

idgmsGroup (name, partlist)

char *name;idLinkRef partlist;

intgmsEndGroup( )

idLinkRefgmsDeGroup (group, displayflag)

id group;int displayflag;

idLinkRefgmsLDeGroup (grouplist, displayflag)

idLinkRef grouplist;int displayflag;

intgmsOpenGroup (group)

id group;

intgmsLOpenGroup (objlist)

idLinkRef objlist;


Group object

intgmsCloseGroup (group)

id group;

intgmsLCloseGroup (objlist)

idLinkRef objlist;

idgmsFillGroup (name, partlist, filledFlag, boundFlag)

char *name;idLinkRef partlist;int filledFlag;int boundFlag;

intgmsFillGroupFlags (group, filledFlag, boundFlag)

id group;int filledFlag;int boundFlag;

intgmsLFillGroupFlags (objlist, filledFlag, boundFlag)

idLinkRef objlist;int filledFlag;int boundFlag;

intgmsUnFillGroup (group)

id group;

intgmsLUnFillGroup (objlist)

idLinkRef objlist;


Group object

DESCRIPTIONThe gmsGroup( ) function is used to create a Group object given a Listof individual parts. The parts may be any Graphical Primitive (Lines,Circles, Text, Groups, and so on).


If the partlist argument is nil, a Group is made current with no parts,otherwise the Group is made current with the part List given. Making aGroup current means that subsequent parts are added to the Groupuntil the gmsEndGroup( ) function terminates creation. At this pointthe Group is added to the current Model and the name assigned.1

The gmsDeGroup( ) function may be used to destroy a Group whileleaving its parts intact. The remaining parts are inserted into theowning Model’s part List at the same location as that of the destroyedGroup in the List of all parts. The part List is returned from thisfunction. displayflag causes SL-GMS to mark the parts for update ifset to 1, and otherwise does not mark parts.

The gmsLDeGroup( ) function destroys all Groups in a List of Groups,adds their parts to the current Model, and returns a List of all the parts.displayflag causes SL-GMS to mark the parts for update if set to 1,and otherwise does not mark parts.

The gmsOpenGroup( ) function opens the given FillGroup.

The gmsLOpenGroup( ) function opens the given List of FillGroups.

The gmsCloseGroup( ) function closes a Group or FillGroup.

The gmsLCloseGroup( ) function closes each member of the givenList of Groups or FillGroups.

The gmsFillGroup( ) function creates the specified type of FillGroupobject (if possible), putting the given List of parts in it. An optionalname may be assigned within the current Model.

1. A Group can also be made current with the gmsCurrent( ) function.


Group object

The gmsFillGroupFlags( ) function converts the given Group orFillGroup into a FillGroup with the specified flags.

The gmsLFillGroupFlags( ) function converts the List of Groups orFillGroups into Groups with the specified flags.

The gmsUnFillGroup( ) function unfills the given FillGroup.

The gmsLUnFillGroup( ) function unfills the given List of FillGroups.

SEE ALSOgmsCurrent( )

Group Pull-Down Menu in the SL-GMS® Reference

SL-GML COMMANDS[name:] group part1 part2 ...

[name:] group

endgroup

[name:] fillgroup part1 part2 ..

fgroupflags flag1 flag2

name degroup

FillGroup Types Fill Bound Description

Simple 1 1 All parts are open Primitives or unbounded Groups; edge is one continuous boundary.

Complex 1 0 All parts are either Primitives or bounded Groups; each Primitive or bounded subnode is a boundary: a Multi-Faced object.


Group object - redrawing

Group object - redrawing

SUMMARY

redraw Group objects

NAME

gmsRepairFlag( )

SYNTAX

intgmsRepairFlag(group, flag)

id group; /* SL-GMS Group */int flag; /* repair flag = G_ON/G_OFF */

DESCRIPTIONThe gmsRepairFlag( ) function sets the repair flag for a Group. Theconstants G_ON or G_OFF may be used to set the state of the flag. Ifthe repair flag is set on a Group, and one object in the Group isredrawn, all objects in the Group are redrawn.

This flag does not eliminate the need for the batcherase flag. If erasingand redrawing an object in the Group will cause an erasure hole, thebatcherase flag must still be set to prevent this.

SEE ALSOgmsBatchErase( )

SL-GML COMMANDS[name:] repairflag int


Internationalization — localization files


SUMMARY

initialize the localization mechanism, retrieve localization strings,generate a localization file from a Model, apply a localization file to aModel,

NAME

gmsL10nInit( ), gmsL10nStr( ), gmsGenerateLocFileSO( ), gmsModApplyLocFileSO( ), gmsQSRStringSO( ), gmsSRApplyLocFileSO( ), gmsStringResource( )

SYNTAX

intgmsL10nInit (file_name, section_name)

char *file_name;char *section_name;

t_addrgmsL10nStr (key_str, default_str)

char *key_str;char *default_str;

intgmsGenerateLocFileSO (model,

file_name,output_wchar_file, prefix)id model;id file_name;int output_wchar_file;id prefix;

intgmsModApplyLocFileSO (model, file_name, section)

id model; /* optional Model */id file_name; /* localization file name */id section; /* optional section name */



intgmsQSRStringSO (string_resource, key_string, loc_string)

id string_resource;id key_string; /*identifies localized string */id loc_string; /* localized string

returned here */

intgmsSRApplyLocFileSO (string_resource, file_name,

section)id string_resource;id file_name; /* localization file name */id section; /* optional section name */

idgmsStringResource ()

DESCRIPTIONIdeally, an internationalized application can be localized for a specificlocale (or language) without duplicating or recompiling any sourcecode. These areas of a SL-GMS application typically requirelocalization:

• text strings used within the source code which are ultimately presented to users

• text presented to users by the graphical user interface

• graphical components (icons) which are locale-specific

To simplify the localization process, strings used within applicationsource code should be kept in an external text file. Only strings whichare ultimately presented to users should be in the external text file. Inthis way, the source code will not need to be modified when theapplication is localized; only the text files need to be modified. TheString Resource object provides a system-independent mechanism forretrieving and identifying localized strings in such text files. InSL-GMS, these text files are called localization files.

In a SL-GMS application, it is possible to localize the graphical userinterface by creating duplicate copies of each Model used by the



interface. Each copy is customized for a specific locale. However, thiscauses maintenance problems: if the Model is modified, all duplicatesmust also be modified.

To avoid these problems, the localized text used by a Model is stored ina localization file. The localization file can also specify which icons areto be used in a particular locale.

Applying a localization file to a Model will customize the Model for aspecific locale. There are two ways to apply a localization file to aModel:

• at run-time, using the gmsModApplyLocFileSO( ) function

• before run-time, using the -loc option of the gm1 and gm2 converters

The tool, genlocfile, generates a localization file from an existingModel.

The gmsL10nInit( ) and gmsL10nStr( ) functions are high-levelfunctions used to manage localization (L10n) within an SL-GMSapplication. The gmsL10nInit( ) function is used to initialize thelocalization mechanism. The file_name argument specifies the name ofa localization file. The section_name argument specifies the section ofthe localization file to use.

The gmsL10nStr( ) function is used to localize strings. The key_strargument specifies a key used to find an associated localized stringwithin the section of the localization file setup using gmsL10nInit( ). Ifan associated localized string cannot be found, the string provided inthe default_str argument is returned. The pointer returned bygmsL10nStr( ) points to a static buffer that contains the localizedstring. The static buffer should be treated as a read-only buffer.

Usage of gmsL10nInit( ) and gmsL10nStr( )

The gmsL10nInit( ) function is called after SL-GMS is initialized usinggmsMainInit( ), or gmsInitialize( ).

#ifdef WINNT_JAPANESE#define SECTION_NAME "Espanol"#else#define SECTION_NAME "English"



#endif/* init localization (l10n) mapping */

gmsL10nInit("myL10n.txt", SECTION_NAME);

Where the "myL10n.txt" file contains:

SECTION English

STRING_RESOURCE greeting "Hello"

SECTION Espanol

STRING_RESOURCE greeting "Hola"

In application code, strings are localized using gmsL10nStr( ). Beforelocalization an application may contain code similar to:

printf(“Hello”);

To use localization, the code is changed to:

printf(gmsL10nStr(“greeting“, ”Hello”));

The gmsGenerateLocFileSO( ) function generates a localization filefrom the given Model. The file_name argument, a String object,specifies the name of the localization file. The output_wchar_fileargument specifies the data type of the localization file. Ifoutput_wchar_file is equal to one, the generated localization file willcontain wide-characters (Unicode). Otherwise, a multi-byte localizationfile is generated. Wide-character localization files can be generatedonly on Windows NT.

The prefix argument, a String object, is used to identify objects in theModel which need to be internationalized. Objects whose namescontain "prefix" will generate commands in the localization file. Ifprefix is NULL, the default prefix "i_" is used.

The function returns 1 if a non-empty localization file is generatedsuccessfully and 0 otherwise.



The following program fragment generates a multi-byte localization filenamed "menu_ja.lc" from the given Model. The default prefix, "i_", isused to identify objects which need to be internationalized.

...

file_name = gmsStringC("menu_ja.lc");

is_successful = gmsGenerateLocFileSO(model,file_name, 0, NULL);

if (!is_successful) {ferror("Failed to generate localization file");exit(1);

}

...



The gmsStringResource( ) function creates and returns a new String Resource object. String Resources are used to store and retrieve localized strings. When a String Resource is first created, it contains no localized strings. Localized strings can be stored in a String Resource using gmsSRApplyLocFileSO( ).

The gmsSRApplyLocFileSO( ) function reads the localization filespecified by file_name, a String object, and applies commands in thefile to the given String Resource. Only certain commands are StringResource specific. These commands are described in detail in thetable Localization File Commands used by gmsSRApplyLocFileSO( ) onpage 199. The function returns 1 if the localization file is read andapplied successfully. The function returns 0 if any errors areencountered.

The gmsQSRStringSO( ) function retrieves a localized string from thegiven String Resource. The key_string argument, a String object,identifies the localized string. The function looks up the localized stringcorresponding to key_string and copies it to the given loc_stringargument (also a String object). The function returns 1 if the localizedstring can be found. If the localized string cannot be found, the functionreturns 0, and the contents of key_string are copied to loc_string.

The gmsModApplyLocFileSO( ) function reads the localization filespecified by file_name, a String object, and applies commands in thefile to either the given Model, or, if the Model argument is NULL, to allTop Models and External SubModels in SL-GMS. Only certaincommands apply specifically to Models. These commands aredescribed in detail in the table Localization File Commands used bygmsModApplyLocFileSO( ) on page 200.

If the Model argument is not NULL, the object names in the localizationfile specify objects contained in the given Model. The object names donot need to contain the name of the Model as a prefix. For example, ifa Text object named "yes_button" is in a Group named "group1," andthe Group is in a Model named "model1," the Text object can bespecified by name as "group1.yes_button."

If the Model argument is NULL, the object names in the localization filespecify objects contained in any Top Model or External SubModel. Inthis case, each object name in the localization file must contain, as aprefix, the name of the Top Model or External SubModel which contains



the corresponding object. For example, if a Text object named"yes_button" is in a Group named "group1," and the Group is in a Modelnamed "model1," the Text object can be specified by name as"model1.group1.yes_button."

The function returns 1 if the localization file is successfully read. Thefunction returns 0 if any errors are encountered.

Both the gmsSRApplyLocFileSO( ) and gmsModApplyLocFileSO( )functions adhere to this rule: if more than one localization file is appliedto an object, the commands in the last localization file applied willoverride any conflicting commands in previously applied localizationfiles. For example, if an application applies to a Model a localizationfile containing English strings, then applies to the same Model alocalization file containing Japanese strings, the Japanese strings willreplace the English strings in those cases where object names are thesame in both files.

When using either gmsSRApplyLocFileSO( ) orgmsModApplyLocFileSO( ), the section_name argument, a Stringobject, serves to limit which lines are read from a localization file. If thesection_name argument is not NULL, only commands contained in thesection identified by section_name will be executed. Sections aredefined in a localization file using the SECTION command (see thetables Localization File Commands used by gmsSRApplyLocFileSO( ) onpage 199, and Localization File Commands used bygmsModApplyLocFileSO( ) on page 200).

Commands which are specific to Model objects are ignored whenapplying a localization file withgmsSRApplyLocFileSO( ). Commands which are specific to StringResource objects are ignored when applying a localization file withgmsModApplyLocFileSO( ).



For both gmsSRApplyLocFileSO( ) and gmsModApplyLocFileSO( ), the localization file format is as follows:

• Leading spaces in lines are ignored.

• Blank lines are ignored.

• Comment lines begin with two forward slashes ("//") and are ignored. Trailing comments are not allowed.

• A command line consists of a command keyword followed by one or more arguments.

• All arguments required by a command line must be present.

• All arguments are separated by space or tab characters.

• The format for the localized_string argument is the same format used by ANSI C compilers for string constants, with the following exception:

• The L prefix (L"...") cannot be used in the localized_string. In ANSI C, the L prefix is used to specify an extended character set. In localization files, a localized_string which uses an extended character set is represented directly in that character set.

The localized_string argument consists of a sequence of characterssurrounded by double quotes ("..."). The argument can contain spacesor tabs within the double quotes. The argument cannot contain newlineor double-quote characters; to represent them, escape sequences areavailable.



The following escape sequences can be used:

The escape \ooo consists of a backslash followed by 1, 2, or 3 octaldigits, which specify the value of the character. The escape \xhhconsists of a backslash, followed by x, followed by hexadecimal digits,which specify the value of the character.

Wide-Character and Multi-Byte Localization FilesOn Windows NT platforms, both wide-character and multi-bytelocalization files are supported by SL-GMS. SL-GMS automaticallydistinguishes between wide-character and multi-byte localization fileson these platforms.

Name Literal Escape Sequence

new line NL \n

horizontal tab HT \t

vertical tab VT \v

backspace BS \b

carriage return CR \r

form feed FF \f

audible alert BEL \a

backslash \ \\

question mark ? \?

single quote ’ \’

double quote " \"

octal number ooo \ooo

hex number hh \xhh



On all other platforms, only multi-byte localization files are supported.

Localization File Commands used bygmsSRApplyLocFileSO( )

Syntax Purpose Description

SECTION section_name

Delimit a section within a localization file.

Begin a section definition. The section is identified by section_name. Subsequent commands will be contained in that section until a new SECTION command or the end of the file is reached.

STRING_RESOURCEkey_string localized_string

Associate a localized string with a key string in a String Resource object.

Store the key_string and the localized_string in the String Resource specified by the string_resource parameter to gmsSRApplyLocFileSO( ). If the String Resource already contains a key string identical to key_string, the localized string associated with the key string is replaced by localized_string.



Localization File Commands used bygmsModApplyLocFileSO( )


SECTION section_name

Delimit a section within a localization file.

Begin a section definition. The section is identified by section_name. Subsequent commands will be contained in that section until a new SECTION command or the end of the file is reached.

PRIM object_name localized_string

Replace the string contained in a Text or Text Rectangle object with a localized string.

Look up the Prim object specified by object_name and replace the string contained in the object with localized_string. The object specified by object_name must be Text or Text Rectangle. This command is equivalent to a call to gmsFindByName( ) to find the object specified by object_name, followed by a call to gmsTRepl( ) to replace the string in the specified object.



RENAMED_VAR object_name variable_name localized_string

Model Instances often contain Renamed Variables which rename variables to string constants. If the string constants must be localized, the RENAMED_VAR command can be used to replace a string constant referenced by a Renamed Variable with a localized string constant.

Look up the Model Instance specified by object_name. Replace the string constant referenced by the Renamed Variable with a string constant containing localized_string. This command is equivalent to a call to gmsFindByName( ) to find the Model Instance specified by object_name, followed by a call to gmsRenVarStrConstReplSO( ) to replace the string constant associated with the variable specified by variable_name.

MODEL_INSTANCEobject_name submodel_name

Different locales may use different symbols to represent the same concept. If a locale-dependent symbol is encapsulated in a SubModel, it is possible to have the same Model Instance reference a different SubModel in each locale. The MODEL_INSTANCE command modifies the SubModel reference of a Model Instance.

Look up the Model Instance specified by object_name. Modify the SubModel reference of the Model Instance. The Model Instance will now reference the SubModel specified by submodel_name. The object specified by object_name must be a Model Instance. This command is equivalent to a call to gmsFindByName( ) to find the Model Instance specified by object_name, followed by a call to gmsSubModelName( ) to modify the SubModel reference of the Model Instance.

Localization File Commands used bygmsModApplyLocFileSO( )

(continued)




Usage of gmsSRApplyLocFileSO( )To retrieve localized strings needed by the application source code, theapplication first creates an empty String Resource object:

id string_resource;

string_resource = gmsStringResource();

Then a localization file is applied to string_resource, which loadslocalized strings into string_resource. In this example, the commandsin the "English" section of the localization file named "locdemo.lc" areapplied to string_resource:

id file_name;

id section_name;

file_name = gmsStringC("locdemo.lc");

section_name = gmsStringC("English");

gmsSRApplyLocFileSO(string_resource, file_name,section_name);

gmsObjFree(file_name);

gmsObjFree(section_name);

The contents of the "locdemo.lc" file:

SECTION English

STRING_RESOURCE locdemo.greeting "Hello"

SECTION Espanol

STRING_RESOURCE locdemo.greeting "Hola"



At some point in the application, the localized string identified by "locdemo.greeting" is retrieved using gmsQSRStringSO( ) and used to set the text in a Text object:

id key_string;

id loc_string;

id text_object;

key_string = gmsStringC("locdemo.greeting");

loc_string = gmsStringEmpty();

gmsQSRStringSO(string_resource, key_string,loc_string);

text_object = gmsFindByName("top_model.greeting");

gmsTStringSO(text_object, loc_string);

gmsObjFree(key_string);

gmsObjFree(loc_string);

Usage of gmsModApplyLocFileSO( )The gmsModApplyLocFileSO( ) function localizes a Model at run-timeby applying a localization file to the Model. SincegmsModApplyLocFileSO( ) consumes time while localizing a Model,the function should not be used by applications which need to improveinitialization performance. For such applications, the -loc option of thegm1 script should be used instead to localize Models before run-time.

It is best to call gmsModApplyLocFileSO( ) on a Model beforegmsDynInit( ) has been called on that Model. If gmsDynInit( ) hasalready been called, and the localization file contains"RENAMED_VAR" or "MODEL_INSTANCE" commands,gmsUnlinkVarDefs( ) must be called beforegmsModApplyLocFileSO( ) to prevent corruption of internal pointers.

In this example, the application will display a Model called"topmodel1." The Model contains one part, a Text object named"greeting."

The application first loads the Model:



id topmodel1;

topmodel1 = gmsMGet("topmodel1", "topmodel1");

Often such Models are loaded implicitly through State activation.

Then a localization file is applied to topmodel1. In this example, thecommands in the "English" section of the localization file named"topmodel1.lc" are applied to topmodel1:

id file_name;

id section_name;

file_name = gmsStringC("topmodel1.lc");

section_name = gmsStringC("English");

gmsModApplyLocFileSO(topmodel1, file_name,section_name);

gmsObjFree(file_name);

gmsObjFree(section_name);

The contents of the "topmodel1.lc" file:

SECTION English

PRIM topmodel1.greeting "Hello"

SECTION Espanol

PRIM topmodel1.greeting "Hola"

After gmsModApplyLocFileSO( ) has been called, the Text objectnamed "greeting" will contain the text "Hello."



Localization File ExamplesTypically, an application will use at least two separate localizationfiles. One file will contain localized strings used by the sourcecode. This file is always applied to a String Resource object. Otherlocalization files will contain commands applied to Models used by theapplication.

This is an example of a localization file containing commands applied toa String Resource object:

// Begin section called "English"

SECTION English

// Associate the localized string "Hello world"// with the key string "greeting" in a String// Resource object.

STRING_RESOURCE greeting "Hello world"

// Begin section called "Francais"

SECTION Francais

// Associate the localized string "Bonjour le// Monde" with the key string "greeting" in a// String Resource object.

STRING_RESOURCE greeting "Bonjour le Monde"



This is an example of a localization file containing commands applied to a Model:

// Begin section called "English"

SECTION English

// Replace the string in a Text object with the// localized string "Yes." The Text object is// named "yes_button." It is in a Group named// "group1," in a Model named "model1."

PRIM model1.group1.yes_button "Yes"

// In the Model Instance named "colors," replace// the string constant referenced by the Renamed// Variable "color1" with the localized string// "Red." RENAMED_VAR model1.colors color1 "Red"

// Modify the SubModel reference of the Model// Instance named "date_inst." It will now// reference the SubModel "date_en."// MODEL_INSTANCE model1.date_inst date_en

// Begin section called "Francais"

SECTION Francais

// Replace the string in a Text object with the// localized string "Oui." The Text object is// named "yes_button." It is in a Group named// "group1," in a Model named "model1."

PRIM model1.group1.yes_button "Oui"

// In the Model Instance named "colors," replace// the string constant referenced by the Renamed// Variable "color1" with the localized string// "Rouge."

RENAMED_VAR model1.colors color1 "Rouge"

// Modify the SubModel reference of the Model// Instance named "date_inst." It will now// reference the SubModel "date_fr."// MODEL_INSTANCE model1.date_inst date_fr



SEE ALSOgmsStringC( ), gmsTStringSO( ), gmsObjFree( )


Internationalization — String object


SUMMARY

create and get a String object, copy a wide-character string or acharacter string into a String object

NAME

gmsQStringC( ), gmsQStringWC( ), gmsStringC( ), gmsStringEmpty( ), gmsStringSetC( ), gmsStringSetWC( ), gmsStringWC( )

SYNTAX

intgmsQStringC (string_obj, buffer, buffer_size,

needed_size)id string_obj;char *buffer;int buffer_size;int *needed_size;

intgmsQStringWC (string_obj, buffer, buffer_size,

needed_size)id string_obj;wchar_t *buffer;int buffer_size;int *needed_size;

idgmsStringC (string)

char *string;

idgmsStringEmpty ()



intgmsStringSetC (string_obj, string)

id string_obj;char *string;

intgmsStringSetWC (string_obj, string)

id string_obj;wchar_t *string;

idgmsStringWC (string)

wchar_t *string;

DESCRIPTIONThe String object is designed to support internationalizedapplications. To avoid string data type dependencies in an application,these dependencies must be encapsulated in an abstraction which cancontain either character strings or wide-character strings. Such anabstraction is provided in the form of the String object.

All operations on a String object work correctly regardless of the actualdata type of the string contained in the object. For example, a Stringobject created with a character string can be queried using awide-character buffer, and vice versa. A String object first used to storea character string can later be reused to store a wide-characterstring. An application does not have to keep track of the data typeassociated with a String object.

String objects also simplify string memory management. A Stringobject automatically reallocates its internal string buffer whennecessary. Any size string can be stored in a String object.

The gmsStringWC( ) and gmsStringC( ) functions create a Stringobject given a wide-character string or a character string,respectively. The gmsStringSetWC( ) and gmsStringSetC( )functions copy a wide-character string or a character string into a Stringobject.

The gmsQStringWC( ) and gmsQStringC( ) functions query thecontents of a String object using a wide-character or character buffer.



The gmsStringWC( ) function creates and returns a new Stringobject. A copy of the given wide-character string is stored in the Stringobject. If the given string is NULL, the String object created containsan empty string (""). The function returns NULL if a memory allocationfailure occurs.

A String object can be freed using gmsObjFree( ).

The gmsStringSetWC( ) function stores a copy of the givenwide-character string in the given String object. The character string orwide-character string previously contained in the String object isdestroyed. If the given wide-character string is NULL, the String objectwill contain an empty string ("") after the call togmsStringSetWC( ). The function returns 1 if it succeeds and 0 if itfails.

The gmsQStringWC( ) function copies the string contained in the givenString object to the given wide-character buffer. The buffer_sizeargument specifies the maximum number of wide-characters which canbe copied to the given buffer, including the terminatingwide-character. If the needed_size argument is not equal to NULL,gmsQStringWC( ) stores in the memory location referenced byneeded_size an integer specifying the buffer size required to copy theentire string in the String object to the buffer.

The string copied to buffer is always terminated by the nullwide-character (L'\0'), even when the function returns G_OVERFLOW.

If buffer is NULL, the function will still return in needed_size the buffersize required to copy the entire string in the String object. This is thenumber of wide-characters needed, including the terminatingwide-character. This enables an application to determine the exactbuffer size needed before allocating the buffer.

The gmsQStringWC( ) function can be called on a String object whichcontains a character string. The character string is converted towide-character as it is copied to the given buffer.



The gmsQStringWC( ) function returns one of the values indicated in the following table:

If gmsQStringWC( ) returns G_OVERFLOW, the number returned byneeded_size can be used to allocate a larger buffer. After allocating alarger buffer, if buffer_size is greater than or equal to the number inneeded_size, a second call to gmsQStringWC( ) will not returnG_OVERFLOW.

The gmsStringC( ) function creates and returns a new String object. Acopy of the given character string is stored in the String object. If thegiven string is NULL, the String object created contains an empty string(""). The function returns NULL if a memory allocation failure occurs.

The gmsStringSetC( ) function stores a copy of the given characterstring in the given String object. The character string or wide-characterstring previously contained in the String object is destroyed. If thegiven character string is NULL, the String object will contain an emptystring ("") after the call to gmsStringSetC( ). The function returns 1 if itsucceeds and 0 if it fails.

The gmsQStringC( ) function copies the string contained in the givenString object to the given character buffer. The buffer_size argumentspecifies the maximum number of bytes which can be copied to thegiven buffer, including the termination character. If the needed_sizeargument is not equal to NULL, gmsQStringC( ) stores in the memorylocation referenced by needed_size an integer specifying the buffersize required to copy the entire string in the String object to the buffer.

Value Meaning


G_OVERFLOW The given buffer was NULL or not large enough to copy the entire contents of the string contained in the String object. If buffer was not NULL, buffer_size wide-characters were copied.

G_INVALID_INPUT One of the parameters to the function was invalid.




If buffer is NULL, the function will still return in needed_size the buffersize required to copy the entire string in the String object. This is thenumber of characters needed, including the termination character. Thisenables an application to determine the exact buffer size needed beforeallocating the buffer.

The gmsQStringC( ) function can be called on a String object whichcontains a wide-character string. The wide-character string isconverted to a multi-byte string as it is copied to the given buffer. Thisconversion is locale-dependent and may fail.

The gmsQStringC( ) function returns one of the values indicated in thefollowing table:

If gmsQStringC( ) returns G_OVERFLOW, the number returned byneeded_size can be used to allocate a larger buffer. After allocating alarger buffer, if buffer_size is greater than or equal to the number inneeded_size, a second call to gmsQStringC( ) will not returnG_OVERFLOW. However, the function may returnG_CONVERSION_FAILURE.

Value Meaning


G_OVERFLOW The given buffer was NULL or not large enough to copy the entire contents of the string contained in the String object. If buffer was not NULL, buffer_size characters were copied.


G_CONVERSION_FAILURE One or more of the wide-characters contained in the String object could not be converted to multi-byte form.



The gmsStringEmpty( ) function creates and returns a new Stringobject. The String object contains an empty string. An empty Stringobject is typically used as a parameter to functions which modify agiven String object as part of a query operation, such asgmsQTStringSO( ), described in Text — object on page 401.

SEE ALSOgmsQTStringSO( ), gmsRenVarStrConstReplSO( ), gmsTStringSO( )


Line object

Line object

SUMMARY

create a Polyline object

NAME

gmsLine( )

SYNTAX

idgmsLine (name, pointlist)


DESCRIPTIONThe gmsLine( ) function is used to create a Polyline object, given twoor more Points contained in a Point List. Point Lists are created withthe refNew( ) function. The current edge attributes are applied to theobject when it is created.


The maximum number of Points in a single Polyline object is 10,240.

SEE ALSOrefNew( )

SL-GML COMMANDS[name:] line x y x y ...


LinkRef object

LinkRef object

SUMMARY

manipulate and query Linked Reference objects

NAME

refAdd( ), refAppend( ), refAt( ), refAtInsert( ), refAtPut( ), refCloAll( ), refCount( ), refDoAll( ), refDo1All( ), refDo2All( ), refDo3All( ), refDo4All( ), refDupAll( ), refFilter( ), refFind( ), refFndName( ), refFreAll( ), refFree( ), refIndex( ), refKilAll( ), refLast( ), refNew( ), refNewN( ), refNewRef( ), refRemove( ), refReplace( ), refQReference( ), refQSuccessor( )

SYNTAX

intrefAdd (list, obj)

idLinkRef list;id obj;

idLinkRefrefAppend (list, linkref)

idLinkRef list;idLinkRef linkref;

idrefAt (list, index)

idLinkRef list;int index;

idLinkRefrefAtInsert (list, index, obj)

idLinkRef list;int index;id obj;


LinkRef object

idrefAtPut (list, index, obj)

idLinkRef list;int index;id obj;

idLinkRefrefCloAll (list)

idLinkRef list;

intrefCount (list)

idLinkRef list;

intrefDoAll (list, func)

idLinkRef list;int (*func)( );

intrefDo1All (list, func, arg1)

idLinkRef list;int (*func)( );long arg1;

intrefDo2All (list, func, arg1, arg2)

idLinkRef list;int (*func)( );long arg1;long arg2;

intrefDo3All (list, func, arg1, arg2, arg3)

idLinkRef list;int (*func)( );long arg1;long arg2;long arg3;


LinkRef object

intrefDo4All (list, func, arg1, arg2, arg3, arg4)

idLinkRef list;int (*func)( );long arg1;long arg2;long arg3;long arg4;

idLinkRefrefDupAll (list)

idLinkRef list;

intrefFilter (list, obj)


idrefFind (list, obj)


idrefFndName (list, name)

idLinkRef list;char *name;

idLinkRefrefFreAll (list)

idLinkRef list;

intrefFree (list)

idLinkRef list;

intrefIndex (list, obj)



LinkRef object

idLinkRefrefKilAll (list)

idLinkRef list;

idrefLast (list)

idLinkRef list;

idLinkRefrefNew( )

idLinkRefrefNewN (n, obj1, obj2, ...)

int n;id obj1, obj2 ...;

idLinkRefrefNewRef (obj)

id obj;

idLinkRefrefRemove (list, obj)


idLinkRefrefReplace (list, obj1, obj2)

idLinkRef list;id obj1;id obj2;

idrefQReference(self)

idLinkRef self; /* a LinkRef object */

idLinkRefrefQSuccessor(self)

idLinkRef self; /* a LinkRef object */


LinkRef object

DESCRIPTIONLinkRef (Linked Reference or List) objects are used to create lists ofother objects. Each LinkRef object contains a pointer to its class(LinkRef), a pointer to the next LinkRef, the successor, and a pointer toan object, the reference.

LinkRef objects

The refQReference( ) and refQSuccessor( ) functions are used toquery attributes of LinkRef objects. The use of field dereferencing (“ ->” syntax in C) on LinkRef objects is discouraged.

The refQReference( ) function returns the pointer contained in thereference (or object) field of a LinkRef object. The refQSuccessor( )function returns the pointer contained in the successor field of aLinkRef object. The pointer contained in the successor field of aLinkRef object is a pointer to the next LinkRef in a linked list of LinkRefobjects.

LinkRef

successor

reference

an Object

LinkRef

successor

reference

an Object

LinkRef

successor

reference

an Object


LinkRef object

The following sample of C code illustrates how the new functions can be used to efficiently process all objects contained in a Linked list of LinkRef objects.

voidprocess_list(list)

idLinkRef list; /* head of list passed in */{

id object;

while (list) {object = refQReference(list);

/* perform some operation on the object */

process_object(object);list = refQSuccessor(list);

}}

The section SL-GMS data types on page -2 provides a listing of theLinkRef object.

SL-GMS handles the details of list manipulation and allocationinternally. Lists of objects are required as arguments to manyfunctions. Commonly, a function requires a List of Points or objects asan argument.

Lists may be created using a sequence of refNewRef( ) and refAdd( )functions, or by using refNewN( ) to build a List with one function. TherefFilter( ) function, unlike refAdd( ), adds an object to a List only if theobject is not already in it.

The refAtInsert( ) function inserts an object inside a List at thespecified index and returns a pointer to the first link in the List. TherefAtPut( ) function replaces an link in a List with the given object andreturns the replaced object. The refAppend( ) function appends itssecond argument to its first and returns the (altered) first List.


LinkRef object

The first occurrence of a particular object in the List is removed using the refRemove( ) function. This function returns a pointer to the updated List, which must always be used to update the List header pointer.

The refReplace( ) function finds the first occurrence of the first objectargument in the given List, replaces it with the second object, andreturns a pointer to the List.

The object at a particular index in the List may be queried usingrefAt( ); the index of the (first) occurrence of an object is returned byrefIndex( ); the existence of an object in a list is verified by refFind( )and refFndName( ); a pointer to the last object in the List is returned byrefLast( ). The number of objects in a List may be queried usingrefCount( ).

Individual LinkRefs may be freed using refFree( ); entire linked Listsmay be freed by using the refFreAll( ) function. These functions donot free the objects in the List. The refKilAll( ) function not only freesthe LinkRefs, but also the objects they reference.

A duplicate of a List may be created using refDupAll( ). This functionmakes a copy of every LinkRef in the List, but not the objects to whichthey point. The refCloAll( ) function may be used to make a copy ofthe List, including all objects in the List.

One of the advantages of Lists is that an operation defined by afunction can be performed on every member of a List. The refDo*All( )functions handle the details. The refDo*All( ) functions are providedthe number of arguments and a pointer to the Lists.

NOTE: A List should only be used to contain SL-GMS objects.

DIAGNOSTICSThe current interface for linked Lists requires that the programmeralways remember to set the List header pointer by the return value ofany function that returns the List, such as refRemove( ), and so on.


LinkRef object

EXAMPLEThe following sequence adds two objects to a List, then removes themand frees the List:

id anObject, aSecondObject;

idLinkRef list;

list = refNewRef(anObject);

refAdd(list, aSecondObject);

list = refRemove(list, anObject);

list = refRemove(list, aSecondObject);

refFreAll(list);

list = 0;


Main — SL-GMS main functions


SUMMARY

invoke a default SL-GMS startup configuration

NAME

gmsMainInit( ), gmsMainInitStr( ), gmsMain( ), gmsMainStr( ), gmsMainLoop( )

SYNTAX

intgmsMainInit (argc, argv)

int argc; /* standard main( ) arguments */char **argv;

intgmsMainInitStr (argstr)

char *argstr; /* string containing main( )arguments separated by spaces */

intgmsMain(argc, argv)

int argc; /* standard main( ) arguments */char **argv;

intgmsMainStr(argstr)

char *argstr; /* string containing main( )arguments separated by spaces */

intgmsMainLoop( )

intgmsMainInit (argc, argv, xt_init)

int *argc;char **argv;



intgmsRunMainLoop ( )

DESCRIPTIONThese functions are the primary startup functions for SL-GMS.

The gmsMainInit( ) function:

1. Processes any command line options usinggmsWsProcArgs( )

NOTE: The switches used by gmsWsProcArgs( ) (documented in theInstallation Notes) are reserved by SL-GMS and should not be used(for application-specific purpose) by programs that callgmsMainInit( ).

2. Sets the "input mode" flag to 1 using gmsInMode( )

NOTE: Setting the "input mode" flag to 1 turns off allocation of space for theSL-GMS Message Area of the graphics window. The MessageArea is used to display prompts and external echo text. The "inputmode" flag is 0 by default.

3. Creates a default Workstation/Window usinggmsWorkst( ) if no Workstation/Window has alreadybeen created

4. Sets traps for the Workstation/Window just created usinggmsSetTraps( )

5. Adds search paths for the following directories: SUB-MODS, GRAPHS, GISMOS using gmsAddLibPath( )

6. Calls gmsInitGismos( ) to initialize GISMO variables andfunctions

The gmsMainInit( ) function is essentially a convenience function; thesteps listed above can be performed by a user-initialization function, ifdesired.



If SL-SMS is being used, gmsInitStates( ) should be called aftergmsMainInit( ). As of this version, gmsMainInit( ) functionality isdeliberately separate from States functionality.

For non-C programming languages, or situations where the argc - argv mechanism is inconvenient or simply unavailable, thegmsMainInitStr(argstr) function can be used instead ofgmsMainInit( ). argstr is of type char *, where the character stringcontains space-separated arguments. Quotes attempting to combinewords into one argument are not accounted for.

The gmsMainLoop( ) function is a "do forever" loop for processingEvents. In the loop, SL-GMS waits for an Event at anyWorkstation/Window. There are two types of Events: Timer Eventsand Input Events. When an Event is received, SL-GMS wakes up and dispatches the Event to the correctEvent-handler for that type of Event. Normally, after every Event isdispatched,

gmsDynUpdate(nil)gmsUpdate(nil)

are invoked. In some cases this updating behavior may not beappropriate. Calling

gmsAutoUpdateMode(G_OFF)

allows the user to control updating explicitly. Also, the relative priorityof dispatching Events can be controlled using gmsEventPriority( ).

The gmsMain( ) function:

1. Calls gmsSetup( )

2. Calls gmsMainInit(argc, argv)

3. Calls gmsMainLoop( )

For non-C programming languages, or situations where the argc - argv mechanism is inconvenient or simply unavailable, thefunction gmsMainStr(argstr) can be used instead of gmsMain( ).argstr is of type char *, where the character string containsspace-separated arguments. Quotes attempting to combine words intoone argument are not accounted for.



EXAMPLEintmain (argc, argv)

int argc;char **argv;

{...

/* set up SL-GMS */gmsSetup( );...

/* call the SL-GMS main initializationroutine */

gmsMainInit(argc, argv);/* initialize the Screen State Manager

*/gmsInitStates( );.../* application-specific initialization code here...

*/

/* go to loop forever */gmsMainLoop( );return 1;

}



The source code for gmsMainLoop( ) is provided on the following page for users who need to customize it, for example, to add special Event processing.

#include "gms.h"#include "system.h"intgmsMainLoop( ){

int alive = 1;while (alive) {

/* a wait at any Workstation/Windowends when an Event occurs at anyWorkstation/Window */

gmsWaitEvent(0);/* dispatch the Events */

switch (gmsQEventPriority( )) {case G_TIMERS_FIRST:

if (!gmsDispatchTimerEvents( ))gmsDispatchInputEvents( );

break;case G_TIMERS_LAST:

if (!gmsDispatchInputEvents( ))gmsDispatchTimerEvents( );

break;case G_EQUAL_PRIORITY:

gmsDispatchInputEvents( );gmsDispatchTimerEvents( );break;

case G_NO_TIMERS:gmsDispatchInputEvents( );break;

default:gmsError("bad event priority flag %d",

gmsQEventPriority( ));return 0;

}



/* this update could also be performedby the user; an update afterdispatching Events may not beappropriate */

if (gmsQAutoUpdateMode( )) {gmsDefu( );gmsDynUpdate(nil);gmsUpdate(nil);

}}

}

SEE ALSOEvents — Xt and X applications on page 140 for making use of anexternal main loop


Marker — custom

Marker — custom

SUMMARY

install a user-defined function for drawing custom markers

NAME

gmsUserMarkerFctn( )

SYNTAXintgmsUserMarkerFctn (fptr)

int (*fptr)();

DISCRIPTIONThe gmsUserMarkerFctn( ) function installs a user-defined markerdrawing function. The fptr argument specifies the address of themarker drawing function. Once it is installed, SL-GMS calls the custommarker drawing function for marker styles greater than five. The custommarker function must expect the following arguments by platform:

For 32-bit Windows:

intdrawMyMarkers (workst, dc, style, x, y, color)

id workst; /* SL-GMS Workstation */HDC dc; /* Windows Drawing resource */int style; /* Marker style number */int x; /* x location in device coords */int y; /* y location in device coords */int color; /* Marker color */


Marker — custom

For Unix/X Windows:

intdrawMyMarkers (workst, curD, eGC, style, x, y, color)

id workst; /* SL-GMS Workstation */Drawable curD; /* Current drawing resource */GC eGC; /* Graphic context for edges */int style; /* Marker style number */int x; /* x location in device coords */int y; /* y location in device coords */int color; /* Marker color */

EXAMPLES

32-bit Windows example:#include <Windows.h>#include "gms.h"

intdrawMarker(id workst, HDC dc, int style, int x, int y,

int color){

int msize = 10; /* arbitrary marker pixel width*/

MoveToEx(dc, (INT) x, (INT) y, (LPPOINT)NULL);

switch (style) {case 6:

if (!AngleArc(dc, x, y, msize, 0.0,360.0))

return 0;break;

default:if (!Ellipse(dc, x-msize, y-msize,x+msize, y+msize))

return 0;break;


Marker — custom

}}

intmain (argc, argv)


{....

gmsUserMarkerFctn(drawMarker);

...}

Unix/X Windows Example:#include <Xlib.h>#include "gms.h"

intdrawMarker(id workst, Drawable curDrawable, GC

xEdgeGC,int style, int x, int y, int color)

{int msize = 3; /* arbitrary marker pixel width */Display* dpy = gmsQDisplayId(workst);

switch (style) {case 6:default:

XDrawArc(dpy, curDrawable, xEdgeGC,x-msize, y-msize, msize*2,

msize*2, 0, 23040);break;

}return 1;


Marker — custom

}

intmain (argc, argv)


{....

gmsUserMarkerFctn(drawMarker);

...}


Marker — object

Marker — object

SUMMARY

create a Marker object

NAME

gmsMark( )

SYNTAX

idgmsMark (name, pointlist)


DESCRIPTIONThe gmsMark( ) function is used to create a Marker object given a setof Points contained in a Point List. The refNew( ) function is used tocreate Lists. The current Marker attributes are applied to the objectwhen it is created.


SEE ALSOrefNew( )

SL-GML COMMAND[name:] mark x y x y ...


Marker — size attribute


SUMMARY

set the Marker size attribute for objects

NAME

gmsMSize( ), gmsLMSize( ), gmsMMSize( ), gmsQMSize( )

SYNTAX

intgmsMSize (obj, size)

id obj;double size;

intgmsLMSize (objlist, size)

idLinkRef objlist;double size;

intgmsMMSize (size)

double size;

doublegmsQMSize (obj)

id obj; /* Marker object or nil pointer formodal query */



DESCRIPTIONThis is a complete set of functions for the manipulation of the Markersize attribute supported by SL-GMS. The gmsMSize( ) functionapplies to individual objects, the gmsLMSize( ) function applies to Listsof objects, and the gmsMMSize( ) function applies to the modalattributes. The gmsQMSize( ) function queries a Marker object’s size.If a nil pointer is used as an argument, the modal Marker size attributeis returned. A 0 is returned when the pointer refers to a non-Markerobject. The modal attribute is referred to as "current" and is appliedwhenever new Marker objects are created.

DIAGNOSTICSNo bounds checking is done for attributes. It is assumed that thedevice driver software, at the SL-GWS layer of SL-GMS, deals with theattributes appropriately.

Marker size is not supported by all different display packages and isignored in such cases.

SL-GML COMMAND [name] msize size


Message tracing

Message tracing

SUMMARY

turn on message tracing

NAME

gmsMtrFlag( )

SYNTAX

intgmsMtrFlag (level)

int level;

DESCRIPTIONThe gmsMtrFlag( ) function affects message tracing — a debuggingutility. Level 0 means no message tracing, level 1 means display alltop-level (object) messages, and level 2 means display all top-level andobject-internal messages.


Model — object

Model — object

SUMMARY

create or end a new Model; set the current Model; query for the Systemobject’s Model List; query for the Local or External SubModels List of aModel

NAME

gmsModelWithParts( ), gmsModel( ), gmsEndModel( ), gmsQModelList( ), gmsQLocModelList( ), gmsQExtModelList( )

SYNTAX

idgmsModelWithParts (name, partlist)

char *name;idLinkRef partlist;

idgmsModel (name)

char *name;

intgmsEndModel( )

idLinkRefgmsQModelList( )

idLinkRefgmsQLocModelList(model)

id model;

idLinkRefgmsQExtModelList(model)

id model;


Model — object

DESCRIPTIONThe gmsModelWithParts( ) function creates a Model with the givenname and the part List. The new Model is made the current Model.The objects in the part List are cloned and the part List used as theargument may be freed.

The gmsModel( ) function is used to create a Model with defaultcharacteristics and add it to SL-GMS with the name given.

This Model becomes the current Model. If there already was a Modelcurrent, the created Model is added to the List of local SubModels forthe current Model. The new Model remains current and parts areadded to the Model until the gmsEndModel( ) function is called.

The gmsEndModel( ) function terminates the current Model, popping upa level in the Model hierarchy. Any additional Graphical Primitivescreated are added to the new current Model.

The gmsQModelList( ) function returns the System object’s List ofModels. A pointer to the actual SL-GMS internal List (a LinkedReference List) is returned. Therefore, the List must not be modified inany way; it must not be freed after being used.

WARNING: If the List of top-level Models is modified by the application program (freeing Models, adding Models) after the gmsQModelList( ) function was called, the List that was returned is no longer valid — the List should be queried again after any changes are made to the SL-GMS top-level Model List.

The gmsQLocModelList( ) and gmsQExtModelList( ) functions,respectively, query the local and external SubModel Lists for a Model.

NOTE: These functions return pointers to the actual Lists; these Lists mustnot be altered by the caller of these functions.


Model — object

SEE ALSOgmsModInst( ), gmsQCurModel( ), gmsCurrent( )

SL-GML COMMANDSname: model

endmodel

name current


Model — save, get, merge


SUMMARY

save or get a Model in binary format; save or get a Model in SL-GMLformat

NAME

gmsCGMGet( ), gmsMSave( ), gmsMGet( ), gmsMXGet( ), gmsMMerge( ), gmsMGSave( ), gmsM2Get( ), gmsM2XGet( ), gmsM2Merge( ), gmsM2Save( ), gmsExtSubModMode( ), gmsQExtSubModMode( )

SYNTAX

idLinkRefgmsCGMGet (filename)

char *filename;

intgmsMSave (model, filename)

idModel model;char *filename;

idgmsMGet (modname, filename)

char *modname;char *filename;

idgmsMXGet (modname, filename)


idgmsMMerge (filename)

char *filename;



intgmsMGSave (model, filename)

idModel model;char *filename;

idgmsM2Get (modname, filename)


idgmsM2XGet (modname, filename)


idgmsM2Merge (filename)

char *filename;

intgmsM2Save (model, name)

id model;char *name;

intgmsExtSubModMode (mode)

int mode; /* 0 or 1 */

intgmsQExtSubModMode ( )

DESCRIPTIONThe gmsCGMGet( ) function reads a file that is in CGM format andconverts it to an SL-GMS Model.

The gmsMSave( ) and gmsMGet( ) functions are used to save Modelsto a file and to read back Models thus saved. If the gmsMGet( )function is given a modname argument, the Model read from the file isadded to the Graphical Modeling Hierarchy using the given name,otherwise it defaults to the file name. Files saved by gmsMSave( )



have the extension ".m1" added by SL-GMS. Similarly, when a Modelfile is read with gmsMGet( ), SL-GMS adds the ".m1" extension.

NOTE: An "m1" file cannot be created if the Model contains more than2,147,483,647 (231 - 1) objects.

When a Model is read in and there is no current Model, the Modelbecomes top-level. If a Model is current, the Model read in becomes alocal SubModel of the current Model. All Models have names withinSL-GMS. If the modname argument to gmsMGet( ) is null, thefilename (without the ".m1" extension) is used as the Model’s name.

NOTE: When using a toolkit popup or pull-down menu to load a new Model,gmsUpdate( ) should be called immediately thereafter.

The gmsMXGet( ) function extracts a Model from a file and adds it tothe External SubModels List of the current Model. The SubModelbecomes available for instancing within the current Model. TheSubModel’s name defaults to the file name without the ".m1" extensionif the modname argument is null. This function is used to preload anExternal Model before it is actually employed and also for SubModelcaching.

The gmsMMerge( ) function merges the Model read from the file withthe current Model. The current Model’s name becomes that of thenewly-merged Model.

Dynamics Initialization (gmsDynInit( )) is performed immediately ondynamic Models that are loaded using gmsMGet( ) or gmsMMerge( ).

The gmsMGSave( ) function works similarly to the gmsMSave( )function except that Models are saved as a file of SL-GML commands.The filename is given a ".g" extension, the same as command files usedin SL-GML.

The gmsM2Get( ) function first tries to read in a Model from a file with a".m2" extension, and if not found, reads in a Model from a file with a".m1" extension (thus an application may use any combination of ".m2"and ".m1" files). The function adds the Model to the current Model’sLocal SubModels List, or the System object’s Model List if no Model iscurrent, using modname (which defaults to filename).



The gmsM2XGet( ) function extracts a Model from a file and adds it tothe External SubModels List of the current Model. The SubModelbecomes available for instancing within the current Model. TheSubModel’s name defaults to the file name without the ".m2" extensionif the modname argument is null. This function is used to preload anExternal Model before it is actually employed and also for SubModelcaching.

The gmsM2Merge( ) function merges the current Model with the Modelin filename (the ".m2" extension is added). The Model must be currentin order to merge.

The gmsM2Save( ) function saves the Model specified. The Model issaved as "<name.m2>".

The gmsExtSubModMode( ) function controls the loading of externalSubModels when a Model is read from disk. When the ExternalSubModel Mode is set to 1 (the default), external SubModels areloaded when a Model is read from disk. When the mode is set to 0,external Submodels are not loaded when a Model is read from disk.Setting the External SubModel Mode to 0 is useful when the userwishes to read in a Model whose SubModels may not be necessarilybuilt. The gmsQExtSubModMode( ) function returns the currentExternal SubModel Mode.

SEE ALSOgmsDynInit( ), gmsModInst( )

SL-GML COMMANDSname save [filename]

name gsave [filename]

[name:] model get filename

[name:] model xget filename


Model — save, get from pseudo-files


SUMMARY

Install Filer interception functions

NAME

gmsFilerFctn( ), gmsQFilerDataFiler( ), gmsQFilerDataAction( ), gmsQFilerDataFilename( ), gmsQFilerDataPseudoFile( ), gmsFilerDataPseudoFile( ), gmsQFilerDataSize( ), gmsFilerDataSize( ), gmsQFilerDataType( )

SYNTAX

intgmsFilerFctn (filer, callback, callback_arg)

int filer;int (*callback)( );void *callback_arg;

intgmsQFilerDataFiler (filer_data)

id filer_data;

intgmsQFilerDataAction (filer_data)

id filer_data;

char *gmsQFilerDataFilename (filer_data)

id filer_data;

void *gmsQFilerDataPseudoFile (filer_data)

id filer_data;



intgmsFilerDataPseudoFile (filer_data, pseudo_file)

id filer_data;void *pseudo_file;

intgmsQFilerDataSize (filer_data)

id filer_data;

intgmsFilerDataSize (filer_data, size)

id filer_data;int size;

intgmsQFilerDataType (filer_data)

id filer_data;

DESCRIPTIONThe gmsFilerFctn( ) function installs a user-defined Filer interceptfunction in SL-GMS. Filer intercept functions allow the applicationprogrammer to use pseudo-files instead of real files for some streamI/O operations. A pseudo-file is a block of memory which contains datanormally contained in a file.

The gmsFilerFctn( ) function is used when Models cannot be storedand retrieved using C library I/O functions. For example, if anapplication must store Models in the form of BLOBs (Binary LargeObjects) in a database, gmsFilerFctn( ) would be used to install a Filerintercept function which accesses the database.

The Filer intercept function should be installed before any Models areloaded by SL-GMS. The gmsFilerFctn( ) function should be calledsometime after gmsSetup( ), and before the first Models are loaded.

The filer argument specifies the Filer type associated with the Filerintercept function. The following Filer type values are currently defined:

G_FILER_M1 Each time SL-GMS must find, read, or write a ".m1" file, the callback function pointer will be invoked.



G_FILER_M2 Each time SL-GMS must find, read, or write a ".m2" file, the callback function pointer will be invoked.

G_FILER_LOCFILE Each time SL-GMS must find, read, or write a localization file, the callback function pointer will be invoked.

The gmsQFilerDataType( ) function can be called within aninterception function to retrieve the data type associated with aFilerData:

The data type associated with the G_FILER_M1 and G_FILER_M2 Filertypes is G_FILER_BINARY. The data type associated with theG_FILER_LOCFILE Filer type is either G_FILER_CHAR orG_FILER_WCHAR, depending upon the localization file format(character or wide-character format). Wide-character localization filesare supported on Windows NT platforms only.

The callback function pointer should point to a function defined usingthe following template:

static intfiler_callback (callback_arg, filer_data)

void *callback_arg;id filer_data;

The callback_arg argument is a user-defined pointer previously storedusing gmsFilerFctn( ). It is optional. One possible use for this wouldbe a pointer to a user-defined structure or object which storesinformation used by the filer_callback( ) function.

The filer_data argument is a pointer to a G_FilerData object. Theobject contains the following attributes:

filer Specifies Filer type. This is a read-only attribute.

The gmsQFilerDataFiler( ) function returns the value of the filer attribute in a given G_FilerData.



action Specifies the action the callback function is to perform. These actions are described in detail below. A read-only attribute.

The gmsQFilerDataAction( ) function returns the value of the action attribute in a given G_FilerData.

filename A string containing the name of the pseudo-file requested. For example, it may contain "model1.m1". This is a read-only attribute.

The gmsQFilerDataFilename( ) function returns the filename stored in the given G_FilerData. The string should not be freed by the caller.

pseudo_file Used to return or specify the address of a pseudo-file. Can be read and written; usage of this attribute depends upon the value of the action attribute.

The gmsQFilerDataPseudoFile( ) function will return the pseudo-file pointer contained in the given G_FilerData. The gmsFilerDataPseudoFile( ) function will set the pseudo-file pointer in the given G_FilerData.

size Used to return or specify the size, in bytes, of a pseudo-file. The size attribute can be read and written; the usage of this attribute depends on the value of the action attribute.

The gmsQFilerDataSize( ) function returns the size of the pseudo-file associated with a given G_FilerData. The gmsFilerDataSize( ) function sets the size of the pseudo-file associated with a given G_FilerData.

When invoked, the callback should first retrieve the action associatedwith filer_data using gmsQFilerDataAction( ). The action attributespecifies the actions the callback function must perform. This attributecan have the following values:



G_FILER_QUERY_EXISTS:

The gmsQFilerDataFilename( ) function should be used to retrieve thefilename of the pseudo-file.

The callback function should return 1 if the pseudo-file specified by the filename exists. The callback functionshould return 0 if it does not exist.

G_FILER_QUERY_WRITABLE:


The callback function should return 1 if the pseudo-file specified by the filename is writable. The callbackfunction should return 0 if it is not writable.

G_FILER_OPEN_WRITE:

The gmsQFilerDataFilename( ) function can be used to retrieve thefilename of the pseudo-file.

The gmsQFilerDataSize( ) function should be used to obtain the size,in bytes, of the empty pseudo-file requested.

The callback function should allocate and obtain a pointer to an emptypseudo-file. The pseudo-file pointer should be installed in filer_datausing gmsFilerDataPseudoFile( ).

If successful, the callback function should return 1. If unsuccessful,the callback function should return 0.

G_FILER_CLOSE_WRITE_SUCCESS:

This action value indicates a pseudo-file has been successfully writtenand is now being closed.


The gmsQFilerDataPseudoFile( ) function should be used to retrievethe pseudo-file pointer contained in filer_data. This is a pointer to apseudo-file which was previously opened for writing.

The gmsQFilerDataSize( ) function can be used to retrieve the size, inbytes, of the pseudo-file.



The callback should perform whatever operations are necessary tosave the data in the pseudo-file and free the resources (memory andsuch) associated with the pseudo-file.


G_FILER_CLOSE_WRITE_FAILURE:

This action value indicates that an attempt to write to the pseudo-filehas failed and the data in the pseudo-file are invalid.

The callback should free the resources (memory and such) associatedwith the pseudo-file and return 1.

G_FILER_QUERY_READABLE:


The callback function should return 1 if the pseudo-file specified by the filename exists and is readable. Thecallback function should return 0 if either of these conditions is false.

G_FILER_OPEN_READ:


The callback function should obtain a pointer to the pseudo-filespecified by the filename. The pseudo-file pointer should be installed in filer_data usinggmsFilerDataPseudoFile( ). The size, in bytes, of the pseudo-filemust be recorded in filer_data using gmsFilerDataSize( ).


G_FILER_CLOSE_READ:


The gmsQFilerDataPseudoFile( ) function should be used to retrievethe pseudo-file pointer contained in filer_data. This is a pointer to apseudo-file previously opened for reading.



The callback should perform whatever operations are necessary tofree the resources (memory and such) associated with this pseudo-file.


If a callback function has been installed for the Filer typeG_FILER_M1, the callback function will be invoked several times eachtime a corresponding pseudo-file must be accessed.

The callback function will be invoked with the following series of actionvalues when a pseudo-file is written:

G_FILER_QUERY_EXISTS

G_FILER_QUERY_WRITABLE

G_FILER_OPEN_WRITE

G_FILER_CLOSE_WRITE_SUCCESS orG_FILER_CLOSE_WRITE_FAILURE

The callback function will be invoked with the following series of actionvalues when a pseudo-file is read:

G_FILER_QUERY_READABLE

G_FILER_OPEN_READ

G_FILER_CLOSE_READ

EXAMPLEIn this example, the application must save, find, and retrieve Models inthe form of a BLOB from a database. The Filer intercept function isfiler_callback( ). The callback_arg is not used in this example, so it isNULL:

int filer_callback( );

gmsFilerFctn(G_FILER_M1, filer_callback, NULL);

The filer_callback( ) function serves as a control center. It extracts theaction associated with the G_FilerData object filer_data and branchesto one of eight sub-functions, depending upon the value of action:



static intfiler_callback (callback_arg, filer_data)

void *callback_arg;id filer_data;

{

int action;/* query action to perform */

action = gmsQFilerDataAction(filer_data);

/* branch to sub-function */switch (action) {case G_FILER_QUERY_EXISTS:

return query_exists(filer_data);

case G_FILER_QUERY_WRITABLE:return query_writable(filer_data);

case G_FILER_OPEN_WRITE:return open_write(filer_data);

case G_FILER_CLOSE_WRITE_SUCCESS:return close_write(filer_data, 1);

case G_FILER_CLOSE_WRITE_FAILURE:return close_write(filer_data, 0);

case G_FILER_QUERY_READABLE:return query_readable(filer_data);

*** code continued on next page ***

case G_FILER_OPEN_READ:



return open_read(filer_data);

case G_FILER_CLOSE_READ:return close_read(filer_data);

}/* unrecognized action: return

failure */return 0;

}

The query_exists( ) function uses gmsQFilerDataFilename( ) toobtain the filename identifying the pseudo-file. The functiondetermines if a BLOB corresponding to this filename exists in thedatabase. If so, the function returns 1. If not, the function returns 0.

static intquery_exists (filer_data)

id filer_data;{

char *filename;int exists;

filename = gmsQFilerDataFilename(filer_data);

/* Code below determines if a BLOBcorresponding to filename existsin the database. If so, the existsflag is set to 1. Else the existsflag is set to 0. */

.

.

.return exists;

}

The query_writable( ) function uses gmsQFilerDataFilename( ) toobtain the filename identifying the pseudo-file. The functiondetermines if any BLOB corresponding to this filename in the database



is writable. If so, query_writable( ) returns 1. If not, query_writable( )returns 0.

static intquery_writable (filer_data)

id filer_data;{

char *filename;int writable;


/* Code below determines if any BLOBcorresponding to filename in thedatabase is writable. If so, thewritable flag is set to 1. Elsethe writable flag is set to 0. */

.

.

.return writable;

}

The open_write( ) function uses gmsQFilerDataSize( ) to determinethe size, in bytes, of the empty pseudo-file requested. The functionallocates a block of memory containing this many bytes (an emptypseudo-file). A pointer to this block is installed in filer_data usinggmsFilerDataPseudoFile( ):

static intopen_write (filer_data)

id filer_data;{

int size;void *pseudo_file;

size = gmsQFilerDataSize(filer_data);



/* allocate a block of memorycontaining size bytes */

pseudo_file = malloc(size);


if (pseudo_file == NULL)return 0;

/* install pseudo_file pointer infiler_data */

gmsFilerDataPseudoFile(filer_data, pseudo_file);return 1;

}

The close_write( ) function uses gmsQFilerDataPseudoFile( ) toretrieve the pseudo-file pointer in filer_data. This pointer is assignedto the variable pseudo_file. The data referenced by pseudo_file arecopied to a BLOB in the database. The memory referenced bypseudo_file is then freed:

static intclose_write (filer_data, write_success)

id filer_data;int write_success;

{

void *pseudo_file;

pseudo_file = gmsQFilerDataPseudoFile(filer_data);

if (write_success) {/* code here will copy the data in

pseudo_file to a BLOB in thedatabase */

.



.

.}

/* free pseudo_file */free(pseudo_file);return 1;

}

The query_readable( ) function uses gmsQFilerDataFilename( ) toobtain the filename identifying the pseudo-file. The functiondetermines if a BLOB corresponding to this filename exists in thedatabase. If so, query_readable( ) returns 1. If not, query_readable() returns 0.

static intquery_readable (filer_data)

id filer_data;{

char *filename;int readable;


/* Code below determines if the BLOBcorresponding to filename existsin the database. If so, readableflag is set to 1. Otherwise,readable flag is set to 0. */

.

.

.return readable;

}

The open_read( ) function uses gmsQFilerDataFilename( ) to obtainthe filename identifying the pseudo-file. The function looks up theBLOB corresponding to this filename in the database. A block ofmemory large enough to hold the information in the BLOB is allocatedand a pointer to this block is assigned to pseudo_file. The data in the



BLOB are copied into the memory referenced by pseudo_file. Thepseudo_file pointer is installed in filer_data usinggmsFilerDataPseudoFile( ), and the size of the pseudo-file is recordedin filer_data using gmsFilerDataSize( ).

static intopen_read (filer_data)id filer_data;

{

char *filename;int size;void *pseudo_file;


/* code below will look up BLOBcorresponding to filename */

.

.

./* code below will assign to size the

number of bytes required to storethe BLOB data */

.

.

./* allocate a block of memory

containing size bytes */pseudo_file = malloc(size);

if (pseudo_file == NULL)return 0;

/* code below will copy data in BLOBto memory referenced bypseudo_file */

.

.



./* install pseudo_file pointer in

filer_data */gmsFilerDataPseudoFile(filer_data, pseudo_file);

/* record pseudo-file size infiler_data */

gmsFilerDataSize(filer_data, size);return 1;

}

close_read( ) uses gmsQFilerDataPseudoFile( ) to retrieve thepseudo-file pointer in filer_data. The memory referenced bypseudo_file is then freed:

static intclose_read (filer_data)

id filer_data;{

void *pseudo_file;

pseudo_file = gmsQFilerDataPseudoFile(filer_data);

/* free pseudo_file */free(pseudo_file);return 1;

}


Model — user header string


SUMMARY

Set and query the user header string of a Model in memory. Query theuser header string of a Model file on disk.

The format of a user header string is similar to that of RenamedVarstrings:

label_1 :: "data_1" label_2 :: "data_2" ... label_n:: "data_n"

Only string data is allowed with each label.

NAME

gmsMUserHeaderStr( ), gmsQMUserHeaderStr( ), gmsMGetUserHeaderStr( )

SYNTAX

intgmsMUserHeaderStr (model, user_str)

id model;char *user_str;

char *gmsQMUserHeaderStr (model)

id model;

char *gmsMGetUserHeaderStr (filename)

char *filename;



DESCRIPTIONThe gmsMUserHeaderStr( ) function sets the user header string for amodel in memory. e.g.

sprintf(header, "extent :: \"10, 10, 280, 280\"format :: \"%%d A\" ");

result = gmsMUserHeaderStr(obj, header);

The format of a user header string is the same as Renamed Varsstrings except only string data is allowed with each label. ThegmsMUserHeaderStr( ) function automatically prefixes the label foreach item in the supplied string with "user_". When editing the userheader string in a ".g" file directly, the "user_" prefix must be includedas part of the label name for user defined items. Items defined bySL-GMS will not have this prefix.

The gmsQMUserHeaderStr( ) function returns a user header stringfrom the Model specified in memory. The "user_" prefix thatgmsMUserHeaderStr( ) adds to item labels is removed bygmsQMUserHeaderStr( ). The string returned by this function must befreed by using g_strfree( ) when the program is finished with the string.

The gmsMGetUserHeaderStr( ) function reads the user header stringfrom a Model file without loading the Model in memory and returns auser header string. Use g_strfree( ) to free the string when done. The"user_" label prefix for each label is removed by this function also.

EXAMPLEAn example Model using the modelheader command would be asfollows:

mtran0vis 1detect 1test: model

. modelheader \user_format :: "%d A" \user_label :: "\t Amps " \user_highlimit :: " 200 " \user_highdanger :: "19\b" \



user_extent :: "20 20 100 100 " \user_lowlimit :: "0" \user_m :: "b1"

fcolor 4fstyle 1finter 1fdir 0fpercent 100ecolor 7estyle 1ewidth 1_circ: cir2 10 10 20 10

endm

SL-GML COMMANDS[name:] modelheader string


Model Instance (ModInst) object


SUMMARY

create a Model Instance object, set SubModel Replicate Mode, setSubModel non-replication flag, query SubModel Replicate Mode,query SubModel non-replication flag, explode a Model Instance,modify the SubModel reference of a Model Instance, query SubModeland SubModel name, prevent unused SubModels from beingautomatically freed, query SubModel permanent flag

NAME

gmsModInst( ), gmsModInst2( ), gmsSubModReplicateMode( ), gmsModNonReplicate( ), gmsQSubModReplicateMode( ), gmsQModNonReplicate( ), gmsInsExplode( ), gmsSubModelName( ), gmsQSubModel( ), gmsQSubModelName( ), gmsModPermanent( ), gmsQModPermanent( )

SYNTAX

idgmsModInst (name, modelname, point)

char *name;char *modelname;idPoint point;

idgmsModInst2 (name, modelname, point)

char *name;char *modelname;idPoint point;

intgmsSubModReplicateMode(mode)

int mode; /* 0 = never replicate1 = replicate all Instances2 = replicate only Instanceswith Renamed Variables */



intgmsModNonReplicate (model, action)

id model;int action; /* G_ON or G_OFF */

intgmsQSubModReplicateMode( )

intgmsQModNonReplicate (model)

id model;

idLinkRefgmsInsExplode (inst)

id inst;

intgmsSubModelName (inst, modelname, m2flag)

id inst;char *modelname;int m2flag; /* G_ON or G_OFF */

idgmsQSubModel(inst)

id inst; /* Instance to query */

char *gmsQSubModelName(inst)

id inst; /* Instance to query */

intgmsModPermanent (model, action)

id model;int action; /* G_ON or G_OFF */

intgmsQModPermanent (model)

id model;



DESCRIPTIONThe gmsModInst( ) function is used to create a Model Instance objectgiven the name of the Model to instance. The list of local SubModels inthe current Model is searched first, followed by the List of externalModels. If the named Model is found in one of these Lists, an Instanceis created which references it.

If the named Model is not found, an attempt is made to look in thecurrent directory and all directories specified by the list of library pathsfor a Model file by that name (terminated by a ".m1" extension). Iffound, the Model is read and entered into the External SubModels Listand an Instance is created which references it.


The position of the Instance is affected by the current transformationmatrix.

The gmsModInst2( ) function uses the "m2" filer to create a ModelInstance, searching first for a ".m2" file and then for a ".m1" file in eachdirectory in the search path. This function is complementary to theexisting gmsM2Get( ), gmsM2Save( ), gmsM2Merge( ), andgmsM2XGet( ) functions.

SubModels are often replicated by Model Instances which referencethem. If each Model Instance does not have a unique replicate of thetemplate SubModel, modifications to the appearance of the SubModelby one Model Instance will affect the appearance of all other ModelInstances referencing that SubModel.



The gmsSubModReplicateMode( ) function controls the SubModel Replicate Mode. If SubModel Replicate Mode is set, all Instances point to a clone of the SubModel they instance, enabling the user to change each Instance independently. Permitted values for the mode argument are:

NOTE: G_REPLICATE_ALWAYS is the default.

The primary use of the gmsSubModReplicateMode( ) function is topermit loading of external SubModels using the function gmsMXGet( ),while the SubModel Replicate Mode is G_NO_REPLICATE — noSubModels pointed to by Instances in the external Models loaded thisway are replicated. After loading external SubModels in this way, theSubModel Replicate Mode can be restored toG_REPLICATE_IF_RENVARS, the default, so that when top-levelModels are loaded, Instances contained within will be replicated asusual.

The gmsModNonReplicate( ) function sets or clears thenon-replication flag on a SubModel. By default, this flag is not set ona SubModel when it is created. When the flag is not set on aSubModel, the SubModel's replication behavior is defined by the globalflag set by the gmsSubModReplicateMode( ) function. When the non-replication flag is set on a SubModel, the global flag is overriddenand the SubModel is not replicated by a Model Instance.

Mnemonic Value Description

G_NO_REPLICATE 0 never replicate

G_REPLICATE_ALWAYS 1 replicate all Instances

G_REPLICATE_IF_RENVARS 2 replicate only Instances with Renamed Variables



Usually, the non-replication flag is set only on SubModels having noanimation or dynamics. Since the SubModel is never modified, ModelInstances referencing that SubModel do not conflict with one another.

Non-replicated SubModels can be used with dynamics in limitedcircumstances. Further information about these limitations is providedin the SL-GMS Reference Manual.

The non-replication flag must be set at run time. In order to set thenon-replication flag at run time, the SubModel must be pre-loadedusing gmsMXGet( ) or gmsM2XGet( ).

To gain full control over the replication behavior of SubModels, theapplication should first call:

gmsSubModReplicateMode(G_REPLICATE_ALWAYS);

Individual SubModels are pre-loaded:

id submodel1;

submodel1 = gmsMXGet("submodel1", "submodel1");

Then SubModels are marked non-replicated:

gmsModNonReplicate(submodel1, G_ON);

The gmsQSubModReplicateMode( ) function returns the currentsetting of the SubModel Replicate Mode.

The gmsQModNonReplicate( ) function returns the current status ofthe non-replication flag on a SubModel.

The gmsInsExplode( ) function replaces an Instance of a SubModelwith a copy of that SubModel’s part List, with the Point List transformedso that the parts remain in the same position. The List of the copiedparts is added to the current Model and also returned to the callingfunction. A Model must be current or this function fails.

The gmsSubModelName( ) function modifies the SubModel referenceof the given Model Instance. The gmsSubModelName( ) function isused in applications displaying Model Instances which have SubModelreferences that must remain undefined until run time. Since everyModel Instance must have some SubModel reference, a dummySubModel reference is assigned to such Model Instances before runtime. At run time, the application calls gmsSubModelName( ) on



Model Instances referencing the dummy SubModel, changing theirSubModel reference to the appropriate SubModel. Model Instancesused in this way are sometimes referred to as "placeholders."

The modelname parameter specifies the name of the SubModel. TheModel Instance will reference the SubModel with this name if it can befound in memory or on disk. A description of the searching algorithmused to find the SubModel is provided in the description of thegmsModInst( ) function on page -263.

If the m2flag parameter is set to G_ON, and the SubModel cannot befound in memory, gmsSubModelName( ) first attempts to read in theSubModel from a file with a ".m2" extension. If such a file cannot befound, gmsSubModelName( ) attempts to read in the SubModel from afile with a ".m1" extension.

Setting the m2flag parameter to G_OFF preventsgmsSubModelName( ) from attempting to read in the SubModel from afile with a ".m2" extension.

To illustrate the use of gmsSubModelName( ), suppose the top-levelModel topmodel1 is loaded:

id topmodel1;

topmodel1 = gmsMGet("topmodel1", "topmodel1");

This top-level Model contains two placeholder Model Instances whichreference the SubModel dummy. Before run time, the correctSubModel reference for these placeholders was unknown. At run time,this information is available, hence the application must find theplaceholder Model Instances and correct their SubModel references. Inthis case, both placeholders referencing dummy will be modified toreference correct_submodel:

id LinkRef parts_list;

id part;

char *submod_name;

parts_list = gmsQPartList(topmodel1);

while (parts_list) {

part = refQReference(parts_list);



submod_name = gmsQSubModelName(part);

if (submod_name && !strcmp("dummy",submod_name))

gmsSubModelName(part, "correct_submodel",G_ON);

parts_list = refQSuccessor(parts_list);

}

The gmsQSubModel( ) function returns the SubModel to which aModel Instance refers. The gmsQSubModelName( ) function returnsthe name of the SubModel to which a Model Instance refers.

The gmsModPermanent( ) function is used to set or clear thepermanent flag on a Model. By default, this flag is not set on a Modelwhen it is created. The permanent flag affects only the behavior ofModels which are SubModels. When the permanent flag is not set, aSubModel is freed when the last Model Instance referencing thatSubModel is freed. This is done to prevent accumulation of SubModelsin memory.

If the permanent flag is set on a SubModel, the SubModel can be freedonly by explicitly calling gmsObjFree( ). The SubModel is notautomatically freed when the last Model Instance referencing thatSubModel is freed.

Setting the permanent flag on a SubModel may improveperformance. When the last Model Instance referencing a givenSubModel is freed, that SubModel is freed. If another Model Instanceis loaded or created and it references the same SubModel (by name),the SubModel must be reloaded from disk. When the permanent flagis set, performance is improved by retaining the SubModel in memory,instead of reloading the SubModel from disk.

The permanent flag is typically set on a SubModel which is instancedin several top-level Models. This can decrease the amount of timeneeded to load a top-level Model because the SubModel will already bein memory.

The permanent flag must be set on a SubModel containing a SubModelreplicate cache to prevent the SubModel and cache from being freed



when the last Model Instance referencing that SubModel isfreed. Further information about SubModel replicate caches isprovided in the section Model Instance (ModInst) — caching on page269.

Currently, the status of the permanent flag on a SubModel cannot besaved in a ".m1" or ".g" file. This means that the permanent flag mustbe set at run time. In order to set the permanent flag at run time, theSubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ).

Individual SubModels are pre-loaded:

id submodel1;


Selected SubModels are then marked "permanent":


The gmsQModPermanent( ) function returns the current status of aModel’s permanent flag.

SEE ALSOgmsModel( ), gmsM2Get( ), gmsM2Save( ), gmsM2Merge( ), gmsMXGet( ), gmsM2XGet( ), gmsCRMv2( ), gmsCRRotz( ), gmsCRSca2( ), gmsChdir( ), gmsMExtToLoc( ), gmsMLocToExt( ), gmsMSave( ), gmsModCacheCapacity( ), gmsModCacheCount( ), gmsQModCacheCapacity( ), gmsQModCacheCount( )

SL-GML COMMANDS[name:] modinst modname x y

[name:] inst2 modname x y

[name:] modinst2 modname x y


Model Instance (ModInst) — caching


SUMMARY

create SubModel cache, query size of SubModel cache

NAME

gmsModCacheCapacity( ), gmsModCacheCount( ), gmsQModCacheCount( ), gmsQModCacheCapacity( )

SYNTAX

intgmsModCacheCapacity (submodel, capacity)

id submodel;int capacity;

intgmsModCacheCount (submodel, count)

id submodel;int count;

intgmsQModCacheCount (submodel)

id submodel;

intgmsQModCacheCapacity (submodel)

id submodel;

DESCRIPTIONThe gmsModCacheCapacity( ) function either creates a SubModelcache for the given SubModel or modifies the capacity of the existingSubModel cache associated with the given SubModel. The capacity ofa SubModel cache is the maximum number of SubModel replicateswhich can be stored in the SubModel cache.

If the given capacity is 0, gmsModCacheCapacity( ) will free the cacheassociated with the given SubModel. If the given capacity is greater



than 0, gmsModCacheCapacity( ) will create a cache for the givenSubModel (if one does not exist), and adjust the cache capacity.

A SubModel cache enables Model Instances to reuse SubModelreplicates, instead of creating and freeing them every time a ModelInstance is created or freed.

An active SubModel replicate is defined as one which is currentlyreferenced by a Model Instance. An inactive SubModel replicate is notcurrently referenced by a Model Instance. Only inactive SubModelreplicates can be stored in a SubModel cache. Active SubModelreplicates have the potential to be stored in a SubModel cache whenthey are made inactive.

When an active SubModel replicate is made inactive, an attempt ismade to store it in the appropriate SubModel cache. If this is notpossible, either because the cache does not exist or the cache hasreached its storage capacity, the replicate will be freed.

The gmsModCacheCapacity( ) function does not create any SubModelreplicates to store in a SubModel cache. SubModel replicates areautomatically created when a Model Instance is created or loaded fromdisk and an inactive SubModel replicate cannot be found in theappropriate SubModel cache (each Model Instance requires a uniquereplicate). SubModel replicates can also be created by using thegmsModCacheCount( ) function.

When the capacity of a SubModel cache is reduced usinggmsModCacheCapacity( ), it may be necessary to free inactiveSubModel replicates in the SubModel cache.

For any SubModel, the number of SubModel replicates in memory mayexceed the capacity of the associated SubModel cache. The SubModelcache capacity limits only the number of replicates which can bereused.

The gmsModCacheCount( ) function increases the count of theSubModel cache associated with the given SubModel if the given countis greater than the current cache count and the current cache count isless than the cache capacity. The count is the sum of the number ofinactive SubModel replicates stored in the cache and the number ofexisting active SubModel replicates which have the potential to bestored in the cache.



When a SubModel cache is created, its count is 0. The count of aSubModel cache automatically increases as more SubModel replicatesare created by Model Instances, until the cache count equals the cachecapacity. The SubModel cache count can never exceed the cachecapacity.

When gmsModCacheCount( ) is used to explicitly increase the countof a SubModel cache, new inactive SubModel replicates are createdand stored in the cache.

It is not possible to decrease the count of a SubModel cache using gmsModCacheCount( ); if the given count is less than or equal to the current count of the cache,gmsModCacheCount( ) does nothing.

The gmsQModCacheCount( ) function returns the count of theSubModel cache associated with the given SubModel. The count is thesum of the number of inactive SubModel replicates stored in the cacheand the number of active SubModel replicates which have the potentialto be stored in the cache. Only inactive SubModel replicates are storedin the cache. The count of a SubModel cache can never exceed thecache capacity.

The gmsQModCacheCapacity( ) function returns the capacity of theSubModel cache associated with the given SubModel. The capacity ofa SubModel cache is the maximum number of SubModel replicateswhich can be stored in the cache.

A SubModel with no cache has a cache capacity of 0.

EXAMPLEUsing a SubModel cache can improve the performance of anapplication which repeatedly creates and frees several Model Instanceswhich refer to the same SubModel. The overhead required to replicatethe SubModel and free the replicates is reduced. However, theapplication may consume more memory, since the replicates are nolonger automatically freed with the Model Instances.

Neither the SubModel cache capacity nor count attributes is saved in a".m1" or ".g" file. These attributes must be set at run time.

To set these attributes at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ):



id submodel1;


A SubModel cache is automatically destroyed when the originalSubModel (the template for the replicates) is freed. ThegmsModPermanent( ) function must be used to prevent submodel1from being automatically freed when the last Model Instancereferencing submodel1 is freed:


The gmsModCacheCapacity( ) function is then called to set thecapacity of the SubModel cache to a number smaller than or equal tothe maximum number of replicates predicted to exist in memory. Thisnumber can be determined by computing or estimating the number ofModel Instances which will be referencing submodel1 at the sametime. The closer the cache capacity is to the actual number ofreplicates which will exist in memory, the greater the optimization. Inthis example, it has been determined that no more than 100 ModelInstances will reference submodel1 at the same time:

gmsModCacheCapacity(submodel1, 100);

SubModel replication can be either batched or incremental.To batch SubModel replication, gmsModCacheCount( ) is calledimmediately after the gmsModCacheCapacity( ) call. This call willcreate 100 replicates of submodel1 and store them in the cache:

gmsModCacheCount(submodel1, 100);

To perform incremental SubModel replication, the application omits thegmsModCacheCount( ) call. As Model Instances referencingsubmodel1 are created or loaded from disk, replicates of submodel1are created. The count of the SubModel cache will increase, but willnever exceed the capacity. If the number of replicates needed is lessthan the capacity, the count will remain smaller than the capacity.

SEE ALSOgmsModPermanent( )


NDC (Normalized Device Coordinates)


SUMMARY

create or set points with Normalized Device Coordinates; set NDCscaling factor

NAME

gmsNPXY( ), gmsSNPXY( ), gmsNDCScale( )

SYNTAX

idPointgmsNPXY (x, y)

double x;double y;

idPointgmsSNPXY (point, x, y)

idPoint point;double x;double y;

intgmsNDCScale (scale)

double scale;

DESCRIPTIONThese functions are used to create and set values for Points usingNormalized Device Coordinates (NDC).

NDC Points are used in SL-GMS to set the Viewport limits associatedwith View objects. The Viewport specifies the region of a devicescreen on which the View is to be drawn. In order to achieve deviceindependence, these coordinates are normalized, that is, specified inthe range (0.0,0.0) to (1.0,1.0). These NDC values are adjustedinternally to the particular coordinate system for the device, usuallypixels.



The gmsNPXY( ) function is used only to create Points to be used asarguments to the gmsPort( ) function, which sets the Viewport for aparticular View object.

All NDC points created by SL-GML commands are created using thegmsNPXY( ) function. Once a Point is created, itsx and y values can be set using gmsSNPXY( ), rather than creatinganother Point. Points created using these functions may be freedusing the pntFree( ) function.

The gmsNDCScale( ) function sets the NDC scaling factor.

DIAGNOSTICSPresently, the internal representation for NDC coordinates is asintegers. The internal representation for NDC coordinates cannot beset by SL-GMS users.

SEE ALSOgmsPort( ), pnt*( )


Object — name

Object — name

SUMMARY

Set, return an object’s name, or remove an object’s name

NAME

gmsObjNameStr( ), gmsQObjNameStr( )

SYNTAX

intgmsObjNameStr (obj, str)

id obj;char *str;

char *gmsQObjNameStr (obj)

id obj;

DESCRIPTIONThe gmsObjNameStr( ) function sets an object’s name to the givenstring. If the string is a null string, the name is removed from theobject.

The gmsQObjNameStr( ) function returns an object’s name for thegiven object. A pointer to the real (not a copy) name of the object isreturned. If a nil pointer is given, the null string is returned. If noname is found, a null string is returned.

SEE ALSOgmsFindByName( )


Object — owner

Object — owner

SUMMARY

functions to query an object’s owner List

NAME

gmsQOwner( ), gmsQOwnerList( ), gmsQOwnerView( ), gmsQOwnerModel( ), gmsQOwnerState( )

SYNTAX

idgmsQOwner (obj)

id obj;

idLinkRefgmsQOwnerList (obj)

id obj;

idgmsQOwnerView (obj)

id obj;

idgmsQOwnerModel (obj)

id obj;

idgmsQOwnerState (obj)

id obj;


Object — owner

DESCRIPTIONThe gmsQOwner( ) function returns the object’s first owner.

The gmsQOwnerList( ) function returns the object’s List of owners.As of this release, the List contains the first owner only.

The gmsQOwnerView( ) function returns the first View that owns theobject.

The gmsQOwnerModel( ) function returns the first Model that owns theobject.

The gmsQOwnerState( ) function returns the State that contains theModel that owns the specified object. The object can be a Model itself.The specified object may be nested to an unlimited number of levelswithin a SubModel. If the Model containing the object has not beenattached to a State using gmsStAddModelName( ), the functionreturns 0. If a Model is referred to by multiple States, the lowest-levelState that refers to the Model is returned.


Object — parts

Object — parts

SUMMARY

return an object’s part List; query the number of parts; return a part;return the number of GraphTraces in a Model or a particularGraphTrace

NAME

gmsQPartList( ), gmsQNumParts( ), gmsQPartNum( ),gmsQNumTraces( ), gmsQTraceNum( )

SYNTAX

idLinkRefgmsQPartList (obj)

id obj;

intgmsQNumParts (obj)

id obj;

idgmsQPartNum (obj, n)

id obj;int n;

intgmsQNumTraces (model)

id model;

idgmsQTraceNum (model, tracenum)

id model;int tracenum;


Object — parts

DESCRIPTIONThe gmsQPartList( ) function returns an object’s part List. Thisfunction operates on Models, Model Instances, or Group objects, all ofwhich are constructed with Lists of other Graphical Primitive parts.This function returns a pointer to the part List.

NOTE: If the gmsQPartList( ) function is called on a Model Instance, itreturns a List of the parts in a SubModel. If there are dynamicdescriptions in the SubModel, or the SubModel Replicate Mode isset to G_ON, each Model instanced is a unique copy of theSubModel with parts that can be modified independently of otherModel Instances.

EXAMPLEThe short program that follows shows gmsQPartList( ) descendingthrough the part List of a Model and all of the subparts of Groups andModel Instances.

#include "gms.h"main( ){

id model;gmsSetup( );model = gmsMGet("test", "test");loop_over_parts(model);gmsClose( );

}intloop_over_parts (object)

id object;{idLinkRef parts, ptr, subparts;id part;

(program continued on next page)


Object — parts

/* get parts List */parts = gmsQPartList(object);

/* loop through parts List */for (ptr = parts; ptr; ptr = refQSuccessor(ptr)) {

part = refQReference(ptr);/* print the address of part */

printf ("%x\n", part);/* check for subparts */

subparts = gmsQPartList(part);/* if there are subparts, go deeper */

if (subparts)loop_over_parts(part);

}return 1;

}As each object is encountered in the List of parts (inside the for loop),its address in memory is printed. The loop_over_parts( ) functionmust be recursive because some parts, such as Groups and ModelInstances, have part Lists as well.

The gmsQNumParts( ) function returns the number of parts in a partList. The gmsQPartNum( ) function returns the part at the given indexinto the object’s part List. These functions operate on the same type ofobjects as gmsQPartList( ).

The gmsQNumTraces( ) function returns the number of GraphTraceobjects in a Model. The gmsQTraceNum( ) function returns a pointerto a particular GraphTrace.

DIAGNOSTICSThe part List returned is the actual part List from the object. Careshould be taken not to inadvertently modify or destroy this List. Theobject that owns the parts may be corrupted.

SEE ALSOgmsObjIsClass( ), gmsDump( ), refQSuccessor( ), refQReference( )


Performance optimization

Performance optimization

SUMMARY

set the time_level flag

NAME

gmsTimeLevel( )

SYNTAX

intgmsTimeLevel (level)

int level;

DESCRIPTIONThe gmsTimeLevel( ) function sets the time_level flag. This flag is 0by default. Setting the flag to 1 displays the time duration spent duringeach system update. (System updating involves preparing objects fordisplay.) The message

time: total time for gmsRedCode( )

indicates the amount of time spent clearing flags and updating. Toobtain more detailed reports, the level is set to 2. These times givesome indication of system performance and vary with Views containingModels with more or less complexity.

SEE ALSOThe chapter entitled in the SL-GMS Reference

SL-GML COMMANDStime

etime


Pie object

Pie object

SUMMARY

create a Pie object

NAME

gmsPie( ), gmsPie2( ), gmsFPie( ), gmsFPie2( )

SYNTAX

idgmsPie (name, center, radius, start, length)

char *nameidPoint center;double radius;double start;double length;

idgmsPie2 (name, points)

char *name;idLinkRef points;

idgmsFPie (name, center, radius, start, length)

char *nameidPoint center;double radius;double start;double length;

idgmsFPie2 (name, points)



Pie object

DESCRIPTION The gmsPie( ) function is used to create a Pie object given a centerPoint, radius, start angle, and arc length. The Pie object is createdwith the current attributes. The radius is in World Coordinates and ismultiplied by the World Coordinate Scale factor. Angles and arc lengthare in degrees and sectors are always drawn counterclockwise.

The gmsPie2( ) function creates a Pie object given a center Point andtwo Points which are on the radius. The Points must be passed in aPoint List. The second Point on the arc (the third in the List) will beadjusted to be on the radius if it is not already.

The gmsFPie( ) and gmsFPie2( ) functions are used in the samemanner as their counterparts without the "F", but the Pie objectsproduced are filled.

The name argument is optional and is the name that is assigned to theobject when it is added to the current Model. The current edgeattributes are applied to the object when it is created.

SEE ALSOgmsCWFlag( )

SL-GML COMMANDS[name:] pie x y radius start length

[name:] pie2 x y x y x y

[name:] fpie x y radius start length

[name:] fpie2 x y x y x y


Plotted Points

Plotted Points

SUMMARY

plot Points of a GraphTrace; clear a plotted region; reset a GraphTrace;shift Points in a GraphTrace

NAME

gmsPlotData( ), gmsPlotDataX( ), gmsPlotDataY( ), gmsPlotClear( ), gmsPlotReset( ), gmsPlotShiftX( ), gmsPlotShiftY( )

SYNTAX

intgmsPlotData (obj, xdata, ydata)

id obj;double xdata;double ydata;

intgmsPlotDataX (obj, xdata)

id obj;double xdata;

intgmsPlotDataY (obj, ydata)

id obj;double ydata;

intgmsPlotClear (obj)

id obj;

intgmsPlotReset (obj)

id obj;


Plotted Points

intgmsPlotShiftX (obj, shiftval)

id obj;double shiftval;

intgmsPlotShiftY (obj, shiftval)

id obj;double shiftval;

DESCRIPTIONThese functions plot, clear, reset, or shift plotted Points of GraphTraceobjects. The gmsPlotData( ) function plots a single Point of aGraphTrace object using the template Line or Marker style andattributes. The position of the plotted Point is determined by where thex and y data fit within the x and y valuelimits set for this GraphTrace,and by the World Coordinate values established by gmsCoordLimits( )for the GraphTrace. Points will never be plotted outside of the regiondefined by the coordlimits.

The gmsPlotDataX( ) and gmsPlotDataY( ) functions receive thecoordinates to plot one at a time, but do nothing until both an x and a ycoordinate are received. The x coordinate must be sent before the ycoordinate.

The gmsPlotClear( ) function clears the region defined by thecoordlimits for the GraphTrace. This action erases everything withinthis region, including other GraphTraces, tick marks, and othergraphical objects. The gmsPlotReset( ) function erases theGraphTrace and clears its Point List.

The gmsPlotShiftX( ) and gmsPlotShiftY( ) functions add the shiftvalto all the x or y coordinates currently in the GraphTrace object’s PointList. This has the effect of shifting the entire GraphTrace right or left(for positive or negative x shift values) or up or down (for positive ornegative y shift values). These actions are useful when implementingtrend Graphs.


Plotted Points

SEE ALSOgmsGraphAxis( ), gmsCoordLimits( ), gmsGraphTrace( ),gmsXValueLimits( )

The chapter entitled in the SL-GMS Reference

SL-GML COMMANDSname plotdata xvalue-real yvalue-real

name plotdatax xvalue-real

name plotdatay yvalue-real

name plotclear

name plotreset

name plotshiftx xshift-real

name plotshifty yshift-real


Point Lists

Point Lists

SUMMARY

get an object’s or List of objects’ Point List(s) or extended Point List(s);return a sub-object’s Point List relative to a top object

NAME

gmsLQPointList( ), gmsLQXPointList( ), gmsQPartPointList( ), gmsQPointList( ), gmsQXPointList( ), gmsLPFndPt( )

SYNTAX

idLinkRefgmsLQPointList (objlist)

idLinkRef objlist;

idLinkRefgmsLQXPointList (objlist)

idLinkRef objlist;

idLinkRefgmsQPartPointList (topobj, subobj)

id topobj;id subobj;

idLinkRefgmsQPointList (obj)

id obj;

idLinkRefgmsQXPointList (obj)

id obj;

intgmsLPFndPt (ptlist, point)

idLinkRef ptlist;idPoint point;


Point Lists

DESCRIPTIONThe gmsLQPointList( ) function returns a Point List containing Pointsof all objects in the List. Any transformation matrix attached to anobject is applied to the Points before they are added to the returnedPoint List.

The gmsQPartPointList( ) function returns a List of the sub-object’sPoints relative to the given top object. The top object could be a ModelInstance or a Group with its own transformation matrix that affects thesub-objects. This function applies the top object’s transformations(and the sub-object’s transformations) to the sub-object’s Points beforereturning the Point List.

The gmsQPointList( ) function returns a pointer to an object’s PointList, which is a linked List of Point objects. The Point List, or a Point inthe List, may be used to create other objects that are connected to theobject, or by other functions that require Point Lists. ThegmsLPFndPt( ) function may also be used to find the Point closest to aPoint in the Point List.

The extended Point List contains additional Points beyond those usedto define Circle or Rectangle objects. These Points are the center ofthe object, and the top, bottom, left, and right Points of a Circle object,or the centers of a Rectangle object’s sides. The gmsQXPointList( )and gmsLQXPointList( ) functions return Lists of the extended PointLists.

It is the programmer’s responsibility to free the LinkRef object returnedby these functions when finished using the Point List by usingrefKilAll( ).

The gmsLPFndPt( ) function returns an index into the given Point Listto a Point that is closest to the given Point. If two Points in the PointList are exactly equidistant to the given Point, the index to the first Pointfound is returned. If no Points are found, -1 is returned (bad Point orPoint List arguments).

EXAMPLEid rect = gmsRect(nil, pointA, pointB);idLinkRef ptlist = gmsQPointList(rect);


Point Lists

gmsDump (ptlist);refKilAll (ptlist);ptlist = 0;

SEE ALSOrefKilAll( )

SL-GML COMMANDSname points

name xpoints


Point Lists — replace


SUMMARY

replace an object’s Point List; apply objects’ transformations on thePoint List argument, then replace the sub-object’s Point List; reverseorder of a Point List

NAME

gmsPoints( ), gmsLPoints( ), gmsPartRpPs( ), gmsRvrsPts( )

SYNTAX

intgmsPoints (obj, points)

id obj;idLinkRef points;

intgmsLPoints (objlist, points)

idLinkRef objlist;idLinkRef points;

intgmsPartRpPs (topobj, subobj, points)

id topobj;id subobj;idLinkRef points;

idLinkRefgmsRvrsPts (points)

idLinkRef points;



DESCRIPTIONThe gmsPoints( ) function replaces an object’s Point List with the PointList specified in the points argument. The Point List must contain thecorrect number of Points to define the object, that is, two Points for aRectangle, at least two Points for a Polyline, and so on. Essentially,the gmsPoints( ) function allows the user to move and/or transform anobject without creating a transformation object or recreating the object.

The gmsLPoints( ) function performs the gmsPoints( ) functionalityupon each object in the List specified as the first argument.

The gmsPartRpPs( ) function is used to change the Point List of anobject that is a sub-object. Sub-objects are affected by thetransformation applied to their top objects. For example, atransformation applied to a Group applies to the Points of thesub-objects in the Group, and the sub-objects may also have individualtransformation matrices.

The gmsPartRpPs( ) function takes into account all the transformationsmatrices, starting at the top object and ending at the sub-object, to thePoints in the Point List before replacing the sub-object’s Point List.Thus, an untransformed Point List is modified correctly before replacinga sub-object’s Point List.

The gmsRvrsPts( ) function reverses the order of Points in a Point List,such that the first Point becomes the last, and so on. The new PointList is returned.

SEE ALSOgmsGroup( ), gmsQPointList( )

The chapter entitled Object Attributes in the SL-GMS Quick Referencefor the number of Points to define an object


Point object

Point object

SUMMARY

functions and object definition for Point class

NAME

pntNew( ), pntNewXY( ), pntSetXY( ), pntFree( ), pntClone( ), pntX( ),pntY( )

SYNTAX

idPointpntNew( );

idPointpntNewXY (x, y)

coordVar x, y;

intpntSetXY (point, x, y)

idPoint point;coordVar x, y;

intpntFree (point)

idPoint point;

idPointpntClone (point)

idPoint point;

coordVarpntX (point)

idPoint point;

coordVarpntY (point)

idPoint point;


Point object

DESCRIPTION This section describes the Point class, an object containing a pointer tothe class of the object (Point), and x and y coordinates. The typecoordVar is defined in the file "objects.h", in the lib directory.

Points may be created using either the pntNew( ) or the pntNewXY( )functions. The x and y values may be set on an existing Point usingthe pntSetXY( ) function. The World Coordinate Scale Factor is notused when Points are made with the pnt*( ) functions. It is usuallypreferable to use the higher level point-creation routines, such asgmsWPXY( ), which automatically converts World Coordinate values tothe correct internal representation (by multiplying them by the WorldCoordinate Scale Factor).

An identical copy (Clone) of a Point may be created using pntClone( ).

SL-GMS maintains a "pool" of Points for quick retrieval. When finishedwith a Point object, for example, after using it in a function call, it can befreed (returned to the "pool") with the pntFree( ) function call. Asshown in the example below, the pointer to any object should always beset to null immediately after freeing the object.

The pntX( ) function returns the integer x coordinate of the Pointpassed to it, and the pntY( ) function returns the integer y coordinate ofthe Point passed to it.


Point object

EXAMPLEThe two Point creation functions below create identical Point objects.In general it is preferable to use the gmsWP*( ) functions since theyautomatically convert World Coordinate values to Internal Coordinates.In the example below, the gmsWValue( ) function is used to convertWC values to IC values.

idPoint pointA;pointA = pntNewXY(gmsWValue(10.0),

gmsWValue(20.0));

/* free the Point */pntFree(pointA);

/* it’s a good idea to always “zerothe pointer” */

pointA = 0;

/* create an identical Point using thegmsWPXY( ) function */

pointA = gmsWPXY(10.0, 20.0);

A second Point can be created with the identical coordinates with thepntclone( ) function:

idPoint pointB;pointB = pntClone(pointA);

Now there are two Point objects with the same coordinates. A Pointobject can be re-used by resetting its coordinates with the pntSetXY( )function.


Point object

SEE ALSOSL-GMF uses four functions for creating Point objects. ThegmsNPXY( ) function is used solely for creating arguments used withthe gmsPort( ) function. The pntNew( ) function creates Points withinteger arguments that are not scaled. The gmsWPoint( ) functioncreates a World Coordinate System Point object with the coordinatesset to the origin (0,0). The gmsWPXY( ) function also creates a WorldCoordinate System Point object but allows setting of the coordinates:

idPoint pointA;pointA = gmsWPXY(5., 0.);

The code fragment above creates a new Point object and returns apointer to itself. The pnt*( ) functions should be used for manipulatingor freeing Point objects. The gmsWP*( ) functions are a convenienceprovided for scaling the coordinates choosen. SL-GMSDraw, andSL-GML use the gmsWPXY( ) function.


Polygon object

Polygon object

SUMMARY

create a Polygon object

NAME

gmsPolygon( ), gmsFPolygon( )

SYNTAX

idgmsPolygon (name, points)


idgmsFPolygon (name, points)


DESCRIPTIONThe gmsPolygon( ) function creates a Polygon object by connectingthe given List of Points with Lines. The refNew( ) function is used tocreate Lists of objects. The first and last Points in the List areconnected by a Line, thus the function always creates ClosedPolygons. The Polygon object created possesses the currentattributes.

The gmsFPolygon( ) function creates Filled Polygons in the samemanner.

The name argument is optional and is the name assigned to the objectwhen it is added to the current Model. The current edge attributes areapplied to the object when it is created.


Polygon object

SL-GML COMMANDS[name:] poly x y x y ...

[name:] fpoly x y x y ...

SEE ALSOrefNew( )


PostScript

PostScript

SUMMARY

create PostScript files and set PostScript parameters

NAME

gmsPsSetParams( ), gmsPsWsProcArgs( ), gmsPsWsProcArgsStr( ), gmsPsPolyMaxPoints( ),gmsPsViewWrite( ), gmsPsLViewWrite( )

SYNTAX

intgmsPsSetParams(workst, dcmax_x, dcmax_y, off_x, off_y,

rotate, one_pix, ps_flags, comment);id workst; /* id of a Workstation/Window*/int ps_dcmax_x; /* max x in device coordinates */int ps_dcmax_y; /* max y in device coordinates */int ps_off_x; /* x offset from 0 in DC */int ps_off_y; /* y offset from 0 in DC */int ps_rotate; /* 0 = portrait

90 = landscape */int ps_one_pix; /* coordinate range of one pixel

used only as a fudge for clipping*/

int ps_flags; /* optional flags/char *ps_comment;/* comment to appear in

PostScript file*/

intgmsPsWsProcArgs(argc, argv)

int argc; /* main( ) argument count */char *argv[]; /* main( ) arguments */


PostScript

intgmsPsWsProcArgsStr(argstr)

char *argstr; /* string containing main( )arguments separated by spaces*/

intgmsPsPolyMaxPoints (max_points)

int max_points; /* 2 <= max_points <= GMS_MAX_POINTS*/

intgmsPsViewWrite(workst, view, name);

id workst; /* id of a PostScript Workstation */id view; /* id of a View object */char *name; /* name of PostScript output file */

intgmsPsLViewWrite(workst, viewlist, name);

id workst; /* id of a PostScript Workstation */id viewlist; /* id of a View List */char *name; /* name of PostScript output file */

DESCRIPTIONThe gmsPsSetParams( ) function sets the PostScript Workstationparameters.

The parameters for the gmsPsSetParams( ) function and their defaultvalues in SL-GMS are as follows:

ps_dcmax_x Maximum x value in Device CoordinatesDefault value: 7200

ps_dcmax_y Maximum y value in Device CoordinatesDefault value: dcmax_x * 3/4.

ps_off_x x offset from 0 in Device CoordinatesDefault value: 0

ps_off_y y offset from 0 in Device CoordinatesDefault value: 0


PostScript

ps_rotate Rotation (relative to the lower left Point of the View) Default value: 0

ps_one_pix Coordinate range of one pixel used only asa fudge for clipping. Default value: 2

ps_flags options are described in thetable Bit options for "psflags" on page 300. Default value: 0

ps_comment Comment to appear in PostScript file.Default value: 0 (null — no comment)

The following options can be set by setting their appropriate bit in theps_flags:

For example, to set the ps_flags to add a black border and to outputmultiple views:

int ps_flags = 0;

ps_flags |= 0x4;

ps_flags |= 0x100;

Bit options for "psflags"

bit Description 0x1 supply header for FrameMaker

0x2 omit clipping

0x4 output several views to one file

0x10 use portrait mode

0x20 add initgraphics to output file

0x40 do not include view in bounding box

0x100 add thin black border line at max x and y

0x200 use solid lines for line width < 1.0

0x400 reverse black/white

0x1000 add extra fudge factor to clip rectangles


PostScript

The gmsPsWsProcArgs( ) function is used to set PostScript Workstation parameters for the default PostScript Workstation. This function controls not only a superset of the parameters of gmsPsSetParams( ), but allows the user to specify the options on the application command line, as well. The following are valid command-line arguments:

Option Description-pol set landscape mode-pop set portrait mode-px<n> set x offset-py<n> set y offset-ps<n> set scaling factor to n/100 where n is percent-pr<n> set rotation-pl do not change lines of width <= 1.0 to color

black-pb supply thin black border line at max x and y-pa output all (multiple Views)-pc<string> supply <string> as comment in PostScript file-pf supply heading for FrameMaker-pf<N> set the ps_flags option fields; N is an integer

representing any one of the option bits listed under "ps_flags" of gmsPsSetParams( )

-pp<n> set coordinate range of one pixel-pw<n> set maximum dc x coordinate-ph<n> set maximum dc y coordinate-pno_fill_pattern produce a level_1 PostScript file which

eliminates fill patterns; eleven different fill patterns are provided in PostScript but a printer must have level_2 PostScript support to display the fill patterns; if level_2 PostScript support is not provided, the -pno_fill_pattern option must be used; this option can also be used to reduce the size of SL-GMS-generated PostScript files if fill patterns are not needed


PostScript

The default is landscape orientation, offset and scaled to fit page size8.5 x 11".

The same arguments1 can be given when printing a file fromSL-GMSDraw using the PostScript option of the System Pull-DownMenu or from SL-Draw using the Print option of the System Pull-DownMenu. The SL-GMS® Reference describes the process used toproduce a PostScript file from SL-GMSDraw. The SL-GMS®Draw User’s Guide describes the processused to produce a PostScript file from SL-GMS Draw.

The gmsPsWsProcArgs( ) function should be called before openingthe PostScript Workstation.

For non-C programming languages, or situations where the arc-argv mechanism is inconvenient or simply unavailable, thegmsPsWsProcArgsStr(argstr) function can be used instead ofgmsPsWsProcArgs( ).

argstr is of type char *, where the character string containsspace-separated arguments. Quotes attempting to combine words intoone argument are not accounted for.

For example, the following two calls result in the same print output to aPostScript file with -op, -c, and -s options.

gmsPsWsProcArgsStr("-pop -pctest_print-ps50")

is the same as

gmsPsWsProcArgs(argc, argv)with:

argc = 3argv[0] = "-pop"argv[1] = "-pctest_print"argv[2] = "-ps50"

1. The first "p" shown after the "-" in each of the options is not required when printing a file from SL-GMSDraw.


PostScript

The gmsPsPolyMaxPoints( ) functions sets the maximum number of points a polyline may have. PostScript interpreters vary in terms of the maximum number of points they can process in one polyline. Some can handle only 200, while most can handle 1500 or more. The SL-GMS default maximum is 1500 points unless overidden by this function.Polylines that are larger than the interpreter’s limit are "broken" into smaller segments when printed.

For example, the following code fragment could be used to informSL-GMS that a printer’s upper limit for the number of points in a polylineis 200.

idLinkRef views;int p_argc;char * p_argv[3];views = refNewRef(gmsFindByName("v_main"));refAdd( views, gmsFindByName("v_sub"));p_argc = 3;p_argv[0] = "-pa";p_argv[1] = "-pl";p_argv[2] = "-pf8";gmsPsWsProcArgs(p_argc, p_argv);gmsPsPolyMaxPoints(200);

gmsPsLViewWrite(gmsQEvWorkst(gmsQGismoEvent( )), views,"test")

If the maximum number of points in a poly line must be changed usinggmsPsPolyMaxPoints( ), the call must be made beforegmsPsViewWrite( ), or gmsPsLViewWrite( ) is called.

The gmsPsViewWrite( ) function writes a View to a PostScript file whilethe gmsPsLViewWrite( ) function outputs a list of Views to a singlePostScript file.

For the gmsPsLViewWrite( ) function the first argument, workst, is theid of a PostScript Workstation. The second argument, view, is theView to be output; viewlist is the List of Views to be output. The third


PostScript

argument, name, is an ASCII string which is used as the output filename.

The size of the PostScript image is determined by the size of theViewport. A Viewport size of (0.0, 0.0) (1.0, 0.75) renders a PostScriptimage that fits on a 8.5 x 11 inch page (in landscape orientation). If adifferent size Viewport is used, it should be changed to (0.0, 0.0) (1.0,0.75) using gmsPortXY( ), before calling the gmsPsViewWrite( ) orgmsPsLViewWrite( ) functions. It should be noted that image size isalso affected by the scaling parameter, which is included in thedescription of gmsPsWsProcArgs( ).

NOTE: In version 4.0, rotation is performed around the Point (0,0), so itmay be necessary to move the PostScript image after it has beenrotated.

If name does not contain a dot, SL-GMS appends ".ps" to the name ofthe file. If the name parameter is null, the file name "<number>.ps" isused, where <number> is a sequentially increasing integer.

NOTE: In version 4.0 the workst argument is ignored; it is reserved forlater use when multiple PostScript Workstations may beprovided. For now, 0 must be used for the workst argument.

To be able to use the gmsPsLViewWrite( ) function successfully, theuser must set the 0x4 bit of ps_flags using gmsPsSetParams( ) orpassing the option -pa or -pf0x4 to gmsPsWsProcArgs( ).


PostScript

For example, the following code fragment could be used to print aPostScript file with the -a, -l, and -f8 options:

idLinkRef views;

int p_argc;

char * p_argv[3];

views = refNewRef(gmsFindByName("v_main"));

refAdd( views, gmsFindByName("v_sub"));

p_argc = 3;

p_argv[0] = "-pa";

p_argv[1] = "-pl";

p_argv[2] = "-pf8";

gmsPsWsProcArgs(p_argc, p_argv);

gmsPsLViewWrite(gmsQEvWorkst(gmsQGismoEvent( )),

views, "test")

SEE ALSOgmsPortXY( ), gmsQEvWorkst( ), gmsQGismoEvent( )

Print and Postscript in the SL-GMS Reference


Projects

Projects

SUMMARY

initialize, get, save, or merge a Project

NAME

gmsProject( ), gmsPGet( ), gmsPSave( ), gmsPMerge( )

SYNTAX

intgmsProject( )

intgmsPGet (name)

char *name;

intgmsPSave (name)

char *name;

intgmsPMerge (name)

char *name;

DESCRIPTIONWhile the gmsProject( ) function is automatically invoked when startingSL-GML, it is not required for use of other SL-GMS functions.

Anytime it is desired to start an application "from scratch," thegmsProject( ) function clears out all Models and Views and resets allmodal attributes and transformations to their defaults.

The gmsPGet( ) function is used to get a Project which had been savedusing the gmsPSave( ) function. Saving a Project creates a file with a".p1" extension, and includes the status of the entire system, includingmodal attribute settings and modal transformations, all Views, and allModels. The Workstation/Window information is not saved in a


Projects

Project, and calling gmsPGet( ) does not close the currentWorkstation/Window.

The gmsPMerge( ) function is used to read a Project from a file andmerge its Models and Views with the existing Project. Modal attributesand transformations are replaced by those of the merged Project.

SL-GML COMMANDSproject

project get name

project save name

project merge name


Query user

Query user

SUMMARY

query for a string, or a yes/no response from user

NAME

gmsAskLine( ), gmsQuery( )

SYNTAX

intgmsAskLine (prompt, namebuff, buffsize)

char *prompt;char *namebuff;int buffsize;

intgmsQuery (prompt)

char *prompt;

DESCRIPTIONThese two functions query the SL-GMS user for a response. ThegmsAskLine( ) function copies the user’s response into the areapointed to by namebuf. If prompt is nil, the string

Enter:is used as a prompt, otherwise the null-terminated string pointed to byprompt is used. The application program supplies the buffernamebuf.

The gmsQuery( ) function returns a 1 when user responds with "yes","YES", "Y", or "y". If prompt is nil, the string

Enter:is used as a prompt, otherwise the null-terminated string pointed to byprompt is used. When using SL-SMS, the preferred method of textentry is through use of either the TEXTENTRY ARRAY or TEXTENTRYVAR GISMOs.


Query user

SEE ALSOgmsStTextEditObj( ), gmsWsTextEditObj( )


Radius set and get

Radius set and get

SUMMARY

set or get the radius of some objects

NAME

gmsRadius( ), gmsLRadius( ), gmsQRadius( )

SYNTAX

intgmsRadius (obj, radius)

id obj;double radius;

intgmsLRadius (objlist, radius)

idLinkRef objlist;double radius;

doublegmsQRadius (obj)

id obj;

DESCRIPTIONThe gmsRadius( ) function sets the radius for objects that are definedby specifying a center and radius. Circles, Sectors, and Pies haveradii. Changing the radius does not affect the center. ThegmsLRadius( ) function changes the radius for a List of objects andgmsQRadius( ) returns the radius of an object.

SL-GML COMMANDname radius real


Raster image of objects — save and restore


SUMMARY

pop-on or pop-off an object, restoring the image under the object;release memory used to save images

NAME

gmsPopOn( ), gmsPopOff( ), gmsPopReset( )

SYNTAX

intgmsPopOn (view, object, saveObj, inMode)

id view;id object;int saveObj;int inMode; /* ignored */

intgmsPopOff (view, object, saveFlag)

id view;id object;int saveFlag;

intgmsPopReset ( )

DESCRIPTIONThe gmsPopOn( ) function makes an object visible while arranging toredisplay any objects obscured by this action. The gmsPopOff( )function makes a popped-on object invisible and restores the imagesaved when the object was popped on.

When an object is popped on, its extent is calculated and saved in aninternal table. Popping off the object involves redrawing this extent inthe View given as an argument to gmsPopOff( ). The View given asan argument must contain both the object to be made visible and the



objects that will be obscured when the object is made visible. Initially,the object to be made visible must be invisible.

The gmsPopOn( ) function has two additional arguments: saveObjand inMode. The saveObj argument, when set to 1, saves a rasterimage of the popped-on object.

The raster image is used to redraw the popped-on object on platformswhere this action is appropriate. Since not all platforms can saveraster images or display these saved images faster than it would take toredraw the object, the saveObj flag is not normally set to 1. TheinMode argument is currently ignored.

The saveFlag argument to gmsPopOff( ), when set to 1, preserves theinformation about the popped-off object in the internal table. Thedefault behavior is to release this information, the object’s extent, andpossibly its raster image when the object is popped off. Setting thesaveFlag to 1 expedites the popping back on of this object. Thecurrent limit to the number of objects that can be saved is 64.

The gmsPopReset( ) function releases the information kept in theinternal table about popped-on objects.

Popon/popoff Modes in SL-GMSWhen a popup object (e.g., Menu or Dialog Box) is erased, thegraphical data that was covered by it must somehow be restored.Restoration of graphical data is accomplished by drawing and erasingthe object in a Popon/popoff Mode.

SL-GMS has two Popon/Popoff Modes:

Mode Type DescriptionRaster Popon/popoff Mode

saves a raster image of the area to be covered by an object; to erase an object the raster image is redrawn

Clip Popon/popoff Mode

constructs a clipping rectangle around an object; it erases an object by clearing the View of the object within the clipping rectangle; it then redraws all the Views within the clipping rectangle



NOTE: The Popon/popoff Mode Workstation option,G_WS_POP_RASTER, should be used if a popup object's extentoverlaps more than one View. The screen redraws incorrectly if ClipPopon/popoff Mode, G_WS_POP_CLIP, is used.

The effects of the Raster and Clip Popon/popoff Modes can be seen inthe Dialog on-line example. The on-line example is run with -pr forRaster Popon/popoff Mode, or -pc or Clip Popon/popoff Mode. The"Timer" and "Exit" Dialog Boxes are drawn and erased in the specifiedmode.


Raster image of View — save, restore, create


SUMMARY

save, restore, and create rasters images of a View

NAME

gmsVuRSave( ), gmsVuRRest( ), gmsVuRFile( )

SYNTAX

short *gmsVuRSave (view, workst)

id view;id workst;

intgmsVuRRest (view, workst, raster, freeFlag)

id view;id workst;short *raster;int freeFlag;

intgmsVuRFile (view, workst, filename)

id view;id workst;char *filename;

DESCRIPTIONThese functions are useful for manipulating the raster which is "under"a View object. The limits of the Viewport determine the size andnumber of pixels in the raster. This is dependent upon the Workstation,hence the Workstation must be passed as an argument.

The gmsVuRSave( ) function is used to save the raster under a workarea so that it can be restored later. The pointer to the pixels returnedby this function is passed to the gmsVuRRest( ) function in order to put



them back. The freeFlag argument to the gmsVuRRest( ) functiontells the function to free the raster if the flag is set to 1.

The gmsVuRFile( ) function is used to write the pixels to a file in amachine-dependent manner. The filename has the ".xwd" extensionappended in an X Window platform, and the ".bmp" extension in aWin32 platform.1

SEE ALSOgmsView( ), gmsWind( ), gmsBitmap( )

SL-GML COMMANDvfile

1. Win32 refers to a platform with a 32-bit architecture running Microsoft Windows NT or Windows 95.


Raster Operation Mode attribute


SUMMARY

set the Raster Operation Mode attribute

NAME

gmsRastOp( ), gmsLRastOp( ), gmsMRastOp( )

SYNTAX

intgmsRastOp (obj, rastop)

id obj;int rastop;

intgmsLRastOp (objlist, rastop)

idLinkRef objlist;int rastop;

intgmsMRastOp (rastop)

int rastop;



DESCRIPTIONThe gmsRastOp( ) function is used to set the Raster Operation Modeon SL-GMS Primitive objects. Raster Operation Mode is an attributethat applies to Bitmap objects. The following truth table depicts themeaning of the 16 possible values for Raster Operation Modes.

Some of the 16 possible values are not used, such as set to 1 or set to0. All values are platform-dependent. For example, a particularplatform has only three modes: overwrite (Source only (3)), AND (1),and XOR (6). The Workstation object may map other Raster OperationModes to one of these three functional values.

In raster operations, the erase color is 0 so anytime a Bitmap is ANDedto a region of a View containing the erase color, the Bitmap is alsoerased in those regions.

Raster Operation Modes

Source 0 0 1 1 Raster Operation Mode NumberDestin 0 1 0 1

Set 0 0 0 0 0 0AND 0 0 0 1 1S & ~D 0 0 1 0 2Source 0 0 1 1 3~S & D 0 1 0 0 4Destin. 0 1 0 1 5XOR 0 1 1 0 6OR 0 1 1 1 7NOR 1 0 0 0 8~XOR 1 0 0 1 9~D 1 0 1 0 10S | ~D 1 0 1 1 11~S 1 1 0 0 12~S | D 1 1 0 1 13NAND 1 1 1 0 14Set 1 1 1 1 1 15



The gmsLRastOp( ) function sets the Raster Operation Mode on a Listof objects. The Raster Operation Mode attributes are the same as forthe gmsRastOp( ) function.

The gmsMRastOp( ) function sets the modal Raster Operation Mode,affecting subsequently created Graphical Primitives.

SEE ALSOgmsBitmap( )

SL-GML COMMANDSname rastop rastmode


Rectangle object

Rectangle object

SUMMARY

create a Rectangle object

NAME

gmsRect( ), gmsRRect( ), gmsFRect( ), gmsRFRect( ), gmsFTRect( ), gmsRFTRect( )

SYNTAX

idgmsRect (name, points)


idgmsRRect (name, points)


idgmsFRect (name, points)


idgmsRFRect (name, points)


idgmsFTRect (name, points, text)

char *name;idLinkRef points;char *text;


Rectangle object

idgmsRFTRect (name, points, text)

char *name;idLinkRef points;char *text;

DESCRIPTIONThe gmsRect( ) function is used to create a Rectangle object given twoPoints contained in a Point List. The gmsRRect( ) function is identicalexcept the second Point in the List is a relative offset from the firstPoint. The current edge attributes are applied to the object when it iscreated.

The gmsFRect( ) and gmsRFRect( ) functions are identical to theircounterparts without the "F", but Filled Rectangles are created.

The gmsFTRect( ) and gmsRFTRect( ) functions create FilledRectangles that contain Text. The Text is passed to these functions viathe third argument, which is a simple C string(a pointer to character). All current Text attributes apply to the textportion of the object.

The name argument is optional and is the name that is assigned to theobject when it is added to the current Model.

EXAMPLEThe following code fragment demonstrates the creation of a Rectangleobject.

/* declare variables */idPoint pointA, pointB;id LinkRef corners;id rect;

/* create Points for Rectanglecorners*/

pointA = gmsWPXY(5., 0.);pointB = gmsWPXY(95., 70.);

/* add Points to List */corners = refNewRef(pointA);refAdd(corners, pointB);


Rectangle object

/* create Rectangle named"frame" */

rect = gmsRect("frame", corners);

/* display the Rectangle */gmsUpdate(nil);

Creating Graphical Primitive objects requires other objects asarguments. First, two Point objects are created, using the WorldCoordinate Point-creation function, gmsWPXY( ). Next, these Pointsare added to a Linked List object, which is passed as an argument tothe gmsRect( ) function. The current Model now contains a singlepart: the Rectangle object. The gmsUpdate( ) function causes theRectangle to be displayed.

The corresponding SL-GML commands that perform the sameoperations as the program fragment above are:

<gms._gms1> gml ready> frame: rect 5 0 95 70<gms._gms1> gml ready> immu

SL-GML COMMANDS[name:] rect x y x y

[name:] rrect x y x y

[name:] frect x y x y

[name:] rfrect x y x y

[name:] ftrect x y x y "text"

[name:] rftrect x y x y "text"


Reference Point

Reference Point

SUMMARY

change an object’s or List of objects’ Reference Point; return anobject’s Reference Point

NAME

gmsRefPoint( ), gmsRefPointX( ), gmsRefPointY( ), gmsLRefPoint( ), gmsLRefPointX( ), gmsLRefPointY( ), gmsQRefPoint( ), gmsQRefPointX( ), gmsQRefPointY( ), gmsQDefRefPt( )

SYNTAX

intgmsRefPoint (obj, point)

id obj;idPoint point;

intgmsRefPointX (obj, rpx)

id obj;int rpx;

intgmsRefPointY (obj, rpy)

id obj;int rpy;

intgmsLRefPoint (objlist, point)


intgmsLRefPointX (objlist, rpx)

idLinkRef objlist;int rpx;


Reference Point

intgmsLRefPointY (objlist, rpy)

idLinkRef objlist;int rpy;

idPointgmsQRefPoint (obj)

id obj;

intgmsQRefPointX (obj)

id obj;

intgmsQRefPointY (obj)

id obj;

idPointgmsQDefRefPt (obj)

id obj;

DESCRIPTIONThese functions set an object’s or a List of objects’ Reference Points, orreturn the Reference Point. The Reference Point is used during objecttransformations, such as scaling and rotating.

Setting the Reference Point to nil clears the current Reference Point, sothat the default Point is used. The user should always free the Pointgiven as an argument in setting the Reference Point after use.

The default Reference Point for an object is the center of that object’sextent. The current Reference Point can be returned bygmsQRefPoint( ), and the default Reference Point withgmsQDefRefPt( ). The returned Point should be freed with pntFree( ).

The gmsQRefPointX( ) function returns the x Internal Coordinate for thecurrent Reference Point, while the gmsQRefPointY( ) function returnsthe y Internal Coordinate for the current Reference Point.

Functions that take integer coordinates as arguments must first convertWorld Coordinate arguments (double values) into internal integerrepresentation using the gmsWValue( ) function.


Reference Point

EXAMPLEThe gmsRefPointX( ) function requires a World Coordinate:

gmsRefPointX(obj, gmsWValue(10.0));

EXAMPLETo retrieve a valid Reference Point for an object:

ref_point = gmsQRefPoint(obj);if (!ref_point)

ref_point = gmsQDefRefPt(obj);

SEE ALSOgmsRRotZ( ), gmsARotZ( ), gmsRScale( ), gmsAScale( ), gmsWValue( ), gmsWCoordX( )

SL-GML COMMANDname refpoint


Relative move

Relative move

SUMMARY

apply a relative move transformation

NAME

gmsRMove2( ), gmsLRMove2( ), gmsMRMove2( ), gmsRMoveX( ),gmsLRMoveX( ), gmsMRMoveX( ), gmsRMoveY( ), gmsLRMoveY( ),gmsMRMoveY( ), gmsCRMv2( )

SYNTAX

intgmsRMove2 (obj, point)

id obj;idPoint point;

intgmsLRMove2 (objlist, point)


intgmsMRMove2 (point)

idPoint point;

intgmsRMoveX (obj, mx)

id obj;int mx;

intgmsLRMoveX (objlist, mx)

idLinkRef objlist;int mx;


Relative move

intgmsMRMoveX (mx)

int mx;

intgmsRMoveY (obj, my)

id obj;int my;

intgmsLRMoveY (objlist, my)

idLinkRef objlist;int my;

intgmsMRMoveY (my)

int my;

intgmsCRMv2 (point)

idPoint point;

DESCRIPTIONThese functions define a relative move transformation. Thetransformation matrix is combined with any existing matrix. ThegmsRMove2( ) function operates on an individual object, while thegmsLRMove2( ) function operates on a List of objects. The object(s)is first erased, the transformation applied, then the object(s) is redrawn.The erase and redisplay transformations immediately occur only ifSL-GMS is in Immediate Update Mode.

The point argument contains the distance that the objects are to betranslated. It must be a pointer to a Point object. If a gmsRMoveX( )function is used, the y coordinate is set to 0. For gmsRMoveY( ), the xcoordinate is set to 0.

The gmsCRMv2( ) function applies to the creation of future Clones orInstances. The gmsMRMove2( ) function sets a modal offsettransformation which applies to all objects subsequently created.


Relative move


EXAMPLEgmsRMoveY(obj, gmsWValue(10.0));

SL-GML COMMANDSname offset x y

name rmove x y

name rmovex x

name rmovey y

moffset x y


Relative rotation

Relative rotation

SUMMARY

apply a relative Z-axis rotation transformation

NAMEgmsRRotZ( ), gmsLRRotZ( ), gmsCRRotz( ), gmsMRRotZ( )

SYNTAX

intgmsRRotZ (obj, angle)

id obj;double angle;

intgmsLRRotZ (objlist, angle)

idLinkRef objlist;double angle;

intgmsCRRotz (point, angle)


intgmsMRRotZ (point, angle)


DESCRIPTIONThese functions define a relative Z-axis rotation transformation. Thetransformation matrix is combined with any existing matrix. ThegmsRRotZ( ) function operates on an individual object, while thegmsLRRotZ( ) function operates on a List of objects. The object(s) isfirst erased, the transformation applied, then the object(s) is redrawn.The erase and redisplay transformations occur automatically only ifSL-GMS is in Immediate Update Mode.


Relative rotation

Individual objects or Lists of objects are rotated around the referencepoint set with gmsRefPoint( ). The point argument used withgmsMRRotZ( ) is the center of rotation and must be a Point object.The rotation angle is a double argument specified as degrees to rotatecounterclockwise.

The gmsCRRotZ( ) function applies to the creation of future Clones orInstances. The gmsMRRotZ( ) function sets a modal rotationtransformation which applies to all objects subsequently created.

SL-GML COMMANDSname rrotz angle

mrotz x y angle


Relative scale

Relative scale

SUMMARY

apply a relative 2D scale transformation

NAME

gmsRScale( ), gmsLRScale( ), gmsMRScale( ), gmsRScaleX( ), gmsLRScaleX( ), gmsMRScaleX( ), gmsRScaleY( ), gmsLRScaleY( ), gmsMRScaleY( ), gmsCRSca2( )

SYNTAX

intgmsRScale (obj, sxy)

id obj;double sxy;

intgmsLRScale (objlist, sxy)

idLinkRef objlist;double sxy;

intgmsMRScale (point, sx, sy)


intgmsRScaleX (obj, sx)

id objdouble sx;

intgmsLRScaleX (objlist, sx)

idLinkRef objlist;double sx;


Relative scale

intgmsMRScaleX (point, sx)

idPoint point;double sx;

intgmsRScaleY (obj, sy)

id obj;double sy;

intgmsLRScaleY (objlist, sy)

idLinkRef objlist;double sy;

intgmsMRScaleY (point, sy)

idPoint point;double sy;

intgmsCRSca2 (point, sx, sy)


DESCRIPTION These functions define a relative 2D scale transformation. Thetransformation matrix is combined with any existing matrix. ThegmsRScale( ) function operates on an individual object, while thegmsLRScale( ) function operates on a List of objects. The object(s) isfirst erased, the transformation applied, then the object(s) is redrawn.The erase and redisplay transformations occur only if SL-GMS is inImmediate Update Mode.

Objects, or Lists of objects, are scaled around the Reference Point setby the gmsRefPoint( ) function. The point argument is the center ofscaling and must be a pointer to a Point object. The x and y scalefactors must be double arguments. If gmsRScaleX( ) is used, the y


Relative scale

scale factor is set to 1.0. For gmsRScaleY( ), the x scale factor is setto 1.0.


The gmsMRScale( ) function sets a modal scale transformation whichapplies to all objects subsequently created. The gmsCRSca2( )function applies to the creation of future Clones or Instances.

SL-GML COMMANDSname scale x y sx sy

name rscale sx sy

name rscalex sx

name rscaley sy

mscale x y sx sy


Relative transformation


SUMMARY

apply relative transformation to an object

NAME

gmsRTran( ), gmsLRTran( ), gmsCRTran( ), gmsMRTran( )

SYNTAX

intgmsRTran (obj, tran)

id obj;idMatrix tran;

intgmsLRTran (objlist, tran)

idLinkRef objlist;idMatrix tran;

intgmsCRTran (tran)

idMatrix tran;

intgmsMRTran (tran)

idMatrix tran;



DESCRIPTIONThese functions apply a relative transformation matrix to an object orList of objects. The transformation matrix is combined with anyexisting matrix. The gmsATran( ) function sets the transformationabsolutely.

The gmsRTran( ) function operates on an individual object, while thegmsLRTran( ) function operates on a List of objects. The object(s) isfirst erased, the transformation applied, then the object(s) is redrawn.The erase and redisplay transformations occur only if SL-GMS is inImmediate Update Mode, otherwise the transformation is apparent thenext time the display is updated.

The gmsCRTran( ) function applies to the creation of future Clones orInstances. The gmsMRTran( ) function sets the modal transformationthat applies to all objects subsequently created. These four functionsrequire a 2D transformation Matrix object as an argument (idMatrix).

SEE ALSOgmsATran( ), gmsXTran( )

SL-GML COMMAND[name] tran d0 d1 d2 d3 d4 d5


Reset transformation


SUMMARY

reset transformation on an object

NAME

gmsTran0( ), gmsLTran0( ), gmsCTr0( ), gmsMTran0( )

SYNTAX

intgmsTran0 (obj)

id obj;

intgmsLTran0 (objlist)

idLinkRef objlist;

intgmsCTr0( )

intgmsMTran0( )



DESCRIPTIONThese functions reset transformations that have been applied toobjects. The gmsTran0( ) function operates on an individual object,while the gmsLTran0( ) function operates on a List of objects. Theobject(s) is first erased, the transformation applied, then the object(s) isredrawn. The erase and redisplay transformations occur only ifSL-GMS is in Immediate Update Mode.

The gmsCTr0( ) function applies to the creation of future Clones orInstances. The gmsMTran0( ) function sets a modal transformationwhich applies to all objects subsequently created.

SL-GML COMMANDS[name] tran0

mtran0


Sector object

Sector object

SUMMARY

create a Sector object

NAME

gmsSect( ), gmsSec2( ), gmsSec3( ), gmsFSec( ), gmsFSec2( ), gmsFSec3( )

SYNTAX

idgmsSect (name, center, radius, start, length)

char *name;idPoint center;double radius;double start;double length;

idgmsSec2 (name, points)


idgmsSec3 (name, points)


idgmsFSect (name, center, radius, start, length)

char *name;idPoint center;double radius;double start;double length;


Sector object

idgmsFSec2 (name, points)


idgmsFSec3 (name, points)


DESCRIPTIONThe gmsSec( ) function is used to create a Sector object given a centerPoint, radius, start angle, and arc length. The Sector object is createdwith the current attributes. The radius argument should be given inWorld Coordinates and is multiplied by the World Coordinate ScaleFactor. Angles (and the arc) are given in degrees, and arcs are drawnin a counterclockwise direction.

The gmsSec2( ) function creates a Sector object given a center Pointand two Points which are on the radius. The Points must be passed ina Point List. The second Point on the arc (the third in the List) will beadjusted to be on the radius if it is not already.

The gmsSec3( ) function creates a Sector object given three Points.The Points must be passed in a Point List and should be created withthe gmsWPXY( ) function. The Points must not be collinear, otherwisea Sector cannot be created. Although the Sector created containsPoints which are passed to the function, the Sector object isrepresented as a center Point and two end Points which are determinedfrom the three Points given.

The gmsFSec( ), gmsFSec2( ), and gmsSec3( ) functions are used inthe same manner as their counterparts without the "F", but the Sectorsproduced are filled.

The name argument is optional and is the name that is assigned to theobject when it is added to the current Model. The current edgeattributes are applied to the object when it is created.


Sector object

SEE ALSOgmsCWFlag( )

SL-GML COMMANDS[name:] sect x y radius start length

[name:] sec2 x y x y x y

[name:] sec3 x y x y x y

[name:] fsect x y radius start length

[name:] fsec2 x y x y x y

[name:] fsec3 x y x y x y


Sectors, Pies, Splines — miscellaneous


SUMMARY

change the arc length or starting angle for Sectors and Pies; set theclockwise flag on Sectors, Pies, or Splines

NAME

gmsArcLength( ), gmsLArcLength( ), gmsQArcLength( ), gmsStartAngle( ), gmsLStartAngle( ), gmsQStartAngle( ), gmsCWFlag( )

SYNTAX

intgmsArcLength (obj, arclength)

id obj;double arclength;

intgmsLArcLength (objlist, arclength)

idLinkRef objlist;double arclength;

doublegmsQArcLength (obj)

id obj;

intgmsStartAngle (obj, startangle)

id obj;double startangle;

intgmsLStartAngle (objlist, startangle)

idLinkRef objlist;double startangle;



doublegmsQStartAngle (obj)

id obj;

intgmsCWFlag (obj, flag)

id obj;int flag;

DESCRIPTIONThe gmsArcLength( ) and gmsStartAngle( ) functions change the arclength and starting angle for Sector and Pie objects. Both arc lengthand starting angle are measured in degrees, starting with 0 degrees onthe positive x axis, and moving counterclockwise with positive angles.

The gmsLArcLength( ) and gmsLStartAngle( ) functions change thearc length and starting angle for a List of Sector and Pie objects.

The gmsQArcLength( ) and gmsQStartAngle( ) functions query thearc length or start angle for Sector or Pie objects. The number ofdegrees from the positive x axis is returned.

The gmsCWFlag( ) function sets the clockwise flag on Sectors,Splines, or Pies, indicating they should be drawn in a clockwisedirection.

SL-GML COMMANDSname startangle real

name arclength real


Set transformation

Set transformation

SUMMARY

set the transformation for an object

NAME

gmsATran( ), gmsLATran( ), gmsCATran( ), gmsMATran( ), gmsTran( )

SYNTAX

intgmsATran (obj, tran)

id obj;idMatrix tran;

intgmsLATran (objlist, tran)

idLinkRef objlist;idMatrix tran;

intgmsCATran (tran)

idMatrix tran;

intgmsMATran (tran)

idMatrix tran;

intgmsTran (object, tran)

id object;idMatrix tran;

DESCRIPTIONThese functions set an absolute transformation matrix for an object orList of objects. The transformation matrix replaces any existing matrix.


Set transformation

The gmsRTran( ) function combines the given transformation matrixwith any existing transformation matrix.

The gmsATran( ) function operates on an individual object, while thegmsLATran( ) function operates on a List of objects. The object(s) isfirst erased, the transformation applied, and the

object(s) is redrawn. The erase and redisplay transformations occuronly if SL-GMS is in Immediate Update Mode, otherwise thetransformation is apparent the next time the display is updated.

The gmsCATran( ) function applies to the creation of future Clones orInstances. The gmsMATran( ) function sets the modal transformationthat applies to all objects subsequently created. These four functionsrequire a 2D transformation Matrix object as an argument (idMatrix).

The gmsTran( ) function transforms the object by the giventransformation matrix.

SEE ALSOgmsRTran( )

SL-GML COMMAND[name] tran d0 d1 d2 d3 d4 d5


Setup, quit, close SL-GMS


SUMMARY

setup, quit, and close the SL-GMS system

NAME

gmsSetup( ), gmsQuit( ), gmsClose( ), gmsExit( ), gmsYesFlag( )

SYNTAX

intgmsSetup( )

intgmsQuit( )

intgmsClose( )

intgmsExit( )

intgmsYesFlag (flag)

int flag;

DESCRIPTIONThese functions operate at the outermost level of SL-GMS. ThegmsSetup( ) function must be executed before any other SL-GMSfunction can be used. An implicit gmsProject( ) function is performedby gmsSetup( ) to initialize all modal attributes to their default values.By default, SL-GMS starts with a World Coordinate Scale Factor of0x10000. The setting of 0x10000 may be changed with thegmsWCScale( ) function. The gmsSetup( ) function is called bygmsMainInit( ).

The gmsQuit( ) function is called by the SL-GML interpreter when thequit command is entered. The gmsClose( ) function is called by



gmsQuit( ) and provides a graceful closing but does not query the userfirst, as does gmsQuit( ).

The gmsExit( ) function causes SL-GMS to close allWorkstation/Windows and terminate execution without querying theuser. The program is terminated with the exit( ) system command.

The gmsYesFlag( ) function sets the query flag that SL-GMS checkswhen prompting for a yes or no response. When the flag is set to 0(the default), SL-GMS waits for a response before it overwrites existingModels and quits. When the flag is set to 1, the answer is alwaysassumed to be yes. This flag is set by using the -y command-lineoption when invoking SL-DRAW2, SL-DRAW, or SL-GML.

SEE ALSOgmsWCScale( ), gmsProject( )

SL-GML COMMANDSproject

coordscale real

quit


SL-GMS Installation Directory — query

SL-GMS Installation Directory — query

SUMMARY

query the SL-GMS installation directory

NAME

gmsQGmsHome( )

SYNTAX

char *gmsQGmsHome( )

DESCRIPTIONThe gmsQGmsHome( ) function returns the directory where SL-GMSis installed as contained in the GMS_HOME environment variable (Unixand 32-bit Windows), or the Registry (32-bit Windows only).


SL-GMS Libraries — version, configuration, date


SUMMARY

query the SL-GMS version number, version date, and configurationnumber; compare a SL-GMS version number with the one in theSL-GMS Libraries being used.

NAME

gmsQVersion( ), gmsQReleaseDate( ), gmsQConfig( ), gmsCompareVersion( )

SYNTAX

char *gmsQVersion( )

char *gmsQReleaseDate( )

char *gmsQConfig( )

intgmsCompareVersion (version)

char *version;



DESCRIPTIONThe gmsQVersion( ), gmsQReleaseDate( ), and gmsQConfig( )functions take no arguments and return a character string containingthe appropriate information. The strings returned from these functionsare in the following form:

The gmsCompareVersion( ) function allows applications to comparean SL-GMS version number with the version in theSL-GMS libraries being used with the application to determine if theSL-GMS libraries are of an identical, lower, or higher version numberthan the specified version number. The specified version number ispassed in as a string.

The gmsCompareVersion( ) function returns 1 if the SL-GMS librariesare a higher version than the specified version number, it returns -1 ifthey are a lower version, and it returns 0 if they are the identicalversion.

NOTE: The specified version number need not be a completeSL-GMS version number for the comparison to work; however,if a shorter string than a complete SL-GMS version number isspecified, the return value will reflect the comparison up to thenumber of characters in the specified SL-GMS versionnumber.

gmsQVersion( ) 5.3a

gmsQReleaseDate( )

28 February 1995

gmsQConfig( ) 53a1_250228



EXAMPLEThe following table gives the return values fromgmsCompareVersion( ) for various specified SL-GMS version numberswhen used with SL-GMS libraries of SL-GMS version number "5.3a":

Specified SL-GMS Version

NumberReturn Value

4 1

5 1

5. 1

5.3 1

5.3a 0

5.3b -1

5.4 -1

6 -1

6. -1


Spline object

Spline object

SUMMARY

create a Spline or Closed Spline object; create a List of Spline orClosed Spline objects

NAME

gmsSpline( ), gmsCSpline( ), gmsLMkSpline( )

SYNTAX

idgmsSpline (name, points)


idgmsCSpline (name, points)


idLinkRefgmsLMkSpline (objlist)

idLinkRef objlist;

DESCRIPTIONThe gmsSpline( ) function creates a curved line (a Spline object) whichtakes its shape from the given Point List. In SL-GMS, Spline objectsconsist of a series of Bezier splines, each with two control Points. ThegmsCSpline( ) function creates a Closed Spline from the given PointList, connecting the first and last Points if necessary. A Spline orClosed Spline is guaranteed to pass through all given Points.

The name argument is optional and is the name assigned to the objectwhen it is added to the current Model. The current edge attributes areapplied to the object when it is created. The stress attribute appliesonly to Splines or Closed Splines and affects whether the curve issharply or flatly curved to fit the Points.


Spline object

The gmsLMkSpline( ) function creates Spline or Closed Spline objectsfrom a List of Polyline or Closed Polyline objects. Polylines and ClosedPolylines may be mixed on the List; these objects are freed after theirPoint Lists have been used to create the new Spline or Closed Splineobject. A List of the new objects is returned and each object is addedto the current Model.

SEE ALSOgmsStress( ), gmsCWFlag( )

SL-GML COMMANDS[name:] spline x y x y ...

[name:] cspline x y x y ...


State — attributes


SUMMARY

set a State Instance’s attribute flags

NAME

gmsStClearFlag( ), gmsStFreeFlag( ), gmsStGismoFlag( ),gmsStPopFlag( ), gmsStVisFlag( ), gmsStDatFlag( ), gmsStD1Flag( ), gmsStAutoDeactFlag( ), gmsStUpdFlag( )

SYNTAX

intgmsStClearFlag (state, clearflag)

id state; /* State Instance */int clearflag; /* clearflag = G_ON/G_OFF */

intgmsStFreeFlag (state, freeflag)

id state; /* State Instance */int freeflag; /* freeflag = G_ON/G_OFF */

intgmsStGismoFlag (state, gismoflag)

id state; /* State Instance */int gismoflag; /* gismoflag = G_ON/G_OFF */

intgmsStPopFlag (state, popflag)

id state; /* State Instance */int popflag; /* popflag = G_ON/G_OFF */

intgmsStVisFlag (state, visflag)

id state; /* State Instance */int visflag; /* visflag = G_ON/G_OFF */



intgmsStDatFlag (state, datflag)

id state; /* State Instance */int datflag; /* datflag = G_ON/G_OFF */

intgmsStD1Flag (state, d1flag)

id state; /* State Instance */int d1flag; /* d1flag = G_ON/G_OFF */

intgmsStAutoDeactFlag (state, autodeactflag)

id state; /* State Instance */int autodeactflag;/* autodeactflag = G_ON/G_OFF */

intgmsStUpdFlag (state, updflag)

id state; /* State Instance */int updflag; /* updflag = G_ON/G_OFF */

DESCRIPTIONThe gmsStClearFlag( ) function sets the state’s clearflag to G_ON orG_OFF. If the clearflag is set to G_ON, clearing of the StateInstance’s View occurs before displaying a Model. The functionreturns 1 for success, 0 for failure. The SL-GMS default for clearflag isG_ON.

The gmsStFreeFlag( ) function turns the state’s freeflag to G_ON orG_OFF. If the freeflag is set to G_ON, the State Instance is freedwhen it is deactivated. The function returns 1 for success, 0 for failure.The SL-GMS default for freeflag is G_OFF.

The gmsStGismoFlag( ) function sets the state’s gismoflag to G_ONor G_OFF. If the gismoflag is set to G_ON and an input Event isreceived, this function causes SL-SMS to search the Models associatedwith the State Instance to determine if an object was selected and if ithas input dynamics (i.e., if it is a GISMO). If it is a GISMO, theappropriate GISMO Action Function is called and no more processing isdone on the Event. The SL-GMS default for gismoflag is G_ON.



If the gismoflag is set to G_OFF, Events are passed directly to theappropriate Event-handler. The function returns 1 for success, 0 forfailure.

The gmsStPopFlag( ) function turns the state’s popflag to G_ON orG_OFF. If the popflag is set to G_ON, SL-SMS uses gmsPopOn( ) tosave a raster image when the State Instance is activated andgmsPopOff( ) to restore a raster image when the State Instance isdeactivated. If the popflag is set to G_OFF, the entire View previouslyobscured is redrawn upon activation. The function returns 1 forsuccess, 0 for failure. The SL-GMS default for popflag is G_OFF.

The gmsStVisFlag( ) function turns the state’s visflag to G_ON orG_OFF. If the visflag is set to G_ON, SL-SMS leaves the StateInstance’s Superstate’s Models visible1 when the State

Instance is activated. If the visflag is set to G_OFF, the Superstate’sModels are made invisible upon activation. The function returns 1 forsuccess, 0 for failure. The SL-GMS default for visflag is G_OFF.

The gmsStDatFlag( ) function turns the state’s datflag to G_ON orG_OFF. If the datflag is set to G_ON, SL-SMS opens a Datasourcefile (".dat" file) when the State is activated. The function returns 1 forsuccess, 0 for failure. The SL-GMS default for datflag is G_OFF.

The gmsStD1Flag( ) function turns the state’s d1flag to G_ON orG_OFF. If the d1flag is set to G_ON, SL-SMS opens a Datasource file(".d1" file) when the State is activated. The function returns 1 forsuccess, 0 for failure. The SL-GMS default for d1flag is G_OFF. As ofthis release, this function is not yet implemented.

The gmsStAutoDeactFlag( ) function turns the state’s autodeactflagto G_ON or G_OFF. The autodeactflag controls the default behaviorof the right mouse button. If the autodeactflag is set to G_ON,clicking the right mouse button (button 3) causes the State Instance tobe deactivated. Automatic deactivation upon right mouse button clickoccurs even if an independent Event-handler was defined. Thefunction returns 1 for success, 0 for failure. The SL-GMS default forautodeactflag is G_ON.

The gmsStUpdFlag( ) function turns the state’s updflag to G_ON orG_OFF. If the updflag is set to G_ON, SL-SMS automatically executes

1. Dynamic updates occur only for objects which are marked as visible.



the State’s update method each time a timer Event is received. Thefunction returns 1 for success, 0 for failure. The SL-GMS default forupdflag is G_ON.

The gmsStUpdFlag( ) function has limited effect. Although it properlycontrols whether update messages are sent to a State and all of itsSubstates, any changes in variables elsewhere in an SL-GMSapplication cause the Models in the State to have their dynamicsupdated. The way to prevent the Models from having their dynamicsupdated is by not calling gmsVarChanged( ) on the driving variables,or by making the Model invisible.

SEE ALSOThe chapter entitled The State Management System in the SL-GMSReference Manual


State — class

State — class

SUMMARY

create, install, and add methods to a State class

NAME

gmsStateClass( ), gmsClassAddMethod( ), gmsStClassInstall( )

SYNTAX

idgmsStateClass (name, size)

char *name; /* name of the State class */int size; /* size of the State class */

intgmsClassAddMethod (class, methname, methaddr, fctntype,

argtypes)id class; /* State class created by

gmsStateClass( ) */char *methname; /* name of method */void (*methaddr)( );/* address of method */int fctntype; /* return type of method */long argtypes; /* not used */

intgmsStClassInstall (class)

id class; /* State class created withgmsStateClass( ) */

DESCRIPTIONThe gmsStateClass( ) function creates a new State class namedname, giving it a default set of attributes. The function returns apointer to the new State class object created. If size is 0, a newgeneric State class is created.


State — class

NOTE: The size of a State class cannot be larger than 32767 bytes

The gmsClassAddMethod( ) function adds a method to a State class’set of methods. The function returns 1 for success, 0 for failure. Validcodes for fctntype are G_INTEGER and G_POINTER. argtypes is notused and should be passed with a 0.

The gmsStClassInstall( ) function installs a State class created withthe gmsStateClass( ) function, connecting it to other SL-SMS objectsand making it available for instancing. The function returns 1 forsuccess, 0 for failure.

NOTE: In SL-GMS version 5.x, checking the argument types is notimplemented.

EXAMPLEBelow is a sample code fragment which uses gmsClassAddMethod( )to add the loc_press method to a customized State:

static intloc_press (state, event)

id state;id event;

{printf("... <loc_press> in state: %s (%d,%d)\n",

gmsQStName(state),pntX(gmsQEvPoint(event)),pntY(gmsQEvPoint(event)));

return 1;}...intcustom_state_initialize ( ){

static id stclass = 0;

/* should only initialize once! */if (stclass) return 0;


State — class

/* create custom State class object*/

stclass = gmsStateClass("CustomState",sizeof(struct CLASS));


/* add method(s) for handlingEvents to this State class */

gmsClassAddMethod(stclass, "loc_press", loc_press,G_INTEGER, 0);

/* install State class */gmsStClassInstall(stclass);return 1;

}


State — initialization


SUMMARY

initialize States

NAME

gmsInitStates( ), gmsInitStatesOnWs( ), gmsStLocMotionEnable( )

SYNTAX

intgmsInitStates( )

intgmsInitStatesOnWs (workst)

id workst;

intgmsStLocMotionEnable (state, flag)

id state; /* State Instance*/int flag; /* -1 (ON), 0 (OFF), or mask */

DESCRIPTIONThe Screen State Manager component of SL-SMS, explained in Thechapter entitled The State Management System of the SL-GMSReference Manual, is a module provided to manage a hierarchy ofscreen States. Use of the Screen State Manager module is optional,but its use practically eliminates the coding necessary to coordinatemapping and unmapping of dynamic screens, to handle Events, and toactivate Datasources. The functions described in this section are usedfor initialization of the Screen State Manager and the enabling of aState’s Locator motion Events.



The gmsInitStates( ) function is called once from inside a user’s application initialization function to:

1. set up State callback functions (Event-handlers);

2. initialize several predefined States available to all appli-cations (the predefined States currently provided arescreen, datscreen, and popup); and

3. establish several predefined GISMO functions that canoperate on screen States (such asgms_screen_state_invoke( ), for example).

When gmsInitStates( ) is called, SL-SMS internally sets upEvent-handlers for 18 different Event types, using gmsWsEventFctn( );the Event-handlers dispatch Events to the appropriate State methods(for example, the Locator Event is dispatched to the loc_press( ) Statemethod).

When using the SL-SMS Event-handling mechanism (i.e., whengmsInitStates( ) is called) gmsWsEventFctn( ) should not be calledby the application program, since doing so interferes with SL-SMS’Event-handling capability.

NOTE: SL does not recommend the explicit setup of State callbackfunctions via gmsWsEventFctn( ); rather, the automaticsetup provided by the gmsInitStates( ) function should beutilized.

The gmsInitStatesOnWs( ) function is called whenever a newWorkstation is created after the call to gmsInitStates( ). ThegmsInitStatesOnWs( ) function sets up a set of 18 Event-handlers forthe new Workstation.

NOTE: The gmsInitStatesOnWs( ) function also sets the timerperiod to 0. Therefore, a call to gmsTimerPeriod( ) must bedone after a gmsInitStatesOnWs( ) call for timer periodsgreater than 0.

The gmsStLocMotionEnable( ) function enables Locator motionEvents for the Workstation of the specified State. Full generation of



Locator motion Events is enabled by using a flag value of -1, anddisabled with a value of 0. Alternatively, the user can use a maskcontaining the Event modifiers that must be true in order to report anEvent. For example, the default flag value used by SL-GMS isG_LOC_BUTTON_LEFT, which means that Locator motion Events areenabled only when a LOC_PRESS Event is received from the leftmouse button, and disabled upon LOC_RELEASE. The defaultbehavior eliminates motion Events while moving the mouse without thebutton held down.

The valid values for the flag argument are provided in the followingtable.

The section

MODIFIER KEY CODESin the "gmscodes.h" file in the lib directory, contains a complete list ofmodifier codes.

The gmsStLocMotionEnable( ) function must be called after a State isactivated.

EXAMPLEgmsStLocMotionEnable(state,

G_LOC_BUTTON_MIDDLE|G_CONTROL KEY);

In the example above, Locator motion Events are enabled when themiddle mouse button and the keyboard control key are depressedsimultaneously. By default, Locator motion Events were enabled withthe mask G_LOC_BUTTON_LEFT.

SEE ALSOgmsWsEventFctn( )

Value Description 0 Locator motion Events disabledmask Locator motion Events enabled

when all modifiers in mask are on-1 Locator motion Events always

enabled



gmsbasic on-line example


State — Instance

State — Instance

SUMMARY

create, activate, and modify State Instances

NAME

gmsStateInst( ), gmsStActivate( ), gmsStDeactivate( ), gmsStWorkstName( ), gmsStViewName( ), gmsStAddModelName( ), gmsStClrModelNames( ), gmsStTextEditObj( ), gmsStTextEditObjName( )

SYNTAX

idgmsStateInst (instname, classname)

char *instname; /* name of State Instance to becreated */

char *classname;/* name of State class */

intgmsStActivate (state, superstate)

id state; /* State Instance */id superstate; /* other State Instance */

intgmsStDeactivate (state)

id state; /* State Instance */

intgmsStWorkstName (state, name)

id state; /* State Instance */char *name; /* name of a Workstation */

intgmsStViewName (state, name)

id state; /* State Instance */char *name; /* name of a View */


State — Instance

intgmsStAddModelName (state, name)

id state; /* State Instance */char *name; /* name of a Model */

intgmsStClrModelNames (state)


intgmsStTextEditObj (state, textobj, maxchars,promptstring, initstring, dispatch_mode)

id state; /* State Instance */id textobj; /* Text object */int maxchars; /* max chars to display */char *promptstring;/* prompt string */char *initstring;/* initial string to display with

prompt */int dispatch_mode;/* dispatch_mode =

G_MULTI_EVENT/G_ONE_SHOT/G_ONE_SHOT_CLEAR */

intgmsStTextEditObjName(state,textobjname, maxchars,promptstring, initstring, dispatch_mode)

id state; /* State Instance */char *textobjname;/* name of a Text object */int maxchars; /* max chars to display */char *promptstring;/* prompt string */char *initstring;/* initial string to display with

prompt*/int dispatch_mode;/* dispatch_mode =


DESCRIPTIONThe gmsStateInst( ) function creates an Instance of a State Class.After an Instance is created, it may be activated by callinggmsStActivate( ). If no classname variable is supplied, an Instance


State — Instance

of the generic State Class is created. If no instname variable issupplied, the name "*" is given to the Instance.

Creating State Instances can use a State Class exemplar. Theexemplar is a single predefined State Instance which is associated withthe State class. Creation of State Instances of that class is done bycloning the State class exemplar. Cloning the exemplar provides amechanism whereby default attributes may be established for a StateClass and assigned automatically whenever an Instance of that class iscreated.

The exemplar State Instance is usually defined during the initialize( )function for a particular State class. This is done by simply calling thegmsStateInst( ) function and assigning instame to be the same asclassname. The exemplar does not have to be defined; it is optional.Nor is the exemplar ever activated; it is simply used as a template forstoring default attributes.

Each time a subsequent gmsStateInst( ) function call is made to createan Instance of the State class, it first looks to see if the exemplar can befound. If so, the new State Instance is created by cloning theexemplar; if not, a simple Instance is created with the standard defaultattributes.

The process of cloning the exemplar to create a new State Instanceinvolves creating a simple Instance and then copying all the standardState attributes, such as freeflag, clearflag, and so on.

The names of Models and Views are copied; pointers are not copied.Only the attributes of the standard State object are copied; all "custom"State fields are set to 0.

The State class can be defined so that additional State fields are copiedto the new Instance by providing a copyfrom method. The method isinvoked during the cloning process to permit the class to copy otherState fields.

This method is defined as follows:

static intcopy_from (state1, state2)

idCLASS state1, state2;{

state1->customfield = state2->customfield;


State — Instance

return 1;}

Any necessary information may be copied from the exemplar in thismanner in a custom copyfrom method.

The gmsStActivate( ) function attaches the State Instance, state, toanother State Instance, superstate, by adding it to superstate’s List ofSubStates. The function installs the State Instance in the tree of StateInstances. If no superstate argument is supplied (superstate == nil),this State Instance is made the top-level State Instance. In addition, a"tree_changed" message is sent to the Top State of an application. TheTop State can use this tree_changed method to provide an update tothe application of the changes in the tree of active SL-SMS States. Thefunction returns 1 for success, 0 for failure. However, when a customactivate method has been written for a State, gmsStActivate( ) returns0 if the custom activate method returns -1, and returns 1 if the customactivate method returns any other value.

When a State is activated with gmsStActivate( ), SL-SMSautomatically calls gmsM2Get( ) and gmsDynInit( ) for each Model inthe State’s Models List that is not already in memory. The last Modelin the List is made the current Model in the Graphical ModelingHierarchy. Then all Models associated with the State are made visible.

The gmsStDeactivate( ) function removes state from the State tree. Ifthe State Instance’s freeflag is set to G_ON, the function causes theState Instance to be freed. If the state State Instance has anySubStates, they also are deactivated. In addition, a "tree_changed"message is sent to the Top State of an application. The Top State canuse this tree_changed method to provide an update to the applicationof the changes in the tree of active SL-SMS States.

The gmsStWorkstName( ) function associates a Workstation/Window(window-manager window) with a State Instance. TheWorkstation/Window may be created before or after this call, usinggmsWorkst( ). The gmsWorkst( ) function creates a namedWorkstation/Window object. Only one Workstation/Window may beassociated with a given State Instance.


State — Instance

The gmsStViewName( ) function associates a View with a State Instance.The View is created and named using the gmsView( ) function. Only oneView may be associated with a given State Instance. CallinggmsStViewName( ) and passing a NULL or empty string for the Viewname will clear the State’s internal View pointer. This should only be doneafter freeing the View:

gmsObjFree(gmsQStView(state));

gmsStViewName(state, NULL);

The gmsStAddModelName( ) function adds a Model to the List ofModels maintained by a State Instance. The Model need not be loaded(using the gmsMGet( ) function) — if necessary it is loaded when theState Instance is activated.

An unlimited number of Models may be added to the State Instance’sModel List by simply repeating the call to gmsStAddModelName( ).

When a Model is added to a State with a call togmsStAddModelName( ), any Substate of that State automaticallyrefers to the Model in its SuperState. The Model should not be addedto the Substate with another call to gmsStAddModelName( ).

The gmsStClrModelNames( ) function clears state’s entire List ofModels. This function does not free the Models; it only removes themfrom the State’s Model List.

The gmsStTextEditObj( ) function associates a TextEdit object withstate.

The TextEdit object is automatically activated at the same time theState Instance is activated, and remains active when the State Instanceis suspended (unless pre-empted by the TextEdit object of anotherState Instance, in which case it is restored as the active TextEdit objectupon reactivation).

When a State Instance is deactivated, the TextEdit object is forgotten,therefore, the gmsStTextEditObj( ) function is normally called in theState’s activate method to reset the object when the State is activated.To retain the TextEdit object, the gmsStTextEditObjName( ) function isused.


State — Instance

The gmsStTextEditObjName( ) function stores the name of a TextEditobject in a State Instance. The object name is not lost when the Stateis deactivated.

When the State is activated, SL-SMS finds the object namedtextobjname and makes it the active TextEdit object.

The object remains active when the State Instance is suspended(unless pre-empted by the TextEdit object of another State Instance, inwhich case it is restored as the active TextEdit object uponreactivation).

The valid values for dispatch_mode for the gmsStTextEditObj( ) andthe gmsStTextEditObjName( ) functions are as follows:

1. G_MULTI_EVENT — after a <RETURN> redisplaypromptstring and initstring;

2. G_ONE_SHOT — after a <RETURN> do not redisplaypromptstring and initstring (i.e., leave text that hasbeen entered);

3. G_ONE_SHOT_CLEAR — after a <RETURN> do notredisplay promptstring and clear initstring (i.e., cleartext that has been entered).

NOTE: The application program must create the desiredWorkstation/Window, create a View in it, and associate a StateInstance with that View.

SEE ALSOgmsWsTextEditObj( )


State — mark and reset


SUMMARY

mark and reset State stack

NAME

gmsStMark( ), gmsStReset( ), gmsStResetToMark( ), gmsStResetToTop( )

SYNTAX

intgmsStMark (state, flag)

id state; /* State Instance*/int flag; /* flag = G_ON/G_OFF */

intgmsStReset (state)

id state; /* State Instance*/

intgmsStResetToMark (state)

id state; /* State Instance*/

intgmsStResetToTop( )

DESCRIPTIONThe gmsStMark( ) function marks the given State Instance so that agmsStResetToMark( ) can be done. The function returns 1 forsuccess, 0 for failure.

The gmsStReset( ) function deactivates all of state’s SubStates. Thefunction returns 1 for success, 0 for failure.

The gmsStResetToMark( ) function deactivates state and allSuperStates up to the last State Instance marked with thegmsStMark( ) function. The marked State Instance is not deactivated.



However, all child States of the marked State Instance are deactivated.The function returns 1 for success, 0 for failure.

The gmsStResetToTop( ) function deactivates all State Instancesexcept for the top-level State Instance. The function returns 1 forsuccess, 0 for failure.


State — messaging

State — messaging

SUMMARY

send a message to a State Instance

NAME

gmsStStrMsg( ), gmsStPStrMsg( ), gmsStStrMsg1( ), gmsStPStrMsg1( ), gmsStStrMsg2( ), gmsStPStrMsg2( ), gmsStStrMsgNI( ), gmsStStrMsgNI1( ), gmsStStrMsgNI2( )

SYNTAX

intgmsStStrMsg (state, msgstr)

id state; /* State Instance */char *msgstr; /* message string */

void *gmsStPStrMsg (state, msgstr)


intgmsStStrMsg1 (state, msgstr, arg1)

id state; /* State Instance */char *msgstr; /* message string */long arg1; /* method argument */

void *gmsStPStrMsg1 (state, msgstr, arg1)



State — messaging

intgmsStStrMsg2 (state, msgstr, arg1, arg2)

id state; /* State Instance */char *msgstr; /* message string */long arg1, arg2;/* method arguments */

void *gmsStPStrMsg2 (state, msgstr, arg1, arg2)

id state; /* State Instance */char *msgstr; /* message string */long arg1, arg2; /* method arguments */

intgmsStStrMsgNI (state, msgstr)


intgmsStStrMsgNI1 (state, msgstr, arg1)


intgmsStStrMsgNI2 (state, msgstr, arg1, arg2)

id state; /* State Instance */char *msgstr; /* message string */long arg1, arg2;/* method arguments */

DESCRIPTIONThe gmsStStrMsg( ) function sends a message to a State Instance toinvoke the method specified by the string, msgstr (i.e., the functionregistered with the state’s class via a call to gmsClassAddMethod( ) ).If the State Instance does not recognize the message, it attempts tofind a "notrecognized" method.1 If the "notrecognized" method is found,it is invoked by passing it the state instance id and the name of themethod. Otherwise, the search is continued up the State tree. Thesearch for a method continues until a State containing the specified

1. "notrecognized" methods are discussed in the SL-GMS® Reference.


State — messaging

method is found, a "notrecognized" method is found, or the top state isencountered. The function return value is whatever the invokedmethod returns. If the method is not found and a "notrecognized"method is not found, a 0 is returned.

The gmsStPStrMsg( ) function sends a message to a State Instance,similar to the gmsStStrMsg( ) function. The difference is that thisfunction returns the pointer value returned by the message.

The gmsStStrMsg1( ) function sends a message to a State Instance,similar to the gmsStStrMsg( ) function, except that the method invokedwill be passed one argument. The function returns 1 for success, 0 forfailure.

The gmsStPStrMsg1( ) function sends a message to a State Instance,similar to the gmsStStrMsg( ) function. The difference is that themethod invoked will be passed one argument and this function returnsthe pointer value returned by the message.

The gmsStStrMsg2( ) function sends a message to a State Instance,similar to the gmsStStrMsg( ) function, except that the method invokedwill be passed two arguments. The function returns 1 for success, 0 forfailure.

The gmsStPStrMsg2( ) function sends a message to a State Instance,similar to the gmsStStrMsg( ) function. The difference is that themethod invoked will be passed two arguments and this function returnsthe pointer value returned by the message.

The gmsStStrMsgNI( ) function sends a message to a StateInstance. If the State Instance does not recognize the message, it isnot inherited from the SuperState. No attempt is made to look for a"notrecognized" method or to traverse the state’s tree hierarchy. Noarguments are passed with the message. The function returns 1 forsuccess, 0 for failure.

The gmsStStrMsgNI1( ) function sends a message to a State Instance,similar to the gmsStStrMsgNI( ) function, except that one argument ispassed with the message. The function returns 1 for success, 0 forfailure.

The gmsStStrMsgNI2( ) function sends a message to a State Instance,similar to the gmsStStrMsgNI( ) function, except that two arguments


State — messaging

are passed with the message. The function returns 1 for success, 0 forfailure.

SEE ALSOThe appendix entitled SL-GMS System Organization in the SL-GMSAdvanced Tutorial


State — miscellaneous


SUMMARY

manipulate State classes and Instances

NAME

gmsSt30Flag( ), gmsStM2Flag( ), gmsStClassFindByName( ), gmsStDebugFlag( ), gmsStEventFctn( ), gmsStFindByName( ), gmsStWasFreed( )

SYNTAX

intgmsSt30Flag (state, flag)

id state; /* State Instance*/int flag; /* flag = G_ON/G_OFF */

intgmsStM2Flag (state, flag)

id state; /* State Instance*/int flag; /* G_ON = search for ".m2" then ".m1"

G_OFF = search for ".m1" then".m2" */

idgmsStClassFindByName (name)

char *name; /* name of a State Class */

intgmsStDebugFlag (debugflag)

int debugflag; /* debug flag = 1, 2, 3 */

intgmsStEventFctn (fctn)

int (*fctn)( ); /* Event-handler */



idgmsStFindByName (instname)

char *instname; /* name of a State Instance */

intgmsStWasFreed (freedmodel)

id freedmodel;

DESCRIPTIONThe gmsSt30Flag( ) function sets the version 3.0 compatibility flag toG_ON or G_OFF. The version 3.0 compatibility flag provides backwardcompatibility. With gmsSt30Flag( ) set to G_ON, the State Instance isnot passed as the first argument to State methods, as in SL-GMSversions 3.0 and above. The function returns 1 for success, 0 forfailure.

The gmsStM2Flag( ) function may be used to change ".m2"/".m1"Model search order. Under SL-SMS, ".m2" Models are searched forfirst in a directory and then ".m1" Models are searched for.

The gmsStClassFindByName( ) function returns a pointer to a Stateclass given its name.

The gmsStDebugFlag( ) function, a debugging utility, provides variouslevels of internal SL-SMS message tracing by setting the state_debugflag. The flag set to 0 turns tracing off. If the flag is greater than orequal to 1, the SL-SMS functions gmsStActivate( ),gmsStDeactivate( ), gmsStReset( ), gmsStResetToMark( ),gmsStResetToTop( ) are traced. Tracing of these functions can behelpful since they affect the Screen Management Hierarchy. If the flagis greater than or equal to 2, in addition to the information describedabove, string messages sent to States are printed. The state_debugflag set to 3 includes Level 1 and 2 information and adds Event tracing.

The gmsStEventFctn( ) function establishes an Event-handler thatintercepts all Events before they reach the State Event-handlersestablished via gmsInitStates( ). This function receives an Eventbefore any of the Event-handler functions. The Event-handler functionpointed to by fctn must take a single argument, id event, and return anint. A return value of 0 indicates the Event was absorbed by thecallback. A return value of 1 tells the Screen State Manager tocontinue processing the Event in the usual manner.



The gmsStFindByName( ) function returns a pointer to a StateInstance given its name.

The gmsStWasFreed( ) function informs all State Instances that aModel was freed (using the gmsObjFree( ) function). This functionshould be called whenever a Model managed by a State Instance isfreed so that the address of the Model is cleared in the State Instance’sModel List. Upon activation or reactivation, SL-SMS reloads theModel. If SL-SMS is not informed about the freed Model by using thisfunction, SL-SMS tries to display the Model (using an old address) uponactivation or reactivation of the State Instance, resulting in an error.The function returns 1 for success, 0 for failure.

SEE ALSOgmsInitStatesOnWs( )


State — query

State — query

SUMMARY

query a State for its name, Model, View, Workstation/Window, and soon; query all active States

NAME

gmsQAllStates( ), gmsQStClassName( ), gmsQStCurState( ), gmsQStEvState( ), gmsQStIsActive( ), gmsQStModel( ), gmsQStModelList( ), gmsQStModelName( ), gmsQStName( ), gmsQStStrMsgState( ), gmsQStSubStates( ), gmsQStSuperState( ), gmsQStTextEditObj( ), gmsQStTopState( ), gmsQStView( ), gmsQStViewName( ), gmsQStWorkst( ), gmsQStWorkstName( )

SYNTAX

idLinkRefgmsQAllStates( )

char *gmsQStClassName (state)


idgmsQStCurState( )

idgmsQStEvState( )

intgmsQStIsActive (state)


idgmsQStModel (state)



State — query

idLinkRefgmsQStModelList (state)


char *gmsQStModelName (state)


char *gmsQStName (state)


idgmsQStStrMsgState( )

idLinkRefgmsQStSubStates (state)


idgmsQStSuperState (state)


idgmsQStTextEditObj (state)


idgmsQStTopState( )

idgmsQStView (state)


char *gmsQStViewName (state)


idgmsQStWorkst (state)



State — query

char *gmsQStWorkstName (state)


DESCRIPTIONThe gmsQAllStates( ) function allocates and returns a linked list of allactive State objects. The list must be freed using refFreAll( ).

The gmsQStClassName( ) function returns a string containing theclass name of the class identified.

The gmsQStCurState( ) function returns a pointer to the current StateInstance (i.e., the most recently activated State Instance). When thisState is deactivated, the current State is the SuperState.

The gmsQStEvState( ) function returns a pointer to the last StateInstance that received an Event. After this State is deactivated, theevent State is 0.

The gmsQStIsActive( ) function takes a pointer to a State Instance anddetermines whether it is active or not; a 1 is returned if the StateInstance is active (i.e., has SuperStates or is the top-level StateInstance) and a 0 if the State Instance is inactive.

The gmsQStModel( ) function returns a pointer to the first Model in thisState Instance’s Model List.

The gmsQStModelList( ) function returns a pointer to State Instance’sModel List.

The gmsQStModelName( ) function returns a string containing thename of the first Model in State Instance’s Model List.

The gmsQStName( ) function returns a string containing the name ofthis State Instance.

The gmsQStStrMsgState( ) function returns a pointer to the last StateInstance that was sent a message.

The gmsQStSubStates( ) function returns a pointer to this StateInstance’s List of SubStates. This function returns a linked List ofState Instances.

The gmsQStSuperState( ) function returns a pointer to this StateInstance’s SuperState.


State — query

The gmsQStTextEditObj( ) function returns a pointer to state’sTextEdit object.

The gmsQStTopState( ) function returns a pointer to the top-levelState Instance.

The gmsQStView( ) function returns a pointer to this State Instance’sView.

The gmsQStViewName( ) function returns a string containing the nameof this State Instance’s View.

The gmsQStWorkst( ) function returns a pointer to this StateInstance’s Workstation/Window.

The gmsQStWorkstName( ) function returns a string containing thename of State Instance’s Workstation/Window.


State — variables

State — variables

SUMMARY

initialize Variable References to a State, and, used with dynamicdescriptions, make their scope local to a State

NAME

gmsStVarDefine( ), gmsStVarDefineChanged( ), gmsStVarChanged( ), gmsStVarDefChanged( ), gmsStFreeAllVarDefs( ), gmsStFindVarDefByNameAll( ), gmsStFindVarDefByAddrAll( ), gmsStFindVarDefAll( ), gmsStVarInitFctn( )

SYNTAX

idgmsStVarDefine(state, name, address, type, count,size)

id state; /* State Instance */char *name; /* name of variable */void *address; /* address of variable */int type; /* type of variable */int count; /* number of data elements */int size; /* size of each data element */

idgmsStVarDefineChanged( state, name, address, type,

count, size)id state; /* State Instance */char *name; /* name of variable */void *address; /* address of variable */int type; /* type of variable */int count; /* number of data elements */int size; /* size of each data element */


State — variables

intgmsStVarChanged (state, varname, varaddr)

id state; /* State Instance */char *varname; /* name of variable */void *varaddr; /* address of variable */

intgmsStVarDefChanged (state, vardef)

id state; /* State Instance */id vardef; /* Variable Definition object */

intgmsStFreeAllVarDefs (state)


idgmsStFindVarDefByNameAll (state, varname)

id state; /* State Instance */char *varname; /* name of variable */

idgmsStFindVarDefByAddrAll (state, varaddr)

id state; /* State Instance */void *varaddr; /* address of variable */

idgmsStFindVarDefAll (state, varname, varaddr)

id state; /* State Instance */char *varname; /* name of variable */void *varaddr; /* address of variable */

intgmsStVarInitFctn(function)

id (*function)( );

DESCRIPTIONThe gmsStVarDefine( ) function defines variables as local to a StateInstance. This function is often used to scope variable definitions on aModel-by-Model basis. Defining variables as local to a State ratherthan defining them as global with gmsVarDefine( ) can increase


State — variables

performance in applications which have a large number of variablesdefined. Variables defined in this manner are local in scope — twoModels in different States can have identical variable names which areactually pointing to different data items. When using SL-SMS,gmsStVarDefine( ) is usually put in a State’s definevars method.

A variable may be redefined anytime it is necessary to change thename and type attributes to which this variable refers by callinggmsStVarDefine( ) again. Then gmsDynInit( ) must be called tore-establish the links between the Variable Definition object and theVariable Reference objects which reference it.

EXAMPLEThe base of an array (i.e., the address of the Variable Definition objectdefining the array) is defined with the the following call :

/* define array to start at "base1" */gmsStVarDefine(gr_1,"y_array", &y_array[base1],


If at a later point in the code, the base of the array is to be re-defined inorder to scroll the portion of data displayed in a graph, there are twoways to modify the address of the Variable Definition object. Onemethod is to use gmsStVarDefine( ), in which case the following call ismade:

/* define array to start at "base2" */gmsStVarDefine(gr_1,"y_array", &y_array[base2],


The Variable Definition object created using gmsStVarDefine( ), mayalso be given a new address by calling gmsStVarDefAddress( ). Thecount and size attributes can also be changed by callinggmsStVarDefCount( ) and gmsStVarDefSize( ).

The gmsStVarDefineChanged( ) function defines a variable and marksit as changed. This function is the equivalent of calling bothgmsStVarDefine( ) and gmsStVarChanged( ) for a variable.

The gmsStVarChanged( ) function informs SL-GMS that an applicationvariable which has been defined as local to a State has changed. The


State — variables

variable name or address passed to this function is the same as thoseused when defining the variable with gmsStVarDefine( ).

The gmsStVarDefChanged( ) function takes a Variable Definitionobject as an argument and informs SL-GMS that an application variablehas changed. The Variable Definition object is created for a localvariable when the gmsStVarDefine( ) function is called.

The gmsStFreeAllVarDefs( ) function frees all variables that havebeen defined for a State Instance.

The gmsStFindVarDefByNameAll( ), gmsStFindVarDefByAddrAll( ),and gmsStFindVarDefAll( ) functions search for application variablesby their name, address, or both. The local State tables of the StateInstance passed to these functions are looked through first, then anySuperState’s tables are searched. Finally the global variable tablesare searched for a matching variable, and the Variable Definition objectis returned.

The gmsStVarInitFctn( ) function sets up a callback function, which iscalled every time a variable reference is encountered during thegmsDynInit( ) function execution. The callback is defined by the useras follows:

idstvarinit(state, object, varname, vartype)

id state;id object;char *varname;int vartype;

The gmsStVarInitFctn( ) function is similar to gmsVarInitFctn( ),except that there are two additional arguments. The first newargument passed in is the State which is doing the execution ofgmsDynInit( ). The second new argument is the SL-GMS Primitivebeing dyninited.

SEE ALSODynamics — Variable Definition Table attached to Models on page -96

Dynamics — query and set Variable Definition attributes on page -90

State — variables on page -382


State — variables, set and query attributes


SUMMARY

set and query individual attributes on an existing Variable Definitionobject

NAME

gmsStVarDefAddress( ), gmsQStVarDefAddress( ), gmsStVarDefCount( ), gmsQStVarDefCount( ), gmsStVarDefSize( ), gmsQStVarDefSize( )

SYNTAX

intgmsStVarDefAddress (state, vardef, address)

id state;id vardef;void *address;

void *gmsQStVarDefAddress (state, vardef)

id state;id vardef;

intgmsStVarDefCount (state, vardef, count)

id state;id vardef;int count;

intgmsQStVarDefCount (state, vardef)

id state;id vardef;



intgmsStVarDefSize (state, vardef, size)

id state;id vardef;int size;

intgmsQStVarDefSize (state, vardef)

id state;id vardef;

DESCRIPTIONA Variable Definition object is created using gmsStVarDefine( ). AVariable Definition object’s address, size, and count attributes may beaccessed individually.

The gmsStVarDefAddress( ) function sets the address of an existingVariable Definition object. The gmsStVarDefCount( ) function sets thenumber of data elements, and gmsStVarDefSize( ) sets the size ofeach data element of an existing Variable Definition object.

The gmsQStVarDefAddress( ), gmsQStVarDefCount( ), andgmsQStVarDefSize( ) functions are used to query individual attributeson an existing Variable Definition object. They are passed the id of theVariable Definition object. The gmsQStVarDefAddress( ) functionreturns the address. The gmsQStVarDefCount( ) function returns thenumber of data elements in the Variable Definition object. ThegmsQStVarDefSize( ) function returns the size of each data element.

NOTE: A Variable Definition object’s name and type attributescannot be changed in this way. To specify a new Variable Definition name or type, a new Variable Definition object must be created usinggmsStVarDefine( ). The gmsDynInit( ) function must thenbe called to re-establish the links between the VariableDefinition object and the Variable Reference objects whichreference it.



SEE ALSOgmsVarDefine( ), gmsVarDefineNoTable( ), gmsStVarDefine( ), gmsDynInit( )


Stress attribute

Stress attribute

SUMMARY

set the stress attribute

NAME

gmsStress( ), gmsLStress( ), gmsMStress( ), gmsQStress( )

SYNTAX

intgmsStress (obj, stress)

id obj;double stress;

intgmsLStress (objlist, stress)

idLinkRef objlist;double stress;

intgmsMStress (stress)

double stress;

doublegmsQStress (obj)

id obj;

DESCRIPTIONThe gmsStress( ) function sets the stress attribute on Spline andClosed Spline objects. The gmsStress( ) function must be greaterthan 0 and is typically less than 1. Stress affects how sharply a Splineis curved. The default stress is 0.5. Values near 0 produce flattenedcurves and values near 1 create sharp curves.

The gmsLStress( ) function sets the stress attribute on a List ofobjects.


Stress attribute

The gmsMStress( ) function sets the modal stress attribute, affectingsubsequently created Splines and Closed Splines.

The gmsQStress( ) function returns the stress attribute of an object, orthe modal stress attribute, if a nil pointer is used.

SEE ALSOgmsSpline( ), gmsCSpline( )

SL-GML COMMAND[name] stress double


Style attribute

Style attribute

SUMMARY

set the style attribute for objects; query the style attribute

NAME

gmsEStyle( ), gmsMStyle( ), gmsFStyle( ), gmsFInter( ), gmsLEStyle( ), gmsLMStyle( ), gmsLFStyle( ), gmsLFInter( ), gmsMEStyle( ), gmsMMStyle( ), gmsMFStyle( ), gmsMFInter( ), gmsQEStyle( ), gmsQMStyle( ), gmsQFStyle( ), gmsQFInter( )

SYNOPSIS

intgmsEStyle (obj, index)

id obj;int index;

intgmsMStyle (obj, index)

id obj;int index;

intgmsFStyle (obj, index)

id obj;int index;

intgmsFInter (obj, index)

id obj;int index;

intgmsLEStyle (objlist, index)



Style attribute

intgmsLMStyle (objlist, index)


intgmsLFStyle (objlist, index)


intgmsLFInter (objlist, index)


intgmsMEStyle (index)

int index;

intgmsMMStyle (index)

int index;

intgmsMFStyle (index)

int index;

intgmsMFInter (index)

int index;

intgmsQEStyle (obj)

id obj;

intgmsQMStyle (obj)

id obj;


Style attribute

intgmsQFStyle (obj)

id obj;

intgmsQFInter (obj)

id obj;

DESCRIPTIONThis is a complete set of functions for the manipulation of the differentstyle attributes supported by SL-GMS. The first group of functionsapplies to individual objects, the second group to Lists of objects, thethird to the modal attributes, and the fourth queries for style attributesettings. The character following the "gms", "gmsL", or "gmsM" in thename indicates whether the attribute applies to Edges ("E"), Lists ofobjects ("L"), Markers ("M"), or filled objects ("F"). Styles of filledobjects and Edges are platform-dependent.

The query functions return an integer that is an index for the styleattribute of an object. The query functions return 0 if the user queriesan object that does not have the particular style attribute. If a nilpointer is used as an argument to a query function, the current modalstyle attribute is returned. The modal attributes are referred to as the"current" width and are applied whenever new Graphical Primitiveobjects are created.

DIAGNOSTICSNo bounds checking is done for attributes. It is assumed that thedevice-driver software, at the SL-GWS layer of SL-GMS, deals with theattributes appropriately.

SL-GML COMMANDS[name] lstyle index

[name] estyle index

[name] mstyle index

[name] fstyle index

[name] finter index


SubModel List

SubModel List

SUMMARY

move SubModels between the current Model’s Local and ExternalSubModels List

NAME

gmsMExtToLoc( ), gmsMLocToExt( )

SYNTAX

intgmsMExtToLoc (model)

id model;

intgmsMLocToExt (model)

id model;

DESCRIPTIONThese functions move SubModels between the current Model’s Localand External SubModel Lists. Local SubModels are included with thecurrent Model when the current Model is saved or retrieved. ExternalSubModels exist as a Model file (with ".m1" extension), and are readfrom disk when they are used in a Model.

Any Model that is saved can be used as an external SubModel. If aModel used as an external SubModel is modified and saved, it appearsmodified in any Model which includes it as an external SubModel. If anexternal SubModel cannot be found when a Model is added to theGraphical Modeling Hierarchy, the Instances referencing the SubModelare freed.

The gmsMExtToLoc( ) function moves a Model from the ExternalSubModels List in the current Model to the Local SubModels List in thecurrent Model. It may remove the external Model from the system-wideList of external Models, which is used to determine whether an externalModel has already been read and added to the Graphical Modeling


SubModel List

Hierarchy (if this is the only reference to the external Model). A copy ofthe new local SubModel always becomes part of the current Model.

The gmsMLocToExt( ) function moves a Model from the LocalSubModels List in the current Model to the External SubModels List.Although external SubModels are based upon Model files, this functiondoes not create a file copy of the Model. The gmsMSave( ) functionmust be used explicitly to create the Model file for the new externalSubModel.

SEE ALSOgmsMSave( ), gmsModInst( ), gmsModel( ), gmsCurModel( ), gmsMGet( ), gmsMXGet( )


Text — attributes

Text — attributes

SUMMARY

set Text attributes

NAME

gmsBColor( ), gmsTFont( ), gmsTPrec( ), gmsTPath( ), gmsTHeight( ), gmsTAlign( ), gmsTSize( ), gmsTStr( ), gmsLTFont( ), gmsLTPrec( ), gmsLTPath( ), gmsLTHeight( ), gmsLTAlign( ), gmsLTSize( ), gmsLBColor( ), gmsLTStr( ), gmsMTFont( ), gmsMTPrec( ), gmsMTPath( ), gmsMTHeight( ), gmsMTAlign( ), gmsMTSize( ), gmsMBColor( ), gmsTPrec0RotFlag( )

SYNTAX

intgmsBColor (obj, color)

id obj;int color;

intgmsTFont (obj, index)

id obj;int index;

intgmsTPrec (obj, index)

id obj;int index;

intgmsTPath (obj, index)

id obj;int index;


Text — attributes

intgmsTHeight (obj, height)

id obj;double height;

intgmsTAlign (obj, alx, aly)

id obj;int alx;int aly;

intgmsTSize (obj, sx, sy)

id obj;int sx;int sy;

intgmsTStr (obj, string)


intgmsLTFont (objlist, index)


intgmsLTPrec (objlist, index)


intgmsLTPath (objlist, index)



Text — attributes

intgmsLTHeight (objlist, height)

idLinkRef objlist;double height;

intgmsLTAlign (objlist, alx, aly)

idLinkRef objlist;int alx;int aly;

intgmsLTSize (objlist, sx, sy)

idLinkRef objlist;int sx;int sy;

intgmsLBColor (list, color)

idLinkRef list;int color;

intgmsLTStr (objlist, string)

idLinkRef objlist;char *string;

intgmsMTFont (index)

int index;

intgmsMTPrec (index)

int index;

intgmsMTPath (index)

int index;


Text — attributes

intgmsMTHeight (height)

double height;

intgmsMTAlign (alx, aly)

int alx;int aly;

intgmsMTSize (sx, sy)

int sx;int sy;

intgmsMBColor (color)

int color;

intgmsTPrec0RotFlag(flag)

int flag;

DESCRIPTIONThis is a complete set of functions for the manipulation of the differentText attributes supported by SL-GMS. The first group of functionsapplies to individual objects, the second group to Lists of objects, andthe third to the modal attributes.

The specific meaning of each Text attribute is best gleaned from the Text button (of the Object Create Control Panel) section andtheir corresponding SL-GML commands in the SL-GMS® Reference .

The gmsBColor( ) function sets the Text background color for the givenText object. If no object is supplied, this function sets the modal Textbackground color.

The modal attributes are referred to as "current" and are appliedwhenever new Text objects are created.

The Text height is always multiplied by the World Coordinate ScaleFactor.


Text — attributes

The gmsTPrec0RotFlag( ) function sets the flag that enables anddisables rotation of precision 0 text (32-bit Windows only). The valuesG_ON and G_OFF are used to enable and disable text rotation. Turningthe flag on only enables text rotation, it does not cause currentlydisplayed text to be redisplayed. Text rotation is off by default.

DIAGNOSTICSNo bounds checking is done for attributes. It is assumed that thedevice-driver software, at the SL-GWS layer of SL-GMS, deals with theattributes appropriately.

SEE ALSOgmsWCScale( ), gmsText( ), gmsTColor( )

SL-GML COMMANDS[name] font index

[name] path index

[name] prec index

[name] height real


Text — object

Text — object

SUMMARY

create, change, or query a Text object or List of Text objects

NAME

gmsText( ), gmsTRepl( ), gmsLTStr( ), gmsQTStringC( ), gmsQTStringSO( ), gmsQTStringWC( ), gmsTStringC( ), gmsTStringSO( ), gmsTStringWC( )

SYNTAX

idgmsText (name, string, point)

char *name;char *string;idPoint point;

intgmsTRepl (obj, string)


intgmsLTStr (objlist, string)


intgmsQTStringC (obj, buffer, buffer_size, needed_size)

id obj;char *buffer;int buffer_size;int *needed_size;


Text — object

intgmsQTStringSO (obj, string_obj)

id obj;id string_obj;

intgmsQTStringWC (obj, buffer, buffer_size, needed_size)

id obj;wchar_t *buffer;int buffer_size;int *needed_size;

intgmsTStringC (obj, string)


intgmsTStringSO (obj, string_obj)

id obj;id string_obj;

intgmsTStringWC (obj, string)

id obj;wchar_t *string;

DESCRIPTIONThe gmsText( ) function is used to create a Text object given the Textstring and a position for the Text. The current Text attributes areapplied to the object when it is created.


The gmsTRepl( ) function is used to change the string of Text that isstored in the object. If SL-GMS is in Immediate Update Mode, the Textis erased and redisplayed with the new string. The gmsLTStr( )function replaces the Text in a List of Text objects with the new string.


Text — object

Because it is often desirable to use wide-character strings in aninternationalized application, the gmsTStringWC( ) andgmsQTStringWC( ) functions are provided, which modify and query thetext in Text and Text Rectangle objects using wide-characterstrings. The gmsTStringC( ) and gmsQTStringC( ) functions, whichuse character strings, are provided for consistency.

To avoid string data type dependencies in an application, thesedependencies must be encapsulated in an abstraction which cancontain either character strings or wide-character strings. Such anabstraction in provided in the form of the String object. ThegmsTStringSO( ) and gmsQTStringSO( ) functions modify and querythe text in Text and Text Rectangle objects using String objects.

The gmsTStringWC( ) function replaces the string contained in thegiven Text or Text Rectangle object with a copy of the givenwide-character string. If the given wide-character string is NULL, theText or Text Rectangle object will contain an empty string (L"") after thecall to gmsTStringWC( ). The function returns 1 if it succeeds and 0 ifit fails.

The gmsQTStringWC( ) function copies the string contained in thegiven Text or Text Rectangle object to the given wide-characterbuffer. The buffer_size argument specifies the maximum number ofwide-characters which can be copied to the given buffer, including theterminating wide-character. If the needed_size argument is not equalto NULL, gmsQTStringWC( ) stores in the memory location referencedby needed_size an integer specifying the buffer size required to copythe entire string in the Text or Text Rectangle to the buffer. This is thenumber of wide-characters needed, including the terminatingwide-character.

The string copied to buffer is always terminated by the nullwide-character (L'\0'), even when the function returns G_OVERFLOW.



Text — object

The gmsQTStringWC( ) function returns one of the values indicated in thefollowing table:

If gmsQTStringWC( ) returns G_OVERFLOW, the number returned byneeded_size can be used to allocate a larger buffer. After allocating alarger buffer, if buffer_size is greater than or equal to the number inneeded_size, a second call to gmsQTStringWC( ) will not returnG_OVERFLOW.

The gmsTStringC( ) function replaces the string contained in the givenText or Text Rectangle object with a copy of the given characterstring. If the given character string is NULL, the Text or Text Rectangleobject will contain an empty string ("") after the call togmsTStringC( ). The function returns 1 if it succeeds and 0 if it fails.

The gmsQTStringC( ) function copies the string contained in the givenText or Text Rectangle object to the given character buffer. Thebuffer_size argument specifies the maximum number of characterswhich can be copied to the given buffer, including the terminationcharacter. If the needed_size argument is not equal to NULL,gmsQTStringC( ) stores in the memory location referenced byneeded_size an integer specifying the buffer size required to copy theentire string in the Text or Text Rectangle to the buffer. This is thenumber of characters needed, including the termination character.

Value Meaning


G_OVERFLOW The given buffer was NULL or not large enough to copy the entire contents of the string contained in the Text or Text Rectangle. If buffer was not NULL, buffer_size wide-characters were copied.

G_INVALID_INPUT

One of the parameters to the function was invalid.


Text — object



The gmsQTStringC( ) function returns one of the values indicated inthe following table:

If gmsQTStringC( ) returns G_OVERFLOW, the number returned byneeded_size can be used to allocate a larger buffer. After allocating alarger buffer, if buffer_size is greater than or equal to the number inneeded_size, a second call to gmsQTStringC( ) will not returnG_OVERFLOW. However, the function may returnG_CONVERSION_FAILURE.

The gmsTStringSO( ) function replaces the string contained in thegiven Text or Text Rectangle object with a copy of the string containedin the given String object. The String object can contain either a

Value Meaning


G_OVERFLOW The given buffer was NULL or not large enough to copy the entire contents of the string contained in the Text or Text Rectangle. If buffer was not NULL, buffer_size characters were copied.


G_CONVERSION_FAILURE Information was lost when the wide-character string in the given object was converted to multi-byte form.


Text — object

character string or a wide-character string. The function returns 1 if itsucceeds and 0 if it fails.

The gmsQTStrSO( ) function copies the string contained in the givenText or Text Rectangle object to the given String object. If the buffer inthe given String object is not large enough to contain the entire string, itis freed and a larger one is allocated. The String object itself is notreallocated. The function returns 1 if it succeeds and 0 if it fails.

SEE ALSOInternationalization — String object on page -208

gmsTFont( )

SL-GML COMMANDS[name:] text "string" x y

name stext "string"


Text — query attributes


SUMMARY

query Text attributes

NAME

gmsQTFont( ), gmsQTPrec( ), gmsQTPrec0RotFlag( ), gmsQTPath( ), gmsQTSizeX( ), gmsQTSizeY( ), gmsQBColor( ), gmsQTHeight( ), gmsQTAlignX( ), gmsQTAlignY( )

SYNTAX

intgmsQTFont (obj)

id obj;

intgmsQTPrec (obj)

id obj;

intgmsQTPrec0RotFlag( )

intgmsQTPath (obj)

id obj;

intgmsQTSizeX (obj)

id obj;

intgmsQTSizeY (obj)

id obj;

intgmsQBColor (obj)

id obj;



doublegmsQTHeight (obj)

id obj;

intgmsQTAlignX (obj)

id obj;

intgmsQTAlignY (obj)

id obj;

DESCRIPTIONThis group of functions queries the attributes of particular Text objects,or returns the modal attribute if a nil pointer is used as the argument.A 0 is returned if the object queried is not a Text object.

The gmsQTPrec0RotFlag( ) functions queries the status of the textrotation flag for precision 0 text (32-bit Windows only).


Text Rectangle — constraint attribute


SUMMARY

Set,or query, the Text Rectangle constraint attribute.

The Text Rectangle constraint attribute controls how text behaves whenit overflows the bounds of the Text Rectangle.

NAME

gmsTRectTextConstraint( ), gmsLTRectTextConstraint( ), gmsMTRectTextConstraint( ), gmsQTRectTextConstraint( )

SYNTAX

intgmsTRectTextConstraint(trect, constraint)

id trect;unsigned int constraint;

intgmsLTRectTextConstraint(objlist, constraint)

idLinkRef objlist;unsigned int constraint;

intgmsMTRectTextConstraint(constraint)

unsigned int constraint;

unsigned intgmsQTRectTextConstraint(trect)

id trect;

DESCRIPTIONThis set of functions sets or queries the text constraint attribute for TextRectangle objects. The text constraint attribute may be any one of thevalues described below.



G_TCONSTRAINT_NONE This value is the default and allows a Text Rectangle's text to displayoutside (overflow) the Rectangle portion of the object.

G_TCONSTRAINT_CLIP This value causes a Text Rectangle's text to be clipped to the Rectangleboundary.

G_TCONSTRAINT_FIT_WIDTH This value causes a Text Rectangle's text to fit inside the width of theRectangle boundary. This is accomplished by changing the position ofindividual characters in the text. The characters may overlap eachother to stay inside the boundary. If the width of a single characteroverflows the boundary, the characters will overlap each other and thetext will overflow the text rectangle (it will not be clipped). This modedoes not modify font size, just character positioning. This mode is usedto compensate for the non-linear scaling of 32-bit Windows TrueTypefonts.

NOTE: G_TCONSTRAINT_FIT_WIDTH is only supported for precision 0 fonts on 32-bit Windows platforms.

None of the constraint modes use edge width to make the TextRectangle boundary smaller for fitting or clipping the text. The TextRectangle boundary is the same as the Text Rectangle's edge if thevalue of the edge width is 1.

The gmsTRectTextConstraint( ) function sets the text constraintattribute on a single Text Rectangle object.

The gmsLTRectTextConstraint( ) function sets the text constraintattribute for all Text Rectangle objects in a list.

The gmsMTRectTextConstraint( ) function sets the modal textconstraint attribute.

The gmsQTRectTextConstraint( ) function returns the text constraintattribute of a given Text Rectangle object.

SL-GML COMMANDStconstraint index

[name] tconstraint index


Traps — signal handling


SUMMARY

modify the default signal-handling behavior of SL-GMS

NAME

gmsSetTraps( ), gmsTrapSignalMode( ), gmsQTrapSignalMode( ), gmsXKillTimer( ), gmsCrashHandlerFctn( )

SYNTAX

intgmsSetTraps (workst)

id workst;

intgmsTrapSignalMode (mode)

int mode; /* "trap signal"0 - do not catch any signals1 - catch signals and execute

the "crash handler" */

intgmsQTrapSignalMode ( )

intgmsXKillTimer ( )

intgmsCrashHandlerFctn (fctn)

int (*fctn)( ); /* "crash handler" function */



DESCRIPTIONThe gmsSetTraps( ) function is called only once in an applicationprogram, and is called automatically by gmsMainInit( ). It can becalled in an application without gmsMainInit( ) after creation of the firstWorkstation/Window. It is this first Workstation/Window that is passedto gmsSetTraps( ). The gmsSetTraps( ) function installs handlers forinterrupt signals along with bus errors, segmentation violations, andbad system calls. If an application uses gmsSetTraps( ), SL-GMScalls its own interrupt handlers. Applications which have their owninterrupt handlers use system-specific signal calls. For example, onUNIX systems, the function signal( ) is used.

By default, SL-GMS catches the signals listed below (Trap Signal Mode = 1), and produces no "core" file for these signals:

The gmsTrapSignalMode( ) function can be used to turn off SL-GMS’catching of traps, by calling the function with a mode argument of 0.The gmsQTrapSignalMode( ) function queries the Trap Signal Mode.

NOTE: The gmsTrapSignalMode( ) function must be called before gmsSetTraps( ) or gmsMainInit( ) is called.

Restrictions for X WorkstationApplications that use the X-Windows Workstation (non-toolkit, Xlib only)must take special care when disabling automatic SL-GMS signalhandling.

Default SL-GMS Behavior for Signals

Signal DescriptionSIGINT print a <NEWLINE> and return to program

essentially ignoring the signalSIGQUIT print the message "... SL-GMS killed" and exit

the program without creating a "core" fileSIGSEGVSIGBUSSIGILLSIGSYS

print a message indicating the type of signal, and exit without producing a "core" file; a special "crash handler" function is invoked prior to exiting



In order to provide timer events, SL-GMS starts a subprocess,gmstimer. If the application terminates abnormally, this subprocess iskilled as part of the normal signal handling cleanup. If an applicationdisables SL-GMS signal handling by calling

gmsTrapSignalMode(0);

the gmstimer subprocess must be killed by the application'ssignal-handling code. The gmsXKillTimer( ) function is provided forthis purpose:

intgmsXKillTimer ( )/* kill "gmstimer" process */

In addition, the gmsCrashHandlerFctn( ) function is provided to set upa "crash handler" function which is called before exiting. The crashhandler function may attempt some kind of error recovery, beforeexiting. For example, SL-DRAW uses this to try to save the workingModel before exiting (if the crash is non-fatal, i.e., it has not corruptedmemory).

The "crash handler" function must take a single argument which is thetrapnum that caused the crash. A sample "crash handler" function isshown on the following page from SL-DRAW, attempting to save theworking Model before exiting.

static intdr_crash_handler (trapnum)

int trapnum;{

char *s;

printf("... SL-DRAW crashing ... attempting tosave work model.\n");

/* attempt to save the work Model */gmsMSave(m_work, "DRAWCRASH");



/* cause a core dump on most platforms*/

printf("... this should core dump\n");s = (char *)3;*s;

return 1;}

NOTE: The creation of the "core" file is accomplished in this crash handler by executing an invalid statement.


Update

Update

SUMMARY

perform partial update or complete redraw of a View; set ImmediateUpdate Mode or Deferred Update Mode

NAME

gmsUpdate( ), gmsUpdateExtents( ), gmsRedraw( ), gmsRedrawNoErase( ), gmsImmu( ), gmsDefu( ), gmsNoUpdImmu( ), gmsUpdateDisplayOnly( ), gmsUpdateEraseOnly( )

SYNTAX

intgmsUpdate (view)

id view;

intgmsUpdateExtents (view)

id view;

intgmsRedraw (view)

id view;

intgmsRedrawNoErase (view)

id view;

intgmsImmu( )

intgmsDefu( )

intgmsNoUpdImmu( )


Update

intgmsUpdateDisplayOnly (view)

id view;

intgmsUpdateEraseOnly (view)

id view;

DESCRIPTIONThe update functions control the way in which the SL-GMS system orspecified Views are erased and redrawn. Updating involves thecalculation of object extents (used for clipping objects), erasing objectsif they are marked for erase, drawing objects if they are marked fordisplay, and then clearing the update flags on objects. In thesefunctions, if a nil pointer is given where a View is expected, the functionis applied to all Views in the Graphical Modeling Hierarchy.

The gmsUpdate( ) function causes visible objects that are internallymarked for erase or display to be erased, if necessary, and drawn onactive Workstation/Windows. This function is used to update onlythose objects that have been changed in a way that requires them to beredrawn. Objects are automatically marked internally for erase ordisplay when they are created, freed, transformed, or their attributesare changed.

The gmsUpdateExtents( ) function does a "true" update byrecalculating (updating) the extents of objects marked for update in thegiven View without redrawing anything.

The gmsRedraw( ) function is used to redraw all objects in a Viewregardless of whether they have changed (been marked for erase ordisplay).

The gmsRedrawNoErase( ) function redraws a View on aWorkstation/Window. If no View is given, all Views are redrawn.Objects marked for erasure are not erased before being redrawn.

SL-GMS can be placed into Immediate Update Mode with thegmsImmu( ) function or into Deferred Update Mode with thegmsDefu( ) function. If in Immediate Update Mode, any change to anobject results internally in the immediate issue of a gmsUpdate( )function call. Calling gmsImmu( ) implicitly forces a gmsUpdate( )


Update

call. In Deferred Update Mode, no update occurs until explicitly calledfor by gmsUpdate( ) in an application program. Deferred Update Modeis the SL-GMS default.

The gmsNoUpdImmu( ) function is used to put SL-GMS into ImmediateUpdate Mode, without actually triggering an update.

The gmsUpdateDisplayOnly( ) function updates a View by displayingobjects marked for display on all Workstation/Windows. If no View isgiven, all Views are updated.

The gmsUpdateEraseOnly( ) function updates a View by erasingobjects marked for erase on all Workstation/Windows. If no View isgiven, all Views are updated.

SEE ALSOgmsClear( ), gmsClip( )

SL-GML COMMANDS[name] update

[name] clear

[name] redraw

immu

defu


User-defined functions


SUMMARY

add or remove a user-defined function that may be used in dynamicdescriptions

NAME

gmsAddUserFctn( ), gmsRemUserFctn( )

SYNTAX

intgmsAddUserFctn (name, addr, rtype, argcnt, argtypes)

char *name; /* function name */void (*addr)( );/* function address */int rtype; /* return type */int argcnt; /* argument count */int *argtypes; /* array of argument types */

intgmsRemUserFctn (name, addr)

char *name; /* function name */void (*addr)( );/* function address */

DESCRIPTIONFunctions from a user’s application can appear in expressions and asthe argument to the dynamic action call. The key to using user-definedfunctions is identifying them to SL-GMS. SL-GMS maintains aninternal table of user-defined functions, along with the necessaryinformation for handling arguments and return values. ThegmsAddUserFctn( ) function performs the setup of the internal table.

The return code is 1 when the user-defined function is added to thetable. If unable to add the user-defined function to the table, 0 isreturned. There is no limit to the number of entries allowed in theinternal table.



The function name, name, is the string as used in dynamicdescriptions. It can be any string that begins with a letter, providedthat the string does not conflict with the name of SL-GMS dynamicactions (listed in the table Dynamic Actions in the chapter DynamicsReferenceof the SL-GMS Quick Reference) or other variables in theapplication. A conflict with a reserved dynamic action name preventsthe gmsAddUserFctn( ) call from succeeding, for example, defining afunction named rotate would not be successful.

The address of the function, addr, is obtained by declaring the functionearlier in the program and using the name of the function in thegmsAddUserFctn( ) call.

The user function return type, rtype, is taken from the table of typecodes defined in the description of the gmsVarDefine( ) function onpage 110.

The argument count, argcnt, specifies the number of calling argumentsand the argument types are set in an array, argtypes. For example, ifthere are two calling arguments, both of type integer, the argcountwould be 2 and the array would have two elements, all G_INTEGER.

EXAMPLEThe following DynProp uses a user-defined function named MyFunc( ).This function takes two integer arguments and returns a double value.

rotate MyFunc(value1, value2)

To identify the actual function to be used to SL-GMS, thegmsAddUserFctn( ) function is used.

#include “gmscodes.h”

...

double MyFunc( );

static int argtypes[] = { G_INTEGER, G_INTEGER};

if(!gmsAddUserFctn("MyFunc",MyFunc,G_DOUBLE,2,argtypes))

fprintf(stderr,"Unabletoaddfunctiontointernaltable.\n");

The "gmscodes.h" file is distributed in the lib directory.



An SL-GMS-internal function, userfctns_initialize( ), is calledautomatically by gmsSetup( ) to allow users to install their applicationfunctions as part of SL-GMS and callable from DynProps. Theuserfctns_initialize( ) function is available to users as a convenienceso that the main( ) routine of an application does not have to bechanged whenever the user wishes to add, delete, or changeuser-defined functions.

To utilize userfctns_initialize( ), a "userfctns.c" moduleis created by the user and contains the user’s ownuserfctns_initialize( ) function. Inside this function, allof the calls to gmsAddUserFctn( ) are placed. A sample "userfctns.c"module is shown below:

Sample "userfctns.c"(user-defined function) module#include "gmsc.h"

/* sample user function */static intuser_test (iarg, darg)

int iarg;double darg;

{printf("Function user_test(iarg = %d, darg = %g)

called.\n", iarg, darg);return iarg;

}/* array of argument types for sample

user function */

int args_int_doub[] = { G_INTEGER, G_DOUBLE };

/* initialize user-defined functions*/

intuserfctns_initialize ( ){



gmsAddUserFctn("user_test",user_test,G_INTEGER,2, args_int_doub);

return 1;}

The "userfctns.c" module is recompiled to produce "userfctns.o" andthen relinked with SL-DRAW2, SL-DRAW, and/or SL-GML.

The gmsRemUserFctn( ) function allows users to delete user-definedfunctions from the SL-GMS internal table of user-defined functions.Either the name of the function to be removed, its address, or both canbe passed to gmsRemUserFctn( ). A return value of 1 indicates thatthe function has been deleted and all memory associated with it hasbeen freed. A return value of 0 indicates that the deletion wasunsuccessful. After the user functions have been removed, no Modelsshould be active that have these functions used in DynProps.

SEE ALSOgmsVarDefine( )

The chapter entitled Dynamicsin the SL-GMS Reference


UserData and UserWord


SUMMARY

set or query the UserData or UserWord associated with an object

NAME

gmsUserData( ), gmsLUserData( ), gmsQUserData( ), gmsUserWord( ), gmsQUserWord( )

SYNTAX

intgmsUserData (obj, string)

id obj;char * string;

intgmsLUserData (objlist, string)


char *gmsQUserData (obj)

id obj;

intgmsUserWord (obj, word)

id obj;long word;

longgmsQUserWord (obj)

id obj;



DESCRIPTIONThe gmsUserData( ) function sets the UserData string associated withan object. UserData is intended as a method under the application’scontrol for adding arbitrary information to Graphical Primitive objects.The only restriction for UserData is that it must be a C string. Themaximum length of a UserData string is 16,384 characters.

The gmsLUserData( ) function sets the UserData string for all objectson a List of objects.

The gmsQUserData( ) function returns the UserData string associatedwith a Graphical Primitive object, or null if there is no string.

The gmsUserWord( ) function sets an object’s UserWord. TheUserWord is an integer that is associated with an object for arbitraryuse in an application. The integer can be a negative value.

The gmsQUserWord( ) function returns the object’s UserWord.

SL-GML COMMANDS[name] userdata string

[name] userword integer


View — miscellaneous


SUMMARY

set or clear the locator capture mode for a View; return the locatorcapture mode for a View; delay redraw

NAME

gmsVuLocCaptureMode( ), gmsQVuLocCaptureMode( ), gmsVuRedrawOnNextUpdate( )

SYNTAX

intgmsVuLocCaptureMode (view, mode)

idG_VIEW view;int mode;

intgmsQVuLocCaptureMode (view)mode for view */

idG_VIEW view;

intgmsVuRedrawOnNextUpdate(view)

id view;/* GMS view */

DESCRIPTIONThe gmsVuLocCaptureMode( ) function sets or clears the locatorcapture mode for a View. When the argument mode is set to 1, locatorcapture is enabled on the View. When the argument mode is set to 0,locator capture is disabled on the View. By default, locator capture isdisabled on View objects.

Locator capture mode causes locator press-drag-release interactions tobe grouped together and delivered to a single View, even if the locatoris moved outside of the window before the button is released.



When locator capture mode is set and a locator press event occurs inthe View, all subsequent locator events are delivered to the View until alocator release event occurs. The loc_motion and loc_release eventsare delivered to the View even if the locator is outside of the window inwhich the loc_press event occurred.

The gmsQVuLocCaptureMode( ) function returns the locator capturemode for a View.

The gmsVuRedrawOnNextUpdate( ) function will notify a View that allof its models need to be redrawn during the next update (i.e.gmsUpdate( )). This function only needs to be called in special cases.Only one update is affected per gmsVuRedrawOnNextUpdate( ) call(subsequent updates will behave normally). This allows a delayedredraw to be forced.

One example where the gmsVuRedrawOnNextUpdate( ) functionmight be used is if gmsWindXY( ) is called and extra processing isdone after the gmsWindXY( ) call. After the extra processing,gmsUpdate( ) is called. The function gmsWindXY( ) requires aredraw, but this isn't guaranteed to be done unless gmsRedraw( ) iscalled because calling gmsUpdate( ) doesn't guarantee a redraw.However, calling gmsRedraw( ) could cause two redraws instead ofone because the gmsUpdate( ) call could redraw. This type of situationis solved by calling gmsVuRedrawOnNextUpdate( ) instead ofgmsRedraw( ). In this case the next gmsUpdate( ) call is guaranteedto do a redraw.

SEE ALSOgmsUpdate( ), gmsWindXY( ), gmsRedraw( )


View — object

View — object

SUMMARY

create or end a new View; set current View; set View priority; returnView dimensions; enable/disable segments; set Workstation/Windownumber; set Clip Mode and Resolution Check Mode

NAME

gmsView( ), gmsEndView( ), gmsVuPri( ), gmsVuList( ), gmsVuDim( ), gmsWsNum( ), gmsClip( ), gmsWsSoftClip( ), gmsResChk( ), gmsVuWorkst( )

SYNTAX

idgmsView (name, modlist)

char *name;idLinkRef modlist;

intgmsEndView( )

intgmsVuPri (view1, view2)

id view1;id view2;

idLinkRefgmsVuList( )

intgmsVuDim (view, p1, p2)

id view;idPoint p1;idPoint p2;


View — object

intgmsWsNum (view, number)

id view;int number;

intgmsClip (view, clipflag)

id view;int clipflag;

intgmsWsSoftClip(ws, action)

id ws;int action; /* G_ON or G_OFF */

intgmsResChk (view, resflag)

id view;int resflag;

intgmsVuWorkst (view, workst)

id view;id workst;

DESCRIPTIONThe gmsView( ) function is used to create a View with defaultcharacteristics and add it to the Graphical Modeling Hierarchy with thename given. This function may be called with a List of Models whichare to go into the View as it is created. The created View becomes thecurrent View.

The gmsEndView( ) function terminates the current View, leavingSL-GMS with no current View. Any additional Models created (while noModel is current) forces a new default View to be created.

The gmsVuPri( ) function sets View priority. The View specified byview1 receives higher priority than view2. Higher priority Views aredisplayed after, and on top of lower priority Views. Thus, in the case ofoverlapping Views, the highest priority View is specified by a LocEvent


View — object

input Event (such as selecting a View with a mouse or passing aLocEvent to gmsFindObject( )).

The gmsVuList( ) function returns the current List of Views in thepriority order in which they are displayed. A pointer to the actual ViewList maintained internally by SL-GMS is returned, so this List shouldnever be modified directly. The gmsVuList( ) function is for referenceonly.

The gmsVuDim( ) function sets the two Points in the argument list tothe x and y dimensions of the given View. This action is useful afterzooming has changed the size of the View.

The gmsWsNum( ) function is used to change the Workstation/Windownumber for the given View object or the default View. The defaultWorkstation/Window number for a View object is 0. EachWorkstation/Window object is added to the System object’s List ofWorkstation/Windows after it is created. The first Workstation/Windowobject created has the index of 0, which is identical toWorkstation/Window number 0. Therefore, by default, all Views areassociated (and are displayed in) Workstation/Window number 0.

If another Workstation/Window object is added, theWorkstation/Window number of a View object is changed to associatethe View with the new Workstation/Window. The secondWorkstation/Window added has Workstation/Window number 1, thethird, number 2, and so on. Many Views may be associated with thesame Workstation/Window, but only one Workstation/Window may beassociated with each View object.

The gmsClip( ) function is used to set the Clip Mode for a specific View.The following table describes the two available modes:

Smart clipping is useful when there may be objects outside of the View.The extent of every object in the View is checked prior to performing theclip function. If the object is either entirely outside or inside the View,

Mode Description1 always clip2 automatic, or smart,

clipping


View — object

there is no need to clip; only when the object straddles the View doesclipping become necessary.

The gmsWsSoftClip( ) function toggles software clipping flags on a workstation. If the software clipping flag is set to G_ON, theworkstation will clip all line coordinates to the rectangle defined by thepixel coordinates (-16521, -16490) and (16255, 16277). Currently, thisfunctionality works on X workstations and causes only lines to beclipped.

Although a slight performance decrease occurs when software clippingis used, it can prevent display anomalies which happen whenSL-GMS-internal coordinates are converted to X coordinates,especially when zooming into a small part of a Model, such as a map.

The software clipping flag should be set before a workstation is used fordisplay.

id workst;workst=gmsQStWorkst(gmsStFindByName(“zoompan_state”))

;gmsWsSoftClip(workst, G_ON);

The gmsResChk( ) function sets the Resolution Check Mode for theView. If set to 0, there is no check performed. If set to 1, the extent ofan object is checked prior to drawing, and a single Point or a small boxis drawn if the extent is .3% of the View. Setting the mode to 1somewhat speeds up the drawing.

Both automatic clipping and resolution check introduce the overheadassociated with carrying around an extent for each object. If neither isset, no extents need be calculated. If the gmsFindObject( ) function iscalled, however, the View specified by the locator argument causesextents to be calculated for all objects in that View.

The gmsVuWorkst( ) function sets a Workstation/Window id for a View.

SEE ALSOgmsWind( ), gmsZoom( ), gmsFindObject( ), gmsWorkst( ), gmsQCurView( )


View — object

SL-GML COMMANDS[name:] view [modlist]

endview

name current

name segments

name clip int

name reschk int


View — WC-window and Viewport


SUMMARY

set the WC-window and Viewport limits for a View

NAME

gmsWind( ), gmsPort( ), gmsWVXY( ), gmsWinPts( ), gmsWindXY( ), gmsPortXY( )

SYNTAX

intgmsWind (view, p1, p2)

id view;idPoint p1; /* World Coordinate Points */idPoint p2;

intgmsPort (view, p1, p2)

id view;idPoint p1; /* Normalized Device Coordinates */idPoint p2;

intgmsWVXY (view, x1, y1, x2, y2)

id view;double x1; /* World Coordinates */double y1;double x2;double y2;

intgmsWinPts (view, p1, p2)

id view;idPoint p1; /* World Coordinate Points */idPoint p2;



intgmsWindXY (view, x1, y1, x2, y2)

id view;double x1; /* World Coordinates */double y1;double x2;double y2;

intgmsPortXY (view, x1, y1, x2, y2)

id view;double x1; /* Normalized Device Coordinates */double y1;double x2;double y2;

DESCRIPTIONThese functions make changes to View objects. The gmsWind( ) andgmsPort( ) functions change the current or designated View’sWC-window and Viewport values. If the view argument is nil, thesefunctions apply to the current View, otherwise they apply to the Viewgiven.

The point arguments must be pointers to Point objects. ThegmsWind( ) function arguments are created by the gmsWPXY( )function since they are in World Coordinates. Only Points and objectsthat are within the limits of the WC-window are displayed in the View.

The gmsWind( ) and gmsWVXY( ) functions set the WC-window usingthe parameters given for Points, and automatically recalculate theViewport. The Viewport is automatically calculated as (0.0, 0.0), (1.0,aspect) where:

aspect y2 y1–x2 x1–-------------------=



and (x1, y1), (x2, y2) are in World Coordinates. The standard aspectratio is a 3:4 ratio of height to width.

The gmsWVXY( ) function converts the given coordinates to Pointobjects before calling gmsWind( ), and frees the Point objects beforereturning.

The gmsWinPts( ) function creates a WC-window without changing theViewport (unlike gmsWind( ), which does change the Viewport). ThegmsWindXY( ) function converts the coordinate arguments to Pointobjects before calling gmsWinPts( ), and frees the Point objects beforereturning. The gmsWinPts( ) function creates a View if nil is passedas an argument for the View.

The Points for the gmsPort( ) function should be created by thegmsNPXY( ) function, as they must be in Normalized DeviceCoordinates. These Viewport coordinates select the portion of theidealized device surface in which the WC-window for the View isdisplayed. The gmsPortXY( ) function converts the coordinatearguments to Normalized Device Coordinate Points before callinggmsPort( ), and frees the Point objects before returning.

SEE ALSOgmsView( ), gmsZoom( ), gmsWPXY( ), gmsNPXY( )

The chapter entitled Display of Models in the SL-GMS Reference

SL-GML COMMANDS [name] wind x y x y

[name] port x y x y


View — zoom and pan


SUMMARY

zoom or pan a View and reset zoom and pan status

NAME

gmsZoom( ), gmsZmIn( ), gmsZmOut( ), gmsPan( ), gmsZpr( ), gmsZps( )

SYNTAX

intgmsZoom (view, p1, p2)

id view;idPoint p1;idPoint p2;

intgmsZmIn (view)

id view;

intgmsZmOut (view)

id view;

intgmsPan (view, point)

id view;idPoint point;

intgmsZpr (view)

id view;

intgmsZps (view)

id view;



DESCRIPTIONThese functions make changes to View objects. The four functions,gmsZoom( ), gmsZmIn( ), gmsZmOut( ), and gmsPan( ) maketemporary changes to the WC-window. The gmsZpr( ) function resetsthe View after any of the four temporary change functions are used.The gmsZps( ) function is used to make the temporary WC-windowchange permanent by applying the zoom or pan directly to the View’sWC-window coordinates.

By default, the gmsZmIn( ) and gmsZmOut( ) functions use the factors1.618 and 0.618 (the golden mean) to calculate the new WC-windowlimits.

SEE ALSOgmsView( ), gmsWind( )

SL-GML COMMANDS[name] zoom x y x y

[name] zoomin

[name] zoomout

[name] pan x y

[name] zpr

[name] zps


Visibility and detectability attributes


SUMMARY

set the visibility and detectability attributes

NAME

gmsVis( ), gmsLVis( ), gmsMVis( ), gmsDetect( ), gmsLDetect( ), gmsMDetect( ), gmsQDetect( ), gmsQVis( )

SYNTAX

intgmsVis (obj, visflag)

id obj;int visflag;

intgmsLVis (objlist, visflag)

idLinkRef objlist;int visflag;

intgmsMVis (visflag)

int visflag;

intgmsDetect (obj, detflag)

id obj;int detflag;

intgmsLDetect (objlist, detflag)

idLinkRef objlist;int detflag;

intgmsMDetect (detflag)

int detflag;



intgmsQDetect (obj)

id obj;

intgmsQVis (obj)

id obj;

DESCRIPTIONThe gmsVis( ) function is used to set the visibility on SL-GMSGraphical Primitive objects or Views. The possible values are:

Setting the visibility to 3 also sets the display flag on the object, whichforces it to be redrawn on the next update even if it is already visible.

The gmsLVis( ) function sets the visibility on a List of objects. Thevisibility attributes are the same as for the gmsVis( ) function.

The gmsMVis( ) function sets the modal visibility, affectingnewly-created Graphical Primitives.

The gmsDetect( ) function is used to set the detectability of GraphicalPrimitive objects or Views.. If set to 0, the object is not detectable; ifset to1, it is detectable. Non-detectable objects can be retrieved withthe gmsFindByName( ) function.

The gmsLDetect( ) function sets the detectability on a List of objects.The detectability attributes are the same as for the gmsDetect( )function.

The gmsMDetect( ) function sets the modal detectability, affecting allsubsequently-created Graphical Primitive objects.

The query functions return the visibility or detectability of a GraphicalPrimitive object. The gmsQDetect( ) function also returns the modal

Value Description 0 invisible 1 visible 2 highlighted 3 visible, force

redraw



detectability of Graphical Primitive objects if called with a nil argument.The gmsQDetect( ) function returns an object’s detectability attribute.

The gmsQVis( ) function queries an object’s visibility.

DIAGNOSTICSThe gmsVis( ) function does not yet support visflag = 2. Support forthe function in hardware does not exist.

SEE ALSOgmsFindByName( )

SL-GML COMMANDS name vis visflag

name detect detflag


Workstation/Window — attribute changes


SUMMARY

manipulate Workstation/Window attributes

NAME

gmsWinBannerName( ), gmsWinClear( ), gmsWinDestroy( ), gmsWindowDestructionFctn( ), gmsWinExt( ), gmsWsWind( ), gmsWsWindXY( ), gmsWsPort( ), gmsWsPortXY( ), gmsWinFlags( ), gmsWinIconName( ), gmsWinMap( ), gmsWinPop( ), gmsWinPush( ), gmsWinSetFocus( ), gmsWinUnmap( )

SYNTAX

intgmsWinBannerName (workst, name)

id workst; /* Workstation/Window */char *name; /* Window banner name */

intgmsWinClear (workst)

id workst; /* Workstation/Window */

intgmsWinDestroy (workst)


intgmsWindowDestructionFctn (cb_fctn)

int (*cb_fctn)();/* callback function */

intgmsWinExt (workst, lower_left, top_right)

id workst; /* Workstation/Window */idPoint lower_left/* corner of Window extent */idPoint top_right;/* corner of Window extent */



intgmsWsWind (workst, p1, p2)

id workst; /* Workstation/Window */idPoint p1; /* NDC Point */idPoint p2; /* NDC Point */

intgmsWsWindXY (workst, x1, y1, x2, y2)

id workst; /* Workstation/Window */double x1; /* NDC Point */double y1; /* NDC Point */double x2; /* NDC Point */double y2; /* NDC Point */

intgmsWsPort (workst, lower_left, upper_right)

id workst; /* Workstation/Window */idPoint lower_left; /* DC Point */idPoint upper_right; /* DC Point */

intgmsWsPortXY (workst, x1, y1, x2, y2)

id workst; /* Workstation/Window */double x1; /* DC Point */double y1; /* DC Point */double x2; /* DC Point */double y2; /* DC Point */

intgmsWinFlags (workst, bit, onoff)

id workst; /* Workstation/Window */int bit; /* flag bit to be set */int onoff; /* onoff = G_ON or G_OFF */

intgmsWinIconName (workst, name)

id workst; /* Workstation/Window */char *name; /* icon name */



intgmsWinMap (workst, raiseflag)

id workst; /* Workstation/Window */int raiseflag; /* raiseflag = G_ON/G_OFF */

intgmsWinPop (workst)


intgmsWinPush (workst)


intgmsWinSetFocus (workst, window)

id workst; /* Workstation/Window */id window; /* X window widget handle */

intgmsWinUnmap (workst)


DESCRIPTIONThe gmsWinBannerName( ) function stores name in theWorkstation/Window’s banner name field and displays the name in theWorkstation/Window banner.

The gmsWinClear( ) function clears the Workstation/Window to color 0.

The gmsWinDestroy( ) function destroys the Workstation/Window.

NOTE: The gmsWinDestroy( ) function does not close or free thechanged Workstation/Window; the gmsWsClose( ) functionshould be used instead.

The gmsWindowDestructionFctn( ) function will register a windowdestruction callback function, cb_fctn( ), with SL-GMS. The callbackfunction will be called for externally created windows at the point whereSL-GMS normally destroys its own window associated with aworkstation. The application is free to destroy or not destroy the



window/widget, perhaps reusing it for another call to gmsWorkst( ).However, the workstation parameter passed to cb_fctn( ) should not bereferenced again.

For Windows NT applications, cb_fctn( ) would be declared as follows.

intcb_fctn (workst, window)

id workst;HWND window;

{/* function body */

}

For X Windows applications, cb_fctn( ) would be declared as follows.

intcb_fctn (workst, display, window)

id workst;Display *display;Window window;

{/* function body */

}

Xt applications may need to use the macro XtWidget(window) to findthe widget associated with workst.

The gmsWinExt( ) function sets the Workstation/Window extent (size) inDevice Coordinates (usually pixels). The two idPoint argumentsrepresent the lower left and top right corners of theWorkstation/Window. This function returns 1 for success, 0 for failure.The Workstation/Window is resized immediately when this function iscalled. The workst argument of the gmsWinExt( ) function can beeither an existing Workstation/Window object or a Workstation/Windowclass retrieved by the gmsQDefaultWs( ) function. If aWorkstation/Window class is passed, then the attributes of theExemplar object are set (which sets the attributes of all subsequentWorkstation/Windows opened).



NOTE: The gmsWinExt( ) function supersedes the obsoletegmsWinDims( ) function.

The gmsWsWind( ) function sets the Workstation/WindowVirtual-window using Normalized Device Coordinate Points.

The gmsWsWindXY( ) function sets the Virtual-window for theWorkstation/Window using the given Normalized Device Coordinates.

The gmsWsPort( ) function modifies the Port using Point objectscontaining Device Coordinates (pixel coordinates).

The gmsWsPortXY( ) function modifies the Port using the given DeviceCoordinates (pixel coordinates).

The gmsWinFlags( ) function turns a Workstation/Window’s bit flags toG_ON or OFF. The bits are:

gmsWinFlags( ) — Valid Codes for "bit" Argument

Code DescriptionG_WIN_CONCAVE_FILL Use SL concave-fill algorithm

(SGI-IRISGL only)G_WIN_DESTROYED Window has been destroyedG_WIN_DBUFF_ERASE Erase Update Double Buffer ModeG_WIN_DBUFF_CLEAR Clear Redraw Double Buffer ModeG_WIN_FULL_SCREEN Adjust Window size to use full screenG_WIN_KEEPASPECT Maintain aspect ratio under resize

(SGI-IRISGL only)G_WIN_MATRIX_HW Enable matrix hardware routines

(SGI-IRISGL only)G_WIN_NOBANNER Window has no border/bannerG_WIN_NOPASTE Disable middle mouse button for control

of cut and paste communicationG_WIN_NOPOSITION User positions and sizes Window with

the mouse (SGI-IRISGL only)G_WIN_NORESIZE Disallow Window resize (SGI-IRISGL

only)G_WIN_WORKSTATION Window of first Workstation/Window



The gmsWinIconName( ) function stores name in theWorkstation/Window’s icon name field; this name is displayed in thewindow-manager window’s icon when the window-manager window isiconized.

The gmsWinMap( ) function maps the Workstation/Window (makes itvisible). If raiseflag is set to G_ON, the function brings it to the top ofthe Workstation/Window stack. For the SGI-IRISGL version, this isequivalent to gmsWinPop( ). For Windows workstations thegmsWinMap( ) function behaves as follows:



:

gmsWinMap( )

Case 1

before Workstation/Window visible or invisible, with or without focus

action call gmsWinMap(ws, G_ON)

result Workstation/Window moved to top of z-order, receives focus

Case 2

before Workstation/Window minimized (visible or invisible)

action call gmsWinMap(ws, G_ON)

result Workstation/Window moved to top of z-order, receives focus

Case 3

before Workstation/Window is visible

action call gmsWinMap(ws, G_OFF)

result no effect

Case 4

before Workstation/Window is invisible


result Workstation/Window position restored; the window that had focus retains it

Case 5

before Workstation/Window minimized (visible or invisible)




The gmsWinPop( ) function raises the Workstation/Window to the top ofthe Workstation/Window stack.

The gmsWinPush( ) function lowers the Workstation/Window to thebottom of the Workstation/Window stack. For Windows workstations thefunction behaves as follows:

The gmsWinSetFocus( ) function sets the keyboard input focus to thespecified Workstation/Window. If window is nil, theWorkstation/Window’s default Window is used. For the SGI-IRISGLversion, this function changes the Workstation/Window to the "currentdrawing Window."

result Workstation/Window moved next to top of z-order; the window that had focus is made top and retains focus

gmsWinPush( )

Case 1

before Workstation/Window is visible and has focus

action call gmsWinPush(ws)

result Workstation/Window moved to bottom of z-order, retains focus

Case 2

before Workstation/Window visible

action call gmsWinPush(ws)

result Workstation/Window moved to bottom of z-order; the window that had focus retains it



The gmsWinUnmap( ) function unmaps the Workstation/Window (makes it invisible). For the SGI-IRISGL version of SL-GMS, this is equivalent to gmsWinPush( ). For Windows workstations the gmsWinUnmap( ) function behaves as follows:

gmsWinUnmap( )

Case 1

before Workstation/Window is visible and has focus

action call gmsWinUnmap(ws)

result Workstation/Window made invisible; the new top window receives focus

Case 2

before Workstation/Window is visible

action call gmsWinUnmap(ws)

result Workstation/Window made invisible; the window that had focus retains it


Workstation/Window — background color


SUMMARY

set and query the window background color for a workstation

NAME

gmsQWsBackgroundColor( ), gmsWsBackgroundColor( )

SYNTAX

intgmsQWsBackgroundColor(workst, color, platform_flag)

id workst; /* Workstation/Window */int *color; /* return color */int *platform_flag;/* return flag indicating

platform color */

intgmsWsBackgroundColor(workst, index, type)

id workst; /* Workstation/Window */int color; /* SL-GMS color index or

platform color */int type; /* background color type to use

*/

DESCRIPTIONThe gmsWsBackgroundColor( ) function is used to set the Windowbackground color for the indicated Workstation. It also sets the defaultModel background color. Three different types can be used to specifythe background color: index, color, and system (type codesG_BKGR_TYPE_INDEX, G_BKGR_TYPE_COLOR, andG_BKGR_TYPE_SYSTEM).G_BKGR_TYPE_INDEX sets the background color to the specifiedSL-GMS color index. G_BKGR_TYPE_COLOR sets the backgroundcolor to a platform-specific color (i.e., a COLORREF orPixel). G_BKGR_TYPE_SYSTEM sets the background color to thewindow manager-defined Window background color (not supported



under X Windows). For the system type, the color parameter isignored, however, it is recommended that G_TCOLOR_NULL beused. A return value of 1 indicates success and 0 indicates failure. IfG_BKGR_TYPE_SYSTEM is used under X Windows, a failure code of0 will be returned.

The gmsQWsBackgroundColor( ) function will return the currentbackground color for the indicated Workstation in the color variable. Ifthe returned color is a platform-specific representation, a 1 is returnedin the platform_flag.Otherwise, the returned color is an SL-GMS color index and a 0 isreturned in platform_flag. The color will be a platform-specific coloronly if the background color was set with a platform-specific color. Thiswill happen if a Window is created with a background color (onWindows NT) and passed in to gmsWorkst( ) or a platform-specificcolor is passed to gmsWsBackgroundColor( ). A return value of 1indicates success and 0 indicates failure.

NOTE: The private global variable g_backgrcolor, used to controlthe background color, has been removed. The newbackground color functions provide the necessary access to aworkstation’s background color.

The Window/Model will not be redrawn automatically after thebackground color is changed.

The background color will follow the definition of the color index towhich it is set (if it is set to a SL-GMS color index). For example,assume the background color is set to index 4, and that index 4 isblue. If the color for index 4 is then changed to pink, the backgroundcolor will change to pink also. However, the pink background will notautomatically display. Some action must be taken to force the screen toredraw.

For Windows NT only, the background color for a Workstation/Windowmay also be set by creating a window manager Window outside ofSL-GMS. The color of the background brush stored in the window classwill determine the background color for SL-GMS. SL-GMS gets thebackground brush when the Window is passed to gmsWorkst( ). Onlya solid brush will work; any other type of brush will cause SL-GMS touse the default background color.



On X Windows, if a Window is passed in to gmsWorkst( ), SL-GMSdoes not determine the background color from it. Because of this, thevalue obtained from gmsQWsBackgroundColor( ) is undeterminedunless the background color is set by callinggmsWsBackgroundColor( ).

If a Workstation/Window is created by SL-GMS (not passed in), and thefunction gmsWsBackgroundColor( ) is not called, the backgroundcolor is set to the SL-GMS color index 0.


Workstation/Window — bitplanes


SUMMARY

implement bitplane masking

NAME

gmsWsBitplaneMask( ), gmsWsColDef( ), gmsQWsBitplaneMask( )

SYNTAX

intgmsWsBitplaneMask (workst, mask, color0)

id workst; /* Workstation/Window */int mask; /* bitplane writemask */

intgmsWsColDef (workst, index, red, green, blue, mask)

id workst; /* Workstation/Window */int index; /* color index */double red; /* red color component*/double green; /* green color component */double blue; /* blue color component */int mask; /* bitplane writemask */

intgmsQWsBitplaneMask (workst)


DESCRIPTIONBitplane masking is a feature that is used to load a Model into a Viewthat is associated with a set of protected bitplanes and a set of colors.Bitplane masking also provides transparency for color index 0 in eachset of bitplanes.

Situations in which bitplane masking is useful include:



1. Objects move over a complex background such as a map.Bitplane masking increases performance because the map isnot redrawn each time an object moves over it.

2. A set of Models that must appear to be transparent whenstacked on top of each other. If an object that is filled with apattern has background areas of color index 0, the back-ground areas of the fill pattern allow portions of underlyingobjects to show through the holes in the fill pattern.



3. Animation in which an object must appear to go between or behind other objects. The set of planes an object is drawn in determines its relation to objects in other sets of planes. For example, an object drawn in the back two planes appears to be behind objects that overlap it which are drawn in more forward planes.

The transparency of color 0 is also useful with softwaredouble-buffering. When a background object of color 0 is grouped withanother object that moves, the background object will be invisible if theGroup is loaded into a set of bitplanes.

Bitplane masking is activated with the G_WS_PLANE_MASKINGWorkstation option.

The gmsWsBitplaneMask( ) function sets the Workstation/Window’swritemask. Setting the bitplane writemask provides the capability ofdrawing objects in specified bitplanes.

The gmsWsColDef( ) function sets a Workstation/Window color mapentry for the given index, with the given bitplane writemask, mask. A 0mask is means that all bitplanes are write-enabled. mask is 24-bits.It must contain exactly one consecutive string of 1-bits, for example,"0xe0." This mask is used as an argument to an SGI-IRISGLwritemask call, and is saved as the "current bitplane mask." Forconvenience, a writemask of 0 is construed as 0xffffff, that is, nowritemask. red, green, and blue are doubles, giving the red, green,and blue components of the color in the range 0.0 to 1.0. mask is the



bitplane writemask for which the color is being set. index is the colorindex. The color index is adjusted according to the bitplane mask. Ifthe index is a number not in the mask, it is adjusted to be a rangewithin the mask. If it is already in the mask, no adjustment is made.Adjusting index allows a color in a masked set of bitplanes to varyaccording to the color in the lower bitplanes.

The gmsQWsBitplaneMask( ) function returns theWorkstation/Window’s writemask.

EXAMPLEworkst_options = G_WS_PLANE_MASKING;gmsWsDefaultOpts(workst_options);

Then, the "colordef.dat" file is modified to define the desired groups ofbitplanes and their associated colors. The writemask is defined in thefifth field of a "colordef.dat" line as an integer in either binary orhexadecimal form. The writemask must contain exactly oneconsecutive string of 1-bits, for example "11100000." Note that thenumber of colors in a bitplane mask is limited to

2^(number of planes) - 1

with indexes ranging from 1 to 2^(number of planes) - 1. Color 0 is"transparent" for all but "back" bitplanes.

"colordef.dat" file — sample 1 (8 plane display)

colors for back two planes(could have a maximum of 4 colors, no transparency for back planes)

for the world map

1 0.0 0.0 0.0 00000011 black map lines2 0.0 0.6 1.0 0x3 blue background



colors for middle three planes(could have maximum of 7 colors + 1 for transparency)

for the satellite

1 1 0 0 00011100 red2 .5803920.3 0 00011100 brown3 .6 .6 .6 00011100 gray4 .996078.684314.73921600011100 pink5 .946667.763137.21372500011100 tan6 0. 0.0 0.0 0x1c black

colors for front three planes(could have maximum of 7 colors + 1 for transparency)

for the elipsoid fill pattern area

1 0.0 0.0 0.0 0xe0 black2 0.0 1.0 0.0 11100000 green3 1.0 0.0 1.0 0xe0 purple

In the above example there are three writemasks. The first writemaskuses two bitplanes for a total of four colors. The second and thirdwritemasks each use 3 bitplanes for a total of seven colors each. Thetotal number of possible colors for the example "colordef.dat" is 18 ofwhich 11 are defined.

"colordef.dat" file — sample 2 (8 plane display)0 0.0 0.0 0.0 black1 1.0 1.0 1.02 0.0 0.0 1.03 0.1 0.2 0.34 0.5 0.5 0.5 medium grey5 0.3 0.3 0.36 0.4 0.4 0.47 1.0 1.0 1.08 0.0 0.0 0.09 1.0 1.0 1.010 0.0 0.0 1.011 0.5 0.25 0.0



colors for front (panel) planes(could have maximum of 7 colors + 1 for transparency)

1 1.0 0.0 0.0 11100000 red2 0.0 0.0 0.0 0xe0 black3 0.1 0.2 0.3 0xe0 dark blue-grey4 0.5 0.5 0.5 0xe0 grey5 0.3 0.3 0.3 0xe0 grey6 0.4 0.4 0.4 0xe0 grey7 1.0 1.0 1.0 0xe0 white

The second example "colordef.dat" file is from the avionics on-lineexample.1 The avionics "colordef.dat" file uses one writemask thatoccupies the front three bitplanes which leaves five bitplanes for normaluse. Five bitplanes allow 32 colors of which 11 are defined. Theavionics "colordef.dat" file also changes the color of index 0 from itsdefault value of white to black.

Finally, a writemask is associated with a View through the View name.Each View that is to use a bitplane writemask is given a name thatbegins with "_vm" and ends with the hexedecimal value of thewritemask. For example, a View named "_vm_map_0xe0" is drawnwith the writemask "0xe0". Typically, as each View is created, theModels for the View are loaded.

1. The avionics on-line example is available only on the SGI-IRISGL platform.



EXAMPLEback_mask = 0x3;front_mask = 0xe0;prefix = "_vm";

/* setup view with back writemask */

modelname = "back_model";sprintf(viewname, "%s_%s_0x%x", prefix, modelname,

back_mask);gmsView(viewname, nil);

/* load Model into View */gmsMGet(modelname, modelname);gmsEndView( );

/* setup View with front write mask */modelname = "front_model";sprintf(viewname, "%s_%s_0x%x", prefix, modelname,

front_mask);gmsView(viewname, nil);

/* load Model into View */gmsMGet(modelname, modelname);gmsEndView( );

The use of bitplane masking can result in visual side effects on displaysthat support only one hardware color map (a color map is a table thatrelates pixel values to screen colors). As an SL-GMS application thatuses bitplane masking is started, other windows on the display maychange color as they are forced to use the SL-GMS color map.

EXAMPLEThe following function calls can be used to cause the redrubber-banding echo and the black/white popup menus to be drawn inan overlay (a masked set of bitplanes).

As an example, if bitplanes 6 and 7 are used for overlays, assuming 8bitplanes, the mask would be 0xc0.

At initialization the color map for these bitplanes is set:



gmsWsColDef(ws, 1, 1., 0., 0., 0xc0); /* red */gmsWsColDef(ws, 2, 0., 0., 0., 0xc0); /* black */gmsWsColDef(ws, 3, 1., 1., 1., 0xc0); /* white */

Before a menu is popped up, a bitplane writemask is set; next, themenu is turned on, and the bitplane writemask is reset:

gmsWsBitplaneMask(ws, 0xc0);gmsVis(menu, 1);gmsBitplaneMask(ws, 0, 0);

The number of colors in a bitplane writemask is limited to

2 (number of bitplanes) - 1

with indexes ranging from 1 to 2(number of bitplanes)-1. Color 0 is"transparent."

When an SL-GMS bitplane writemask is in effect, all color indexes areinterpreted as being in the bitplanes specified by the current writemask.A color index below the writemask is transformed up; a color indexabove the writemask is set to the last overlay color in the writemask.

Views with bitplane maskingBitplane masking is implemented in SL-GMS by adding the capability tothe View object, as well as by the functions described above. A Viewcan contain a bitplane writemask; if a writemask is present, the Viewsets the bitplane writemask before drawing.

In the present implementation of SL-GMS 5.x, the bitplane writemask istemporarily put in the View name field, using the following convention:if the View name begins with "_vm" then it contains a writemask; thewritemask is a substring beginning with "0x" at the end of the Viewname. For example, a View named "_vm_panel0xe0" is drawn with thewritemask "0xe0."

The avionics on-line example provides source and executables thatillustrate the use of double-buffering and bitplane masking in SL-GMS.This on-line example uses front bitplanes for the "panel" Model.

DIAGNOSTICSIf a Workstation/Window having overlay objects drawn is moved oruncovered, the objects are redrawn subject to the writemask in force at



the time of the redraw; the result may be that overlay objects are drawnin the normal planes.


Workstation/Window — coordinate conversion


SUMMARY

convert a point in Device Coordinates to SL-GMS Internal Coordinates

NAME

gmsWsPointDCToIC( )

SYNTAX

intgmsWsPointDCToIC (workst, point)

id workst; /* Workstation/Window */idPoint point; /* point in Device Coords */

DESCRIPTIONThe gmsWsPointDCToIC( ) function converts a point in DeviceCoordinates (DC) to Internal Coordinates (IC) for a givenWorkstation/Window. The Internal Coordinates replace the DeviceCoordinates in the Point object provided to the function.

DIAGNOSTICSThe gmsWsPointDCToIC( ) function returns 0 for failure.

EXAMPLEThe mouse is moved to a location over an object in a Model and clicked.The window handle, and the location of the mouse in DeviceCoordinates, are provided by system-dependent event handlers. Findthe object in the Model that is under the mouse.

idPoint pt;id workst, locevent, vu, obj;...

/* Find Workstation/Window associated withsystem-dependent window handle */

workst = gmsQWorkst((unsigned long)window_handle);



/* Create a point object that containsthe mouse coordinates */

pt = (idPoint)pntNewXY((coordVar)mouse_x,(coordVar)mouse_y);

if (!pt) return;

/* Convert DC -> IC */gmsWsPointDCToIC(workst, pt);

/* Create a GMS Locator event */locevent = (id)gmsEvent(G_LOC_PRESS, workst, NULL);

/* Store IC values in the event */gmsEvPoint(locevent, pt);pntFree(pt)

/* Find View and store it in the event */vu = gmsQWsView(workst, locevent);gmsEvView(locevent, vu);

/* Find object in Model */obj = gmsFindObject(locevent, 3.0, 0);gmsObjFree(locevent);

if (!obj) return;

SEE ALSOgmsQWorkst( ), gmsQWsView( )


Workstation/Window — events


SUMMARY

functions to set up Workstation/Window Event handlers or queryWorkstation/Window or timer Event masks

NAME

gmsWsEventFctn( ), gmsWsEventMask( ), gmsQWsEventMask( ), gmsWsTextEditObj( ), gmsWsKbdFilterFctn( ), gmsWsLowEventFctn( ), gmsNonWsLowEventFctn( ), gmsWsSynchronize( )

SYNTAX

intgmsWsEventFctn (workst, eventcode, fctn)

id workst; /* Workstation/Window which is toreceive Event */

int eventcode; /* type of Event */int (*fctn)( ); /* callback function to be invoked

upon Event */

intgmsWsEventMask (workst, eventcode, action)


int eventcode; /* type of Event */int action; /* G_ENABLE or G_DISABLE */

intgmsQWsEventMask (workst, event_type)


int event_type; /* type of Event */



intgmsWsTextEditObj (workst, textobj, maxchars,

promptstring, initstring, dispatch_mode, fctn)id workst; /* Workstation/Window which is to

receive Event */id textobj; /* id of Text/TextRect object */int maxchars; /* max chars to display */char *promptstring;/* prompt string */char *initstring;/* initial string to display with

prompt */int dispatch_mode;/* dispatch_mode =


int (*fctn)( ); /* callback function to be invokedupon Event */

intgmsWsKbdFilterFctn (workst, fctn)

id workst;idLinkRef (*fctn)( );

intgmsWsLowEventFctn (workst, fctn)

id workst;int (*fctn)( );

intgmsNonWsLowEventFctn (fctn)

int (*fctn) ( );

intgmsWsSynchronize (workst)

id workst;



DESCRIPTIONThe gmsWsEventFctn( ) function is invoked from an applicationprogram. This function sets up Event handlers on aper-Workstation/Window basis by passing the object pointer for thedesired Workstation/Window (workst).

The eventcode argument specifies the type of Event the Event-handler(fctn) will receive. The valid Event codes are listed in the section Eventcodes, in the chapter Event Handling, of the SL-GMS Reference. If the fctn pointer passed is0, this Event is disabled on the given Workstation/Window.

All Event-handlers may be established by using the gmsWsEventFctn( )function except for one: the Event-handler for String Events. To definean Event-handler for String Events gmsWsTextEditObj( ) is used.

NOTE: When using the SL-SMS Event-handling mechanism (i.e.,when gmsInitStates( ) is called) gmsWsEventFctn( )should not be called by the application program, since doingso interferes with SL-SMS’ Event-handling capability.

The gmsWsEventMask( ) function enables or disables a type of Event inthe Workstation/Window Event mask.

The gmsQWsEventMask( ) function returns the currentWorkstation/Window Event mask, either G_ENABLE or G_DISABLE.

The gmsWsTextEditObj( ) function defines an object (textobj must bea Text or Text Rectangle object) as the echo object for Text input andediting. This function also becomes the focus for all KEY_PRESSEvents and is responsible for dispatching a STR_DONE Event byexecuting the given callback function. This function should not be usedin SL-SMS.

The gmsWsTextEditObj( ) function sets up an Event-handler for StringEvents on the Workstation/Window, workst, using the specified textobj.The function returns 1 for success, 0 for failure.

The maxchars variable represents the maximum number of charactersto echo in the Text or Text Rectangle object, and is used to preventoverflow.



The promptstring and initstring arguments together define the text thatwill actually be displayed. The text displayed after a <RETURN> isdetermined by dispatch_mode.

The dispatch_mode can have one of three valid values:

1. G_MULTI_EVENT — after a <RETURN> redisplaypromptstring and initstring;

2. G_ONE_SHOT — after a <RETURN> do not redisplaypromptstring and initstring (i.e., leave text that has beenentered);

3. G_ONE_SHOT_CLEAR — after a <RETURN> do not redis-play promptstring and clear initstring (i.e., clear text that hasbeen entered).

The gmsWsKbdFilterFctn( ) function installs a Workstation/WindowKeyEvent filter function. This function does not enable any Events.

The gmsWsLowEventFctn( ) function is used to establish anEvent-handler to intercept Workstation/Window Events before SL-GMSreceives them. The gmsWsLowEventFctn( ) function registers alow-level Event-handler with SL-GMS. The registered function is givena chance to check each Event, and should return to SL-GMS a signedinteger flag instructing SL-GMS on further processing of the Event.

To enable total application access to the Event Queue, four parametersare passed to the application’s low-level Event-handler: a pointer to theX Display structure, an X window id, a pointer to the XEvent union, anda flag indicating SL-GMS "intentions" for the Event.

Return Value Description 1 dispatch and process the Event 0 do not dispatch or process the Event-1 dispatch, but do not process, the Event; the

distinction is that the application may wish to suppress SL-GMS processing while allowing, for instance, toolkit reponse



The gmsProcessLowEvent( ) function is used to pass events toSL-GMS when an application event loop function external to SL-GMS isbeing used (flag value non-zero in the call togmsExternalEventLoop( )). The gmsProcessLowEvent( ) functionis system-dependent and is only used with the SL-GMS interface to Xtand X at present. Under Xt and X, gmsProcessLowEvent( ) acceptsa pointer to an Xevent structure as its argument. The event structureis then checked by SL-GMS to see if any SL-GMS object has an interestin the event. If SL-GMS had no interest in the event, a value of 0 isreturned. Alternatively, if SL-GMS was interested in the event and tooksome action, a non-zero value is returned fromgmsProcessLowEvent( ) to the application. In either case,event-handler functions may be specified to SL-GMS through the use ofeither the gmsWsLowEventFctn( ) or thegmsNonWsLowEventFctn( ) functions.

In the case of SL-GMS interest in the event, if an event-handler wasregistered with SL-GMS through the use of gmsWsLowEventFctn( ),

Flag Value Case Description

1 normal SL-GMS has not yet looked at the Event. It will probably be "dispatched," which in the case of Xt means calling XtDispatchEvent( ). Then, of course, the Xt Intrinsics broadcasts the Event to all "interested parties" which may or may not include application, SL-GMS, or high-level toolkit callbacks.

0 "flush" SL-GMS is attempting to "throw away" the Event. In some cases it may prove fatal for the application to try processing these Events.

-1 "modified flush" SL-GMS is attempting to respond to the "most recent" (e.g., PointerMotion) or "only one" (e.g., Expose) Event. The application’s low-level Event handler previously indicated that SL-GMS should process a related Event; the handler in this case is essentially being notified and should simply return.



this registered event-handler function allows the application to have achance to check and/or take some action regarding each event thatSL-GMS has an interest in before SL-GMS does anything with theevent. This may include preventing SL-GMS from taking actionregarding the event if that is appropriate for the particular situation inthe application. In the case of no SL-GMS interest in the event, if anevent-handler function was registered with SL-GMS through the use ofgmsNonWsLowEventFctn( ), this registered event-handler functiongives the application a chance to check and/or take some actionregarding this event. Alternatively, the application’s event loop functionmay be designed to process the events not associated with SL-GMSand the use of gmsNonWsLowEventFctn( ) to register anevent-handler function is superfluous. If no event-handler function wasspecified to SL-GMS through use of either gmsWsLowEventFctn( ) orgmsWsLowEventFctn( ), SL-GMS dispatches and processes theevent it has been handed.

NOTE: The gmsWsLowEventFctn( ) function is currently availableon X platforms only and will be provided on other platforms ina future release of SL-GMS.

The gmsNonWsLowEventFctn( ) function is used to establish anEvent-handler to receive Events that are not associated with anSL-GMS Workstation/Window. Applications using gmsMainLoop( ) canuse gmsNonWsLowEventFctn( ) to register an Event-handler toprocess Events in which SL-GMS has no interest. The Event-handlerexpects a single XEvent parameter. A sample Event-handler is:

intNonGmsWindowCB (e)

XEvent *e;{

printf("\n%s: NonGmsWindowCB( ): display=’0x%x’,window=’%d’, type=’%d’\n\n",__FILE__, e->xany.display,e->xany.window, e->type);

return 1;}



The gmsWsSynchronize( ) function synchronizes the low-levelcommand stream.

DIAGNOSTICSThe gmsWsEventFctn( ) and gmsWsTextEditObj( ) functions should notbe called when using SL-SMS (i.e., when gmsInitStates( ) is alsocalled).

SEE ALSOgmsStTextEditObjName( ), gmsStTextEditObj( )

The section Event-handler functions outside SL-SMS in the SL-GMSReference provides additional information about thegmsWsEventFctn( ) function.


Workstation/Window — object


SUMMARY

initialize, activate, deactivate, and change cursor echo type forWorkstation/Window objects

NAME

gmsWorkst( ), gmsWsDefaultOpts( ), gmsWsAct( ), gmsWsDeact( ), gmsWsClose( ), gmsWsEchoMask( ), gmsWsLocEcho( ), gmsWsProcArgs( ), gmsWsProcArgsStr( )

SYNTAX

idgmsWorkst (cls, name, conn, type, wind, code)

struct ClassDef *cls;/* pointer to Workstation/Window class */

char *name; /* name of Workstation/Window */char *conn; /* connection for Workstation/Window

(DISPLAY) */char *type; /* Workstation/Window type */char *wind; /* window id */int code; /* Workstation options */

intgmsWsDefaultOpts (code)

int code; /* Workstation options */

intgmsWsAct (workst)


intgmsWsDeact (workst)


intgmsWsClose (workst)




intgmsWsEchoMask (workst, mask)

id workst; /* Workstation/Window */int mask; /* Locator echo mask */

intgmsWsLocEcho (workst,view,echotype,echoconst,pointlist)

id workst;id view;int echotype;int echoconst; /* echo constraints (in x or y

dimensions) */idLinkRef pointlist; /* number of Points depends upon echotype

*/

idgmsWsProcArgs (argc, argv, wsopts)

int argc;char **argv;int wsopts;

idgmsWsProcArgsStr (argstr, wsopts)

char *argstr;int wsopts;

DESCRIPTIONThese functions create or modify Workstation/Window objects. AWorkstation/Window object must be created and activated before anyView can be displayed.

The gmsWorkst( ) function creates Workstation/Window objects. Inbasic X application programs using SL-GMS, gmsWorkst( ) is called tocreate a window-manager window. An Xt application program, however,creates all widgets (and associated window-manager windows) it needs andthen passes the id of the drawing area to gmsWorkst( ).

The cls argument specifies the class of the Workstation/Window, andshould be the return value of the gmsQDefaultWsClass( ) function.

The name argument is an arbitrary (non-optional) name which may beused to reference the Workstation/Window using gmsFindByName( ).



The conn argument specifies a physical or logical connection to thedisplay device. Under Xt, the conn argument is ignored because thedisplay connection is found from the Xt widget specified as the windargument (discussed below). Under X, when an id of an X window isspecified as the wind argument, the conn argument must be specifiedas the X display connection id associated with the X window. When thewind argument is null under X, the conn argument is assumed to be thename of an X display connection to open. If both the conn and windarguments are null strings under X, the X display connection to open isfound from the DISPLAY environment variable, for example, "unix:0.0".

The window argument, wind, is used to specify a pre-existing X windowor Xt widget where SL-GMS is to draw dynamic graphics. The windargument, if given, must be an X window or Xt widget id.

NOTE: An Xt application must wait for the first Expose event beforecalling gmsWorkst( ) (i.e., the gmsWorkst( ) function mustbe passed a "realized" widget).

Both conn and wind should be converted to strings (using sprintf( )) beforepassing them to gmsWorkst( ). For example,

char string_id[32];sprintf(string_id, "%lu", window_id);gms_workst = gmsWorkst(gmsQDefaultWsClass( ), "ws1",

"", "default", string_id,flags);



A null string passed as the wind argument means that SL-GMS will open a window-manager window using the 80% Rule2 if no Workstation/Window attributes3 are in effect.

NOTE: SL-GMS properly handles all interrupts and Events whenattached to a single server or physical device. Multipleservers independently communicating with a singleapplication process will be supported in a future release ofSL-GMS.

The Workstation/Window type is not normally used, and should be setto a NULL string (" ") . If type is set to "ws", and name is set to "ws",and the Workstation Input Mode is ON, then a window is not opened.

The code argument defines special options on the newly-createdWorkstation/Window as shown in the following tables.

2. The 80% Rule is: Use a window placed in the center of the screen display, utilizing 80% of the pixels in the x direction and the number of pixels necessary in the y direction to achieve a 3 to 4 aspect ratio, with a 3-line Message Area above the graphics portion for text output and a window banner.

Valid Bit Values for gmsWorkst( ) “code" argument on Unix/X11 Systems

Decimal Hex Mnemonic Description1 0x0001 G_WS_DBUFF_ERASE enable software

double-buffering (Erase Update Mode)

2 0x0002 G_WS_NO_HARDWARE do not use special hardware-drawing routines

8 0x0008 G_WS_DBUFF_CLEAR enable software double-buffering (Clear Redraw Mode)



3. Workstation/Window attributes are changed with the functions described in the section Workstation/Window — attribute changes on page -439.

16 0x0010 G_WS_LOOKUP_COLORS use the X default color map and allocate colors in read-only mode to allow color map sharing (color map lookup by the X server); i.e., eliminate flashing which occurs when the cursor is moved between windows

32 0x0020 G_WS_FULL_SCREEN size Window to use full screen

64 0x0040 G_WS_KEEP_ASPECT constrain Window aspect ratio to initial setting

1024 0x0400 G_WS_BW_REV reverse black and white colors

4096 0x1000 G_WS_POP_RASTER set gmsPop*( ) functions to use rasters

8192 0x2000 G_WS_POP_CLIP set gmsPop*( ) functions to use clip rectangle

16384 0x4000 G_WS_CONCAVE_FILL use SL concave fill algorithm (SGI-IRISGL only)

32768 0x8000 G_WS_BPAD enable bitpad devices(SGI-IRISGL only)

524288 0x80000

G_WS_MATRIX_HW enable matrix hardware routines(SGI-IRISGL only)

65536 0x10000

G_WS_TEXT_BCOLOR enable Text background color


continued)

Decimal Hex Mnemonic Description



131072 0x20000

G_WS_CACHE_GC enable X Graphics Context caching(HP-UX only)

262144 0x40000

G_WS_NOPASTE disable middle mouse button for control of cut and paste

1048576 0x100000

G_WS_PLANE_MASKING enable Bitplane masking

8388608 0x800000

G_WS_EXPOSE_RECT enable expose-rectangle(SGI-IRISGL only)

More than one option is entered by bitwise OR-ing their values together.


continued)

Decimal Hex Mnemonic Description



The Workstation/Window object exhibits the following default behavioron 32-bit Windows systems:

1. Text is always drawn with a background color.

2. The gmsPop*( ) functions always use rasters.

3. The middle mouse button is not used in cut and paste opera-tions.

The gmsWsDefaultOpts( ) function allows an application to establishdefault Workstation/Window options that hold for anyWorkstation/Window created thereafter via the gmsWorkst( ) function.Any code arguments given with the gmsWorkst( ) function are OR’dwith the defaults given in the gmsWsDefaultOpts( ) function.

Workstation/Windows are activated by default when created. In asystem with multiple Workstation/Windows, specificWorkstation/Windows may be activated or deactivated as desired. Noobjects are drawn on Workstation/Windows that are not active.

By default, all Views are associated with the first Workstation/Window.When a second Workstation/Window object is created, a View must beassociated with this Workstation/Window before anything can be

Valid Bit Values for gmsWorkst( ) "code" argument on 32-bit Windows

Decimal Hex Mnemonic Description1 0x0001 G_WS_DBUFF_ERASE enables software

double-buffering (Erase Update Mode)

8 0x0008 G_WS_DBUFF_CLEAR enables software double-buffering (Clear Redraw Mode)

32 0x0020 G_WS_FULL_SCREEN sizes Window to use full screen

64 0x0040 G_WS_KEEP_ASPECT constrains Window aspect ratio to initial setting

1024 0x0400 G_WS_BW_REV reverses black and white colors

More than one option is entered by bitwise OR-ing their values together.



displayed upon it. Workstation/Windows are associated with particularViews by using the gmsWsNum( ) function.

The gmsWsAct( ) and gmsWsDeact( ) functions, respectively, activateand deactivate a Workstation/Window.

The gmsWsClose( ) function destroys the Workstation/Window.

The gmsWsEchoMask( ) function sets the bitplane writemask used forLocator echo. If mask is 0 (zero), the Locator echo is XOR’d onto thedisplay. If mask is non-zero, the system’s Locator echo writemask isused.

The gmsWsLocEcho( ) function sets the Locator echo type for thegiven Workstation/Window. The Locator echo type controls the type ofechoing for the mouse cursor. Valid codes for the echotype argumentare provided in the table on the following page.



gmsWsLocEcho( ) — Valid Codes for "echotype" Argument

Code DescriptionG_LOC_ECHO_DEFAULT normal (arrow)G_LOC_ECHO_LINE_1 single moving line; parameters:

one anchor pointG_LOC_ECHO_LINE_2 double (jointed) moving line;

parameters: two anchor pointsG_LOC_ECHO_LINE_3 double (jointed) moving line which

can be constrained in x or y dimension; parameters: two anchor points, one Reference Point to constrain tracking

G_LOC_ECHO_RECT_1 expanding rectangle (one fixed corner); parameter: one anchor point

G_LOC_ECHO_RECT_2 expanding rectangle which can be constrained in x or y dimension; parameters: one anchor point, one reference point to constrain tracking

G_LOC_ECHO_CORNERS_MOVE moving corners of a box (fixed size); parameters: two points specifying the extent of the box, one reference point "stuck" on the mouse

G_LOC_ECHO_RECT_MOVE moving box (fixed size); parameters: two points specifying the extent of the box, one reference point "stuck" on the mouse

G_LOC_ECHO_RECT_SCALE_PROP proportional scaling rectangle; parameters: two points specifying the extent of the rectangle, one reference point

G_LOC_ECHO_RECT_SCALE_UNPROP

disproportional scaling rectangle; parameters: two points specifying the extent of the rectangle, one reference point



The echoconst argument to the gmsWsLocEcho( ) function can beG_LOC_ECHO_HORIZ, G_LOC_ECHO_VERT, or 0. The echoconstargument restricts the movement of the echo to the x or y dimension (orin the case of 0, provides no constraint at all). The pointlist argumentcontains Points to be used as "anchors," when such parameters arenecessary. If pointlist is nil, Locator echo is turned off.

The gmsWsProcArgs( ) function processes the switches in thecommand line, and uses the information obtained to create aWorkstation/Window. The options available are platform-dependentand are listed for both Unix X/11 and 32- bit Windows systems. Theseoptions are specified in the function’s third argument, wsopts. Thefunction returns a pointer to the Workstation/Window created, or thefirst Workstation/Window created if more than one Workstation/Windowis created.

NOTE: The switches used by gmsWsProcArgs( ) are reserved bySL-GMS and should not be used (for application-specificpurpose) by programs that call gmsMainInit( ).

G_LOC_ECHO_LINE_MOVE single moving line (no anchor point); parameters: two points specifying the extent of the line, one reference point "stuck" on the mouse

G_LOC_ECHO_PLINE_MOVE moving continuous (single) polyline; parameters: <n> points specifying the polyline points, one reference point "stuck" on the mouse

G_LOC_ECHO_DJPLINE_MOVE moving disjoint (noncontinuous) polyline; parameters: <n> points specifying the polyline points, one reference point "stuck" on the mouse

gmsWsLocEcho( ) — Valid Codes for "echotype" Argumentcontinued)

Code Description



For non-C programming languages, or situations where the argc-argvmechanism is inconvenient or simply unavailable, thegmsWsProcArgsStr(argstr, wsopts) function can be used instead ofgmsWsProcArgs( ).

argstr is of type char *, where the character string containsspace-separated arguments. Quotes attempting to combine words intoone argument are not accounted for.

SEE ALSOgmsSetup( ), gmsWsNum( ), gmsView( ), gmsFindByName( ), gmsQDefaultWsClass( )

SL-GML COMMANDSname act

name deact


Workstation/Window — Window query


SUMMARY

query Workstation/Window Window attributes

NAME

gmsQWinBannerName( ), gmsQWinExt( ), gmsQWinIconName( ), gmsQWindowId( ), gmsQWorkst( )

SYNTAX

char *gmsQWinBannerName (workst)


intgmsQWinExt (workst, lower_left, top_right)

id workst; /* Workstation/Window */idPoint lower_left; /* corner of Window extent */idPoint top_right; /* corner of Window extent */

char *gmsQWinIconName (workst)


unsigned longgmsQWindowId (workst)


idgmsQWorkst (window_handle)

unsigned long window_handle;

DESCRIPTIONThe gmsQWinBannerName( ) function queries the name in the bannername field of the Workstation/Window. It returns theWorkstation/Window’s banner name if successful, 0 for failure.



The gmsQWinExt( ) function returns the extent (size) of aWorkstation/Window in the two Point objects, lower_left and top_right.The values in lower_left and top_right are in Device Coordinates(usually pixels) and may be accessed using pntX( ) and pntY( ). Thisfunction returns 1 for success, 0 for failure.

The gmsQWinIconName( ) function returns the icon name field of theWorkstation/Window, or 0 for failure.

The gmsQWindowId( ) function returns unsigned long, theWorkstation/Window’s system-dependent window id:under X — the Workstation’s window id, under SGI-IRISGL — the gid ofthe Workstation’s first window; under Windows NT — the windowhandle for a given Windows NT Workstation. The gmsQWindowId( )function returns 0 for failure.

The gmsQWorkst( ) functions returns the Workstation/Windowassociated with a given system-dependent window id. ThegmsQWorkst( ) function returns 0 for failure.


Workstation/Window — Workstation query


SUMMARY

query a Workstation/Window object for various Workstation attributes

NAME

gmsQDefaultWsClass( ), gmsQDisplayId( ), gmsQScreenExt( ), gmsQWidgetId( ), gmsQWsColDef( ), gmsQWsColormapIndex( ), gmsQWsColormapId( ), gmsQWsNumColors( ), gmsQWsEchoMask( ), gmsQWsPopMode( ), gmsQWsViewport( ), gmsQWsView( )

SYNTAX

idgmsQDefaultWsClass ( )

void *gmsQDisplayId (workst)


intgmsQScreenExt (workst, lower_left, upper_right, conn)

id workst; /* Workstation/Window object */idPoint lower_left; /* lower left coordinates */idPoint upper_right; /* upper right coordinates */

char *conn; /* Workstation connection */

void *gmsQWidgetId (workst)


idgmsQWsColDef (workst, index)

id workst; /* Workstation/Window */int index; /* color index */



intgmsQWsColormapIndex (workst, gms_index,

colormap_index)id workst; /* Workstation/Window object */int gms_index; /*SL-GMS color index

(used in Model) */unsigned long *colormap_index; /* returned

colormap index */

void *gmsQWsColormapId (workst)

id works; /* Workstation/Window */

intgmsQWsNumColors (workst)


longgmsQWsEchoMask (workst)


intgmsQWsPopMode (workst)


idgmsQWsViewport (workst)


idgmsQWsView (workst, locevent)

id workst; /* Workstation/Window */id locevent; /* Locator event */

DESCRIPTIONThe gmsQDefaultWsClass( ) function returns the id of the defaultWorkstation/Window class. Its return value is used as the firstargument in the gmsWorkst( ) function.



The gmsQDisplayId( ) function returns a Workstation/Window’ssystem-dependent display identifier: under X — theWorkstation/Window’s display id, under SGI-IRISGL — the gid of thefirst window of the Workstation/Window.

The gmsQScreenExt( ) function is used to obtain the extent of adisplay device, which allows an application to configure itself (forexample, to center a window-manager window on a screen) accordingto the available screen resolution.

The workst argument is a Workstation/Window object. A call togmsQDefaultWsClass( ) can be used in place of aWorkstation/Window object.

The screen extent in Device Coordinates is returned in the lower_leftand upper_right arguments. The pntX( ) and pntY( ) functions areused to obtain the coordinate values from each Point.

The conn argument specifies a physical or logical connection to thedisplay device. Under X, if the conn argument is a null string, thisvalue is taken from the DISPLAY environment variable, for example,“unix:0.0”.

The integer returned from the gmsQWidgetId( ) function issystem-dependent: under Xt — the widget’s handle is returned, underX — 0 (zero) is returned, and under SGI-IRISGL — the gid of the firstwindow of the Workstation/Window is returned.

The gmsQWsColDef( ) function creates and returns a ColDef objectcontaining the values for the color with the given index. ThegmsObjFree( ) function is used to free ColDef objects.

Given a Workstation/Window (workst), an SL-GMS color index(gms_index), and a pointer to an unsigned long integer(colormap_index), the gmsQWsColormapIndex( ) function will storein colormap_index the window colormap index associated with thatSL-GMS color index, if possible. The function returns 1 if it succeedsand 0 if it fails.

Currently, gmsQWsColormapIndex( ) is implemented in the XWorkstation layer only. When using this layer, the colormap indexobtained by gmsQWsColormapIndex( ) is a pixel value.

The gmsQWsColormapId( ) functions returns a Workstation/Window'ssystem-dependent colormap identifier: Under X, the



Workstation/Window's X colormap id is returned. All otherWorkstation/Window types, such as WindowsNT, currently return 0.

The gmsQWsNumColors( ) function returns the number of colorsdefined for a given Workstation/Window. The number of colors returneddoes not include colors allocated for bitmaps. If the workst argument isNULL, the number of colors returned is the maximum number of colorsdefined by any single Workstation/Window.

The gmsQWsEchoMask( ) function returns the Workstation/WindowLocator echo mask set by gmsWsEchoMask( ).

The gmsQWsPopMode( ) function returns the Workstation/Window’spreferred Pop-on/pop-off Mode using gmsPopOn( )/gmsPopOff( ):either G_WS_POP_RASTER or G_WS_POP_CLIP.

The gmsQWsViewport( ) function returns the extent of theWorkstation/Window's Viewport (an Extent object).

The gmsQWsView( ) function returns the View in which a Locator eventoccurred, given a Workstation/Window and a Locator event.

EXAMPLETo get the <x1, y1>, <x2, y2> pixel values for a Workstation/WindowViewport:

id wsvp = gmsQWsViewport(g_workst);printf("x1 = %d, y1 = %d, x2 = %d, y2 = %d\n",

extX1(wsvp), extY1(wsvp),extX2(wsvp), extY2(wsvp));



For a full-screen window on an SGI platform, output from the above code is:

x1 = 0, y1 = 0, x2 = 1267, y2 = 950

SEE ALSOgmsWorkst( ), gmsWsEchoMask( ), gmsPopOn( ), gmsPopOff( )


World Coordinates

World Coordinates

SUMMARY

create Points from World Coordinates; set World Coordinate ScaleFactor

NAME

gmsWPoint( ), gmsWPXY( ), gmsSWPXY( ), gmsWValue( ), gmsWCScale( ), gmsWCoordX( ), gmsWCoordY( )

SYNTAX

idPointgmsWPoint( )

idPointgmsWPXY (x, y)

double x, y;

intgmsSWPXY (point, x, y)

idPoint point;double x;double y;

intgmsWValue (x)

double x;

intgmsWCScale (scale)

double scale;

doublegmsWCoordX (x)

coordVar x;


World Coordinates

doublegmsWCoordY (y)

coordVar y;

DESCRIPTIONThese functions are used to create and set values for Points usingWorld Coordinates.

All Points used as arguments to the SL-GMS functions may be createdusing the gmsWPXY( ) function which takes floating-point arguments.The x and y values are multiplied by the World Coordinate Scale Factorand returned in a Point object.

The gmsWPoint( ) function creates a Point which is equivalent togmsWPXY(0.0,0.0). Once a Point is created, its x and y values are setusing gmsSWPXY( ) rather than creating another Point. Points createdusing these functions may be freed using the pntFree( ) function.

All Points generated by SL-GML commands are created using thegmsWPXY( ) function. The gmsWValue( ) function takes a doubleargument and converts it to an integer using the World CoordinateScale Factor. If this function is called with an argument of 1.0, itreturns the current World Coordinate Scale Factor.

The gmsWCScale( ) function sets the World Coordinate scaling factor.

The gmsWCoordX( ) function converts an SL-GMS Internal Coordinateto a World Coordinate.

The gmsWCoordY( ) function converts an SL-GMS Internal Coordinateto a World Coordinate.


World Coordinates

DIAGNOSTICSCurrently, gmsWCoordX( ) and gmsWCoordY( ) are identical, sincethere is only one World Coordinate Scale Factor. Futureimplementations may provide separate scale factors for the x and ydirections.

SEE ALSOgmsWind( ), gmsNPXY( ), pnt*( )

SL-GML COMMANDcoordscale real


Index
Symbols
".m2"/".m1" search order, States ...... 376"colordef.dat" file............................... 454"fontdef.dat" files............................... 160"userfctns.c"

example ...................................... 420.dat files

clearing out variables.................... 51.h files ............................................. 2, 66.m1 extension ................................... 242

Aabsolute

move ............................................... 5rotation............................................ 8scale ............................................. 10

AND operation .................................. 317apply transformation ........................... 13aspect ratio of window, setting of

Workstation......................... 473, 475autodeactflag, setting for State ......... 354

Bbackground color

of Model ........................................ 15of Workstation/Window ............... 448

Batch Erase Mode .............................. 80batcherase flag ................................... 78Bitmap

creation of ..................................... 20scaling of....................................... 20

Bitmap Write Mode ............................. 21bitpad devices

enabling for Workstation ............. 473Bitplane masking

enabling for Workstation ............. 474bitplane masking............................... 451BLOBs (Binary Large Objects) 245, 252,

253, 254, 255, 256

bus errorhandler for ...................................412with gmsVarDefine( )...................111

C

cacheSubModel ....................242, 243, 269

centerof object.........................................24

center of object vs center of extent26, 144CGM file format

converting to SL-GMS Model ......241Circle, create .......................................28class

class-definition structures..............66name strings

on-line file location...................31testing if object is a member .........30

clearGraphs ........................................285variables set up in .dat files...........51View ..............................................32Workstation ...................................32

Clear Redraw Mode ..................472, 475clearflag, setting for State .................353Clip Mode..........................................426clipping......................................426, 428clockwise flag ....................................341clone

Graphical Primitive object .............33Point ............................................293

example.................................294State class exemplar...................365

close, SL-GMS..................................344close_read( ) .....................................257close_write( ).....................................254Closed Spline object .........................350closure attribute...................................34ColDef objects

freeing from memory ...................162


colorbackground

of Model .................................. 15of Workstation/Window ......... 448

color index, setting RGB values for39of objects ...................................... 36Text background, enabling

Workstation for................ 473colordef.dat file ................................... 39colormap, setting for a Workstation .. 473command line

process arguments ................. 4, 478compare version numbers, SL-GMS 347complement ...................................... 317concave fill

enabling for Workstation ............. 473configuration number, SL-GMS ........ 347coordVar variable type...................... 293copy, objects....................................... 33crash handler, SL-GMS .................... 413create

Events......................................... 120current

Group............................................ 40Model ............................................ 40View .............................................. 40

cursor.................................................. 43cursor movement, elimination of flashing

on screen for............................... 473custom Markers ................................ 229

D

d1flag, setting for State..................... 354Datasource

classadding a method to ................. 53creation of ............................... 53installation into the run-time

environment ................ 53looking up given a name......... 53

Instance.........................................54messages................................59

datflag, setting for State ....................354debugging

dumps ...........................................68debugging utility

SL-SMS.......................................376default

SL-GMS search path...............62, 63Deferred Update Mode................66, 415definevars method.....................114, 384detectability attribute .........................436directories............................................62dispatch_mode..................................368display .................................................65display flag ........................................437double-buffering, enabling Workstation for

472, 475double-buffering, on an object.............69dump ...................................................68duration

time spent updating.....................281Dynamic Description

create ............................................71querying ........................................74

dynamicsend ................................................81in non-replicated SubModel ..........98initialize .........................................81optimized.......................................85prevention of update ...................355update ...........................................81user-defined functions.................418Variable References......................94

dynarray flag .......................................88DynProps

creating .........................................70maximum length of........................71


E

edgecolor of .......................................... 36style ............................................ 391width ........................................... 118

end dynamics...................................... 81erase

batcherase .................................... 78GraphTraces............................... 285marking objects for ....................... 65

Erase Update Mode.................. 472, 475event

dispatch input.............................. 130dispatch timer ............................. 131functions ..................................... 130GISMO........................................ 131intercept all events...................... 376set priority of processing............. 131wait ............................................. 130

Eventsadd to Workstation event queue . 120create.......................................... 120enable Locator motion ................ 360main loop ............................ 131, 223modify ......................................... 120query........................................... 132Timer........................................... 138

processing priority................. 131exploding SubModels ....................... 261EXPORT macro definition..................... 4expose-rectangle

enabling for Workstation ............. 474extended Point List ........................... 287extent

center.................................... 26, 144of an object, query for ................. 146

external SubModelmoving to Local List .................... 394query Model’s List of ................... 238

External SubModel Mode..................243

F

failure return value ................................3Filer interception files ........................244filer_callback( ) ..........................246, 250fill

attribute .......................................151direction.......................................148percent ........................................148

objects other than Rectangles150valid range for........................149

style.............................................391fill (concave)

enabling for Workstation .............473Fill attribute

color of ..........................................36Filled Text Rectangle

create ..........................................320FillGroup

close............................................187close each member of List ..........187create ..........................................187open ............................................187open List of FillGroups ................187

find by nameDatasource class object ................53object...........................................157State Instance .............................377

find file functioninstall ...........................................153

flagbatcherase ....................................78

example...................................80clockwise.....................................341display, force redraw ...................437global...........................................264non-replication, SubModels.........264permanent ...................................267repair ...........................................189


example .................................. 80updflag ........................................ 139visible.......................................... 437yes, query user ........................... 345

flashing (with cursor movement), elimination of............................... 473

font indexfrom font name............................ 160

font_index parameter........................ 160force redraw...................................... 437fpercent errors which were not noticeable

before.......................................... 150freeflag, setting for State................... 353freeing from memory

ColDef objects ............................ 162List of objects.............................. 162objects ........................................ 162Variable Definitions..................... 162

from .dat files .......................... 51full screen, setting to use

Workstation option .............. 473, 475functions, adding user-defined.......... 418

GG_BKGR_TYPE_COLOR................. 448G_BKGR_TYPE_INDEX .................. 448G_BKGR_TYPE_SYSTEM............... 448G_BPAD_BUTTON_* Event codes . 134,

137G_BTM_NO_TRANS flag ................... 22G_BTM_TRANS_IMPULSE flag......... 22G_CONTROL_KEY Event code ....... 134g_dyninit_state.................................... 82G_FILER_BINARY ........................... 246G_FILER_CHAR............................... 246G_FILER_CLOSE_READ......... 249, 250G_FILER_CLOSE_WRITE_FAILURE249G_FILER_CLOSE_WRITE_SUCCESS ..

248G_FILER_LOCFILE.......................... 246

G_FILER_M1 ............................245, 246G_FILER_M2 ....................................246G_FILER_OPEN_READ...........249, 250G_FILER_OPEN_WRITE .........248, 250G_FILER_QUERY_EXISTS......248, 250G_FILER_QUERY_READABLE249, 250G_FILER_QUERY_WRITABLE 248, 250G_FILER_WCHAR............................246G_FilerData.......................................246G_LOC_* Event codes..............134, 137G_LOC_ECHO_HORIZ ....................478G_LOC_ECHO_VERT......................478G_LOCK_KEY Event code ...............134G_MULTI_EVENT.....................368, 465G_NO_REPLICATE..........................264G_ONE_SHOT..........................368, 465G_ONE_SHOT_CLEAR............368, 465G_REPLICATE_ALWAYS ................264G_REPLICATE_IF_RENVARS.........264G_SHIFT_KEY Event code...............134G_TCOLOR_NULL ...........................449G_WIN_CONCAVE_FILL .................443G_WIN_DBUFF_CLEAR ..................443G_WIN_DBUFF_ERASE ..................443G_WIN_DESTROYED......................443G_WIN_FULL_SCREEN...................443G_WIN_KEEPASPECT ....................443G_WIN_MATRIX_HW.......................443G_WIN_NOBANNER........................443G_WIN_NOPASTE ...........................443G_WIN_NOPOSITION......................443G_WIN_NORESIZE..........................443G_WIN_WORKSTATION..................443G_WS_BPAD....................................473G_WS_BW_REV ......................473, 475G_WS_CACHE_GC..........................474G_WS_CONCAVE_FILL...................473G_WS_DBUFF_CLEAR............472, 475G_WS_DBUFF_CLEAR flag...............69G_WS_DBUFF_ERASE ...........472, 475


G_WS_DBUFF_ERASE flag .............. 69G_WS_EXPOSE_RECT................... 474G_WS_FULL_SCREEN ........... 473, 475G_WS_KEEP_ASPECT ........... 473, 475G_WS_LOOKUP_COLORS............. 473G_WS_MATRIX_HW........................ 473G_WS_NO_HARDWARE................. 472G_WS_NOPASTE............................ 474G_WS_PLANE_MASKING............... 474G_WS_PLANE_MASKING workstation

option .......................................... 453G_WS_POP_CLIP............................ 473G_WS_POP_RASTER..................... 473G_WS_POP_RASTER

Workstation Option ..................... 313G_WS_TEXT_BCOLOR................... 473genlocfile utility................................ 192gismoflag, setting for State ............... 353GISMOs

initialize ....................................... 169process a function key ................ 170

global flag ......................................... 264gms.h file .............................................. 3

gms_gms_dms.h file...................................... 3gms_sms.h file...................................... 3

gmsA

gmsATran( )...................................... 334

gmsC

gmsClassAddMethod( ) .............. 61, 372gmscodes.h file........................... 30, 109gmsCompareVersion( )..................... 348gmsCoordLimits( ) ............................ 179gmsCurrent( ).................................... 187

gmsDgmsDsActivate( ) ................................ 58

gmsDsDeactivate( ).............................58gmsDsMsg( ).......................................55gmsDynEnd( ) .............72, 116, 117, 163gmsDynInit( ) 72, 87, 92, 94, 97, 98, 109,

111, 116, 163, 203, 242, 366, 384, 385, 387

gmsDynUpdate( ) ..................88, 92, 113

gmsEgmsEndView( )..................................457gmsExternalEventLoop( )..................466

gmsFgmsFindByName( ) ...200, 201, 437, 470gmsFindObject( )...............135, 428, 429gmsFreeAllVarDefs( )..................51, 163

gmsGgmsGenerateLocFileSO( ) ................193

example.......................................194

gmsIgmsInitGismos( ) ...............................224gmsInitStates( ) .................139, 225, 376gmsInMode( ) ....................................224

gmsLgmsLQExtCenter( ) .............................27

gmsMgmsM2Get( ) .............................263, 366gmsM2Merge( ).................................263gmsM2Save( )...................................263gmsM2XGet( )...................102, 263, 271gmsMainInit( ) ...........................344, 412gmsMainInit( ) .......................................4gmsMainLoop( ) ........................131, 142gmsMGet( ) .......................................367gmsMGet( ) .......................................457

SL-GMS Function Reference vVersion 6.2a- 26 May 2006

gmsModApplyLocFileSO( )192, 195, 196, 197, 203, 204example ...................................... 204

gmsModCacheCapacity( ) 103, 269, 272gmsModCacheCount( )103, 270, 271, 272gmsModDynInitVarDefTable( ) ........... 97gmsModNonReplicate( ) ................... 104gmsModPermanent( ) ....................... 272gmsMSave( ) .................................... 395gmsMXGet( ) .................... 102, 264, 271

gmsNgmsNonWsLowEventFctn( ) ............. 142gmsNPXY( )...................................... 433

gmsOgmsObjFree( )... 113, 116, 117, 210, 377

gmsPgmsPlotClear( )................................. 176gmsPop*() functions

setting to use clip rectangle for Workstation................ 473

setting to use rastersfor Workstation................ 473

gmsPopOff( ) .................................... 354gmsPort( ) ................................. 274, 295gmsPortXY( ) .................................... 304gmsProcessLowEvent( )................... 466gmsProject( ) .................................... 344gmsPsLViewWrite( ) ......................... 303gmsPsPolyMaxPoints( ).................... 303gmsPsWsProcArgs( ) ....................... 303

gmsQ

gmsQCenter( ) .................................. 144gmsQDefaultWs( ) ............................ 442gmsQDefaultWsClass( ) ................... 470gmsQEvStringC( )............................. 136gmsQEvStringSO( ) .......................... 136

gmsQExtCenter( ) ...............................24gmsQModCacheCapacity( )..............271gmsQModCacheCount( ) ..........271, 272gmsQPartList( ) ...................................67gmsQSRStringSO( )..........................195

example.......................................203gmsQStringC( ) .................209, 211, 212gmsQStringWC( )..............209, 210, 211gmsQTPrec0RotFlag( ) .....................407gmsQTStringC( ) ...............403, 404, 405gmsQTStringSO( ) ............................403gmsQTStringWC( )....................403, 404gmsQTStrSO( ) .................................406gmsQWsBackgroundColor( ) ....449, 450gmsQWsColDef( ) .............................162

gmsR

gmsRect( )...........................................74gmsRedCode( ).................................281gmsRedraw( )....................................425gmsRefPoint( ) ............7, 9, 12, 329, 331gmsRemVarDefLinks( ).........72, 82, 163gmsRenamedStr( )......................82, 116gmsRenVarStrConstReplSO( ) ...72, 201

example.........................................73gmsRepairFlag( ) ........................78, 189gmsRMove2( ).......................................7gmsRRotZ( )..........................................9gmsRScale( ) ......................................12gmsRSTran( )....................................165gmsRTran( ) ......................................343

gmsSgmsSetTraps( ) .................................224gmsSetup( ).......................................245gmsSEvModifiers( )...........................125gmsSRApplyLocFileSO( ) 195, 196, 197,

199example.......................................202

gmsStActivate( )................................376

SL-GMS Function Reference viVersion 6.2a- 26 May 2006

gmsStAddModelName( ) .................. 277gmsStDeactivate( ) ........................... 376gmsStFreeAllVarDefs( ).................... 163gmsStReset( )................................... 376gmsString( )

example ........................................ 73gmsStringC( ).................... 194, 209, 211

example .............................. 202, 204gmsStringEmpty( ) ............................ 213gmsStringResource( )....................... 195gmsStringSetC( ) ...................... 209, 211gmsStringSetWC( )................... 209, 210gmsStringWC( ) ........................ 209, 210gmsStVarDefAddress( ).................... 384gmsStVarDefCount( ) ....................... 384gmsStVarDefine( ) ........ 92, 98, 162, 387gmsStVarDefSize( ) .......................... 384

gmsTgmstimer process

killing of (X Workstation) ............. 413spawning of................................. 139

gmsTimerPeriod( ) ............................ 360gmsTRepl( ) ...................................... 200gmsTStringC( ) ......................... 403, 404gmsTStringSO( )....................... 403, 405

example ...................................... 203gmsTStringWC( ) .............................. 403

gmsUgmsUnlinkVarDefs( )..... 72, 82, 163, 203gmsUpdate( ) ........ 84, 87, 242, 321, 425

gmsVgmsVarChanged( ) ....... 88, 95, 100, 355gmsVarDefAddress( ) ....................... 112gmsVarDefCount( )........................... 112gmsVarDefine( )... 55, 71, 84, 91, 92, 94,

117, 162, 163, 383, 419gmsVarDefineChanged( ) ................. 163

gmsVarDefineNoTable( )91, 92, 93, 162, 163

gmsVarDefSize( )..............................112gmsVarInitFctn( ).......................112, 385gmsVarRefName( ) .............................87gmsView( ) ........................................457gmsVuRFile( ) .....................................21

gmsWgmsWCScale( ) .................................344gmsWinDims( )..................................443gmsWindXY( ) ...................................425gmsWinFlags( )

valid codes for bit argument ........443gmsWinPush( )..................................446gmsWinUnmap( ) ..............................447gmsWorkst( ).............................224, 449gmsWPoint( ) ....................................295gmsWPXY( ) .............295, 321, 338, 432gmsWsBackgroundColor( )448, 449, 450gmsWsClose( )..................................441gmsWsEventFctn( )...........................360gmsWsLocEcho( )

valid codes for echotype argument ...477

gmsWsLowEventFctn( ) ....................142gmsWsProcArgs( ) ................4, 224, 478gmsWsProcArgsStr( ) .......................479gmsWsPsProcArgs( )............................4gmsWValue( ) .......7, 294, 323, 327, 332

gmsX

gmsXTran( ) ........................7, 9, 12, 165

gmsZ

gradient fill stylesacyclic .........................................173cyclic ...........................................172elliptic ..........................................173

GraphAxis object

SL-GMS Function Reference viiVersion 6.2a- 26 May 2006

create.......................................... 174major tick spacing ....................... 176minor tick spacing ....................... 176set ends of axis........................... 176values for endpoints.................... 176

GraphTrace objectclear ............................................ 285creating ....................................... 178erase and clear Point List ........... 285plot Points ................................... 284query number of traces............... 278

Grid object ........................................ 181Group

redrawing .................................... 189Group object ..................................... 185

close ........................................... 187close each member of List .......... 187create.......................................... 187current........................................... 40destroy ........................................ 187destroy Groups in a List .............. 187

gsave Model ..................................... 242gmsQFGradient( )............................. 173

Hhardware-drawing routines, disabling

Workstation for............................ 472highlight .............................................. 65

Iid variable type...................................... 2idLinkRef variable type ......................... 2idPoint variable type ............................. 2Immediate Update Mode .... 66, 331, 415IMPORT macro definition ..................... 4impulse filter kernel

and scaling Bitmaps...................... 22include files

order of in SL-GMS programs......... 3initialize

dynamics .......................................81State............................................359Variable References

local to State..........................382input events.......................................130install

find file function ...........................153Instance, SubModel ..........................261Internationalization ............................190

Modelapply localization file .............195generate localization file........193

source codelocalization file for..................195

interrupt signals, handler for..............412invisible .............................................437

Kkeysymdef.h file ................................134

Llib directory ...........................................2Line

color of ..........................................36create ..........................................214style.............................................391

Linked Reference (LinkRef) object....215-loc option .................................192, 203loc_motion method............................135loc_press method..............................135loc_release method...........................135local SubModel

moving to External List................394query Model’s List of ...................238

localization file commandsgmsModApplyLocFileSO( ) .........200gmsSRApplyLocFileSO( ) ...........199

localization filesdefinition of..................................191

SL-GMS Function Reference viiiVersion 6.2a- 26 May 2006

new function generated from Models ................... 193

Unicode....................................... 193wide character and multi-byte..... 198

locator eventscapture for a View....................... 424

Locator object ................................... 158

Mm2flag parameter.............................. 266main Event loop

starting ........................................ 223main loop, external ........................... 140Marker object

color of .......................................... 36creating ....................................... 233custom drawing function ............. 229Marker class ................................. 31setting size.................................. 234style ............................................ 391

masking, bitplane.............................. 451matrix hardware routines, enabling for

Workstation................................. 473menus

pop-up......................................... 311message tracing ............................... 236middle mouse button

disabling for cut and paste.......... 474mode, update.................................... 415Model

apply localization file to............... 195background color .......................... 15current................................... 40, 237generate localization file ............. 193

example ................................ 194object

creating ................................. 237prevention of dynamic update..... 355pseudo-files ................................ 244save ............................................ 240

user header string .......................258Variable Definition Table ...............97

Model Instance (ModInst) object .......261modelname parameter ......................266modify

Events .........................................120mouse button

middle, disabling cut and paste for Workstation .....................474

mouse cursor ......................................43move

absolute...........................................5multiple Views, in PostScript .............304

Nname

find object by ...............................157of an object..................................275of SL-GMS Run-time Functions ......3

NDC scaling factor ............................273noerase flag, for an object...................80non-replicated SubModels ................265non-replication flag............................261

on SubModels .............................264normalized Point ...............................273

Oobject

center Point ...................................24detectability .................................436free List from memory .................162freeing from memory ...................162get Point List ...............................287name ...........................................275query owner List..........................276radius ..........................................310replace Point List.........................290style attribute...............................391UserData .....................................422UserWord ....................................422

SL-GMS Function Reference ixVersion 6.2a- 26 May 2006

Variable Definition......................... 92visibility ....................................... 436

open_read( ) ..................................... 255open_write( )..................................... 253optimized dynamics ............................ 85OR operation .................................... 317overlapping Views............................. 427overwrite ........................................... 317owner

of object ...................................... 276

Ppan.................................................... 434PartPrim class..................................... 31paths ................................................... 62percent-fill

attribute....................................... 149objects other than Rectangles .... 150

permanent flag.......................... 261, 267picking objects .................................. 427Pie object

create.......................................... 282modify ......................................... 340

plane masking................................... 451plot

plotshift ....................................... 285Points.......................................... 285

pntFree( ) ... 24, 144, 163, 274, 293, 323, 488

pntX( ) ............................................... 135pntY( ) ............................................... 135Point

clone ........................................... 292example ................................ 294

create.......................................... 292List .............................................. 290Normalized Device Coordinates . 273plot .............................................. 284Reference Point .......................... 322with World Coordinates............... 487

x coordinate.................................292Point y coordinate .............................292pointer types, in SL-GMS......................2Polygon object

create ..........................................296Polyline object

create ..........................................214popflag, setting for State ...................354Popon/Popoff Mode ..........................312PostScript..........................................298preserve_sub_vdt parameter ......97, 102Prim class............................................31priority, View......................................426processing priority .............................131Project object ....................................306ps_comment......................................300ps_dcmax_x ......................................299ps_dcmax_y ......................................299ps_flags.............................................300ps_off_x.............................................299ps_off_y.............................................299ps_one_pix........................................300ps_rotate ...........................................300pseudo-files.......................................244psflags

bit options....................................300pull-down menus

raster save and restore ...............311

Qquery

Events .........................................132Model parts .................................278object parts..................................278user .............................................308

query_exists( )...................................252query_readable( )..............................255query_writable( ) ...............................252quit, SL-GMS.....................................344

SL-GMS Function Reference xVersion 6.2a- 26 May 2006

R

radiusobject .......................................... 310

rasteroperations ................................... 316Raster Operation Mode ........ 21, 316

raster imageView ............................................ 314

Rectangle objectcreate.......................................... 319

redraw Group.................................... 189Reference Extent, definition of............ 22Reference Point ................................ 322refFreAll().......................................... 380refKilAll( ) .......................... 144, 163, 288refNew( ) ........................... 214, 233, 296relative

move ........................................... 325scale ........................................... 330transformation..................... 328, 333

Renamed Variablescreating ......................................... 70in SubModel Replicate Mode........ 72maximum length of ....................... 71query string ................................... 74

repair flag.......................................... 189replace string .................................... 401replication, SubModel ....................... 263reset transformation.......................... 335Resolution Check Mode.................... 426return values ......................................... 3reverse black and white

setting Workstation for ........ 473, 475RGB, setting for a color index............. 39rotation.............................................. 328

absolute .......................................... 8

Ssave Model ....................................... 240

scale............................................10, 330scoping

initialize variables local to State ..382search path, SL-GMS

changing of....................................62default ...........................................63

Sector objectcreate ..........................................337modify..........................................340

segmentation violationhandler for ...................................412with gmsVarDefine( )...................111

segments...........................................426set transformation .............................342setup .................................................344size attribute

Marker .........................................234SL-GML command

act ...............................................476amove .............................................6amovex............................................6amovey............................................6arclength .....................................341arotz ................................................8ascale............................................11ascalex ..........................................12ascaley ..........................................12batcherase ....................................78bitmap ...........................................21bitmapflag......................................21center ............................................24cir2 ................................................29circ.................................................28clear ..............................................32clip...............................................428clone..............................................33closed............................................34color ..............................................36coordlimits ...................................176coordscale...........................344, 488

SL-GMS Function Reference xiVersion 6.2a- 26 May 2006

cspline......................................... 350ctb ................................................. 39current......................................... 427dbflag ............................................ 69deact ........................................... 476detect .......................................... 437dump............................................. 68dynprop......................................... 71endview....................................... 427estyle .......................................... 391etime ........................................... 281ewidth ......................................... 118fcir2 ............................................... 29fcirc ............................................... 29fcolor ............................................. 36finter............................................ 391font.............................................. 396fpoly ............................................ 296frect............................................. 320fsec2 ........................................... 338fsec3 ........................................... 338fsect ............................................ 338fstyle ........................................... 391ftrect............................................ 320graphaxis .................................... 174graphtrace................................... 178grid.............................................. 181gsave .......................................... 241height .......................................... 397inst2 ............................................ 263lcolor ............................................. 36lstyle............................................ 391majorspacing .............................. 176mark............................................ 233mcolor ........................................... 36minorspacing .............................. 176model get .................................... 240model xget .................................. 240modinst ....................................... 263modinst2 ..................................... 263

moffset ........................................326mrotz ...........................................329mscale.........................................332msize...........................................234mstyle..........................................391mtran ...........................................168mtran0 .........................................336noerase .........................................80offset ...........................................326pan ..............................................435path .............................................396plotclear.......................................285plotdata .......................................284plotdatax......................................285plotdatay......................................285plotreset ......................................285plotshiftx ......................................285plotshifty ......................................285points...........................................287poly..............................................296port ..............................................433prec .............................................396project .................................306, 344project get ...................................306project merge ..............................307project save.................................306quit ..............................................344radius ..........................................310rastop ..........................................316rect ..............................................320refpoint ........................................322renamedvars .................................71reschk..........................................429rfrect ............................................320rftrect ...........................................320rmove ..........................................326rmovex ........................................326rmovey ........................................326rrect .............................................320rrotz .............................................328

SL-GMS Function Reference xiiVersion 6.2a- 26 May 2006

rscale .......................................... 331rscalex ........................................ 331rscaley ........................................ 331save ............................................ 240scale ........................................... 331sec2 ............................................ 338sec3 ............................................ 338sect ............................................. 338spline .......................................... 350startangle .................................... 341stext ............................................ 402stress .......................................... 389tcolor ............................................. 36text .............................................. 402time ............................................. 281tran.............................. 167, 334, 342tran0............................................ 336userdata...................................... 423userword ..................................... 423valuelimits ................................... 176view............................................. 427vis ............................................... 437wind ............................................ 432xpoints ........................................ 287xtran.............................................. 13xvaluelimits ................................. 179yvaluelimits ................................. 179zoom ........................................... 435zoomin ........................................ 435zoomout ...................................... 435zos .............................................. 435zpr............................................... 435

SL-GMSclose ........................................... 344compare version numbers .......... 347configuration number .................. 347convert Internal Coordinate to World

Coordinate ...................... 488crash handler .............................. 413initialize ....................................... 223

installation directory ....................346quit ..............................................344setup ...........................................344version date.................................347version number ...........................348

SL-SMSdebugging utility ..........................376

source ...............................................317Spline object

create ..........................................350modify..........................................340stress...........................................389

State".m2"/".m1" search order .............376class ............................................356

add methods..........................357create ....................................356find by name..........................376install .....................................357

definevars method...............114, 384initialization..................................359Instance

activate ..................................363attributes of............................352clear List of Models ...............367clear View pointer..................367create ....................................363deactivate ..............................366find by name..........................377free Model .............................377initialize Variable References 382messaging.............................371Model.....................................367modify....................................363query .....................................378TextEdit object.......................367Variable Definition objects.....386View.......................................367

clear pointer367Workstation/Window..............366

SL-GMS Function Reference xiiiVersion 6.2a- 26 May 2006

local variables ............................. 382mark and reset............................ 369messaging .................................. 371query........................................... 378set version 3.0 compatibility........ 376update method............................ 114

stress, Splines .......................... 350, 389String Events

Event-handlers for ...................... 464String object........................ 72, 195, 403

creating and querying ................. 209example ................................ 73, 193

String Resource objectexample ...................................... 205

style attribute .................................... 391SubModel

cache .......................... 242, 243, 269exploding .................................... 261external ....................................... 394local ............................................ 394non-replicated with dynamics ....... 98non-replication .................... 261, 265permanent................................... 267replication ................................... 263

SubModel Replicate Mode........ 261, 279success codes ...................................... 3system calls (bad), handler for.......... 412System Pull-Down Menu .................. 302

TText................................................... 401

background color, enabling Workstation for................ 473

color of .......................................... 36Text object

create.......................................... 402query attributes ........................... 407set attributes ............................... 396

Text Rectangleconstraint attribute ...................... 409

TextEdit object ..................................367State Instance .............................367

time_level flag ...................................281timer event ................................131, 138timing information..............139, 281, 360traces, number of ..............................278transformation

absolute general..........................164absolute move.................................5absolute scale ...............................10apply..............................................13Bitmap object ................................20relative.........................................333relative 2D scale..........................330relative general............................167relative move...............................325relative rotation............................328reset ............................................335set ...............................................342

transparent Views .............................427traps, setting of..................................412trend Graphs .....................................285type attribute .......................................92types, of variables .................................2

U

Unicode localization files...................193update

dynamics .......................................81modes .........................................416times............................................281

update method ..................................114update( ), State method ....................106updflag flag........................................139

setting for State ...........................354UserData

maximum length of......................423set and query ..............................422

user-defined functionadding and removing...................418

SL-GMS Function Reference xivVersion 6.2a- 26 May 2006

dynamic ...................................... 418userfctns_initialize() .......................... 420UserWord

set and query .............................. 422

V

variabledefine new type........................... 113determining which are present at run

time ................................... 94inform SL-GMS of value change. 113SL-GMS types ................................ 2Variable Definition

created with gmsVarDefineNoTable( )

freeing from memory162definition of............................ 109find object.............................. 117freeing from memory....... 51, 117query

address92, 387count92, 387size92, 387

query name............................. 93removal of links to ................. 116set

address91, 112, 387count91, 112, 387size92, 112, 387type92

Variable Referencedefinition of.............................. 82query

address95name94number of95

query an object ....................... 94removal of links to ................. 116

Variable Definition Table

for a Model ....................................97inform SL-GMS of value change .100number of objects..........................99object by name..............................99objects by index ............................99recommended uses.......................98

version date, SL-GMS.......................347version number, SL-GMS..................348View

capture locator events.................424clear ..............................................32Clip Mode ....................................428clipping ........................................426create ..........................................427current ...........................................40delayed redraw............................425detectability .................................436dimensions ..................................426make temporary WC-window change

permanent .......................435multiple

printing in PostScript .............304pan and zoom .............................434printing in PostScript ...................303priority .........................................426raster image ................................314reset pan and zoom ....................435Resolution Check Mode ..............429transparent ..................................427Viewport ......................................431visibility........................................436WC-window.................................431Workstation/Window number ......428

Viewport ............................................431Virtual-window, setting for a

Workstation/Window ...................443visflag, setting for State.....................354visibility attribute................................436visible flag .........................................437

SL-GMS Function Reference xvVersion 6.2a- 26 May 2006

W

wait for event .................................... 130WC-Window...................................... 431width, of edge ................................... 118Workstation

aspect ratio, constraining Window to initial setting ............ 473, 475

bitpad devices, enabling of ......... 473Bitplane masking, enabling of..... 474colormap, setting of .................... 473concave fill, enabling of .............. 473expose-rectangle, enabling of..... 474full screen

setting Window to use473, 475gmsPop*() functions

setting to use clip rectangle .. 473setting to use rasters............. 473

hardware-drawing routinesdisabling of ...................... 472

matrix hardware routinesenabling of ...................... 473

mouse (middle) for cut and paste, disabling of ...................... 474

reverse black and whitesetting of ................. 473, 475

software double-bufferingenabling of .............. 472, 475

Text background colorenabling of ...................... 473

X Graphics Context cachingenabling of ...................... 474

Workstation/Window......................... 469activate ....................................... 476background color, setting............ 448bitplane masking......................... 451bitplane writemask for

Locator echo ................... 476clear .............................................. 32color map index .......................... 453

coordinate conversion .................460create ..........................................470create with command line

parameters ......................478deactivate....................................476destroy ........................................476

externally created..................441Events .........................................462externally created

destroy...................................441Locator echo type........................476number ........................................426options.........................................475query Window attributes..............480query Workstation attributes .......482writemask ....................................454

World Coordinate Scale Factor .293, 488setting value ................................487

X

X Graphics Context cachingenabling Workstation for .............474

XOR operation ..................................317

Yyes flag..............................................345yes or no

query user ...................................308

Zzoom .................................................434

SL-GMS Function Reference xviVersion 6.2a- 26 May 2006

Function Name Index
GgmsAddLibPath( ) ...................... 62gmsAddUserFctn( ) .................. 418gmsAllVarsChanged( ) ............... 85gmsAMove2( ) .............................. 5gmsAMoveX( ) .............................. 5gmsAMoveY( ) .............................. 5gmsArcLength( ) ....................... 340gmsARotZ( ) ................................. 8gmsAScale( ) .............................. 10gmsAScaleX( ) ........................... 10gmsAScaleY( ) ........................... 10gmsAskLine( ) .......................... 308gmsASTran( ) ........................... 164gmsATran( ) .............................. 342gmsAutoUpdateMode( ) ............ 85gmsBackgrFlag( ) ....................... 15gmsBatchErase( ) ...................... 78gmsBatchEraseMode( ) ............. 78gmsBColor( ) ............................ 396gmsBitmap( ) .............................. 20gmsBitmapFlag( ) ....................... 20gmsCASca2( ) ............................ 10gmsCASTran( ) ......................... 164gmsCATran( ) ............................ 342gmsCenter( ) .............................. 24gmsCGMGet( ) ......................... 240gmsChdir( ) ................................. 62gmsCir2( ) ................................... 28gmsCirc( ) ................................... 28gmsClassAddMethod( ) ..... 52, 356gmsClear( ) ................................. 32gmsClip( ) ................................. 426gmsClone( ) ................................ 33gmsClose( ) .............................. 344gmsClosed( ) .............................. 34gmsCloseGroup( ) .................... 185gmsClrAllWs( ) ........................... 32gmsCompareVersion( ) ............ 347
gmsCoordLimits( ) ................... 174gmsCrashHandlerFctn( ) ......... 411gmsCRMv2( ) ........................... 325gmsCRRotz( ) .......................... 328gmsCRSca2( ) .......................... 330gmsCRSTran( ) ........................ 167gmsCRTran( ) ........................... 333gmsCSpline( ) .......................... 350gmsCTB( ) .................................. 36gmsCTr0( ) ................................ 335gmsCurGroup( ) ......................... 40gmsCurModel( ) ......................... 40gmsCurrent( ) ............................. 40gmsCurView( ) ........................... 40gmsCWFlag( ) .......................... 340gmsDatDsFreeAll( ) ................... 51gmsDefu( ) ................................ 415gmsDeGroup( ) ........................ 185gmsDetect( ) ............................. 436gmsDispatchInputEvents( ) ..... 130gmsDispatchTimerEvents( ) .... 130gmsDisplay( ) ............................. 65gmsDoubleBufferFlag( ) ............ 69gmsDsActivate( ) ....................... 54gmsDsAddVarDef( ) ................... 54gmsDsClass( ) ............................ 52gmsDsClassFindByName( ) ...... 52gmsDsClassInstall( ) ................. 52gmsDsDeactivate( ) ................... 54gmsDsFindVarDef( ) .................. 54gmsDsInst( ) ............................... 54gmsDsInstFree( ) ....................... 54gmsDsListActivate( ) ................. 57gmsDsListDeactivate( ) ............. 57gmsDsListFree( ) ....................... 57gmsDsListGet( ) ......................... 57gmsDsListSave( ) ....................... 57gmsDsListUpdate( ) ................... 57gmsDsMsg( ) .............................. 59gmsDsMsg2( ) ............................ 59


gmsDsMsg3( ) ............................ 59gmsDsMsg4( ) ............................ 59gmsDsObjFree( ) ........................ 57gmsDsObjNew( ) ........................ 57gmsDsPMsg( ) ............................ 59gmsDsPMsg1( ) .......................... 59gmsDsPMsg2( ) .......................... 59gmsDsPMsg3( ) .......................... 59gmsDsPMsg4( ) .......................... 59gmsDsUpdate( ) ......................... 54gmsDsVarDefFree( ) .................. 54gmsDump( ) ................................ 68gmsDumpViews( ) ...................... 68gmsDynEnd( ) ............................ 81gmsDynInit( ) .............................. 81gmsDynInitNoMarks( ) ............... 81gmsDynRestore( ) ...................... 81gmsDynStr( ) .............................. 70gmsDynUpdArrayFlag( ) ............ 85gmsDynUpdate( ) ....................... 81gmsDynUpdateMode( ) ............. 85gmsEColor( ) .............................. 36gmsEndCurrent( ) ...................... 40gmsEndGroup( ) ....................... 185gmsEndModel( ) ....................... 237gmsEndView( ) ......................... 426gmsErase( ) ................................ 65gmsEStyle( ) ............................. 391gmsEvAction( ) ......................... 120gmsEvData( ) ........................... 120gmsEvent( ) .............................. 120gmsEventPriority( ) .................. 130gmsEvExtent( ) ......................... 120gmsEvKeysym( ) ...................... 120gmsEvModifiers( ) .................... 120gmsEvObject( ) ........................ 120gmsEvPoint( ) ........................... 120gmsEvStringC( ) ....................... 120gmsEvStringSO( ) .................... 120gmsEvTime( ) ........................... 120

gmsEvTrigger( ) ....................... 120gmsEvType( ) ........................... 120gmsEvView( ) ........................... 120gmsEvWorkst( ) ....................... 120gmsEWidth( ) ........................... 118gmsExit( ) ................................. 344gmsExtentMode( ) ..................... 85gmsExternalEventLoopFlag( ) 140gmsExtSubModMode( ) ........... 240gmsFALibPaths( ) ...................... 62gmsFastDynPropMode( ) .......... 85gmsFCir2( ) ................................ 28gmsFCirc( ) ................................. 28gmsFColor( ) .............................. 36gmsFDir( ) ................................ 148gmsFGradient( ) ....................... 171gmsFilerDataPseudoFile( ) ..... 244gmsFilerDataSize( ) ................. 244gmsFilerFctn( ) ......................... 244gmsFilled( ) .............................. 151gmsFillGroup( ) ........................ 185gmsFillGroupFlags( ) ............... 185gmsFindByName( ) .................. 157gmsFindObject( ) ..................... 157gmsFindVarDefAll( ) ................ 107gmsFInter( ) .............................. 391gmsFKeyProcess( ) ................. 170gmsFPercent( ) ........................ 148gmsFPie( ) ................................ 282gmsFPie2( ) .............................. 282gmsFPolygon( ) ........................ 296gmsFRect( ) .............................. 319gmsFreeAllVarDefs( ) .............. 107gmsFSec( ) ............................... 337gmsFSec2( ) ............................. 337gmsFSec3( ) ............................. 337gmsFStyle( ) ............................. 391gmsFTRect( ) ........................... 319gmsGenerateLocFileSO( ) ...... 190gmsGraphAxis( ) ...................... 174


gmsGraphTrace( ) .................... 178gmsGrid( ) ................................. 181gmsGridSize( ) ......................... 181gmsGridSizeX( ) ....................... 181gmsGridSizeY( ) ....................... 181gmsGroup( ) ............................. 185gmsHilite( ) ................................. 65gmsImmu( ) .............................. 415gmsInitGismos( ) ...................... 169gmsInitStates( ) ........................ 359gmsInitStatesOnWs( ) ............. 359gmsInsExplode( ) ..................... 261gmsL10nInit( ) .......................... 190gmsL10nStr( ) ........................... 190gmsLAMove2( ) ............................ 5gmsLAMoveX( ) ............................ 5gmsLAMoveY( ) ............................ 5gmsLArcLength( ) .................... 340gmsLARotZ( ) ............................... 8gmsLAScale( ) ............................ 10gmsLAScaleX( ) ......................... 10gmsLAScaleY( ) ......................... 10gmsLASTran( ) ......................... 164gmsLATran( ) ............................ 342gmsLBColor( ) .......................... 396gmsLBitmapFlag( ) .................... 20gmsLCenter( ) ............................ 24gmsLClone( ) .............................. 33gmsLClosed( ) ............................ 34gmsLCloseGroup( ) ................. 185gmsLDeGroup( ) ...................... 185gmsLDetect( ) ........................... 436gmsLDisplay( ) ........................... 65gmsLEColor( ) ............................ 36gmsLErase( ) .............................. 65gmsLEStyle( ) ........................... 391gmsLEWidth( ) .......................... 118gmsLFColor( ) ............................ 36gmsLFDir( ) ............................... 148gmsLFGradient( ) ..................... 171

gmsLFilled( ) ............................ 151gmsLFillGroupFlags( ) ............. 185gmsLFInter( ) ............................ 391gmsLFPercent( ) ...................... 148gmsLFStyle( ) ........................... 391gmsLGridSize( ) ....................... 181gmsLGridSizeX( ) .................... 181gmsLGridSizeY( ) .................... 181gmsLHilite( ) ............................... 65gmsLine( ) ................................ 214gmsLMColor( ) ........................... 36gmsLMkSpline( ) ...................... 350gmsLMSize( ) ........................... 234gmsLMStyle( ) .......................... 391gmsLObjFree( ) ........................ 162gmsLOpenGroup( ) .................. 185gmsLPFndPt( ) ......................... 287gmsLPoints( ) ........................... 290gmsLQExtCenter( ) .................. 143gmsLQExtent( ) ........................ 143gmsLQPointList( ) .................... 287gmsLQXPointList( ) .................. 287gmsLRadius( ) .......................... 310gmsLRastOp( ) ......................... 316gmsLRefPoint( ) ....................... 322gmsLRefPointX( ) ..................... 322gmsLRefPointY( ) ..................... 322gmsLRMove2( ) ........................ 325gmsLRMoveX( ) ....................... 325gmsLRMoveY( ) ....................... 325gmsLRRotZ( ) ........................... 328gmsLRScale( ) ......................... 330gmsLRScaleX( ) ....................... 330gmsLRScaleY( ) ....................... 330gmsLRSTran( ) ......................... 167gmsLRTran( ) ............................ 333gmsLStartAngle( ) .................... 340gmsLStress( ) ........................... 389gmsLTAlign( ) ............................ 396gmsLTColor( ) ............................. 36


gmsLTFont( ) ............................ 396gmsLTHeight( ) ......................... 396gmsLTPath( ) ............................ 396gmsLTPrec( ) ............................ 396gmsLTran0( ) ............................. 335gmsLTRectTextConstraint( ) .... 409gmsLTSize( ) ............................ 396gmsLTStr( ) ....................... 396, 401gmsLUnFillGroup( ) ................. 185gmsLUserData( ) ...................... 422gmsLVis( ) ................................. 436gmsLXTran( ) .............................. 13gmsLXTran1( ) ............................ 13gmsM2Get( ) ............................. 240gmsM2Save( ) .......................... 240gmsM2XGet( ) .......................... 240gmsMain( ) ................................ 223gmsMainInit( ) .......................... 223gmsMainInitStr( ) ..................... 223gmsMainLoop( ) ....................... 223gmsMainStr( ) ........................... 223gmsMajorSpacing( ) ................. 174gmsMAMove2( ) ........................... 5gmsMAMoveX( ) ........................... 5gmsMAMoveY( ) ........................... 5gmsMark( ) ............................... 233gmsMARotZ( ) .............................. 8gmsMAScale( ) ........................... 10gmsMAScaleX( ) ........................ 10gmsMAScaleY( ) ........................ 10gmsMASTran( ) ........................ 164gmsMATran( ) ........................... 342gmsMBColor( ) ......................... 396gmsMBitmapFlag( ) ................... 20gmsMClosed( ) ........................... 34gmsMColor( ) .............................. 36gmsMDetect( ) .......................... 436gmsMEColor( ) ........................... 36gmsMEStyle( ) .......................... 391gmsMEWidth( ) ......................... 118

gmsMExtToLoc( ) ..................... 394gmsMFColor( ) ........................... 36gmsMFDir( ) ............................. 148gmsMFilled( ) ........................... 151gmsMFInter( ) ........................... 391gmsMFPercent( ) ..................... 148gmsMFStyle( ) .......................... 391gmsMGet( ) .............................. 240gmsMGetUserHeaderStr( ) ..... 258gmsMGridSize( ) ...................... 181gmsMGridSizeX( ) ................... 181gmsMGridSizeY( ) ................... 181gmsMGSave( ) ......................... 240gmsMinorSpacing( ) ................ 174gmsMLocToExt( ) ..................... 394gmsMMColor( ) .......................... 36gmsMMerge( ) .......................... 240gmsMMSize( ) .......................... 234gmsMMStyle( ) ......................... 391gmsModApplyLocFileSO( ) ..... 190gmsModCacheCapacity( ) ....... 269gmsModCacheCount( ) ........... 269gmsModDynInitVarDefTable( ) .. 96gmsModel( ) ............................. 237gmsModelWithParts( ) ............. 237gmsModInst( ) .......................... 261gmsModInst2( ) ........................ 261gmsModNonReplicate( ) ......... 261gmsModPermanent( ) .............. 261gmsMRastOp( ) ........................ 316gmsMRMove2( ) ....................... 325gmsMRMoveX( ) ...................... 325gmsMRMoveY( ) ...................... 325gmsMRRotZ( ) .......................... 328gmsMRScale( ) ........................ 330gmsMRScaleX( ) ...................... 330gmsMRScaleY( ) ...................... 330gmsMRSTran( ) ........................ 167gmsMRTran( ) ........................... 333gmsMSave( ) ............................ 240


gmsMSize( ) ............................. 234gmsMStress( ) .......................... 389gmsMStyle( ) ............................ 391gmsMTAlign( ) .......................... 396gmsMTColor( ) ........................... 36gmsMTFont( ) ........................... 396gmsMTHeight( ) ....................... 396gmsMTPath( ) ........................... 396gmsMTPrec( ) ........................... 396gmsMTran0( ) ........................... 335gmsMTRectTextConstraint( ) .. 409gmsMtrFlag( ) ........................... 236gmsMTSize( ) ........................... 396gmsMUserHeaderStr( ) ........... 258gmsMVis( ) ............................... 436gmsMXGet( ) ............................ 240gmsNDCScale( ) ...................... 273gmsNoErase( ) ........................... 78gmsNoFlags( ) ............................ 85gmsNoFlagsMode( ) .................. 85gmsNonWsLowEventFctn( ) .... 462gmsNoUpdImmu( ) ................... 415gmsNPXY( ) .............................. 273gmsObjFree( ) .......................... 162gmsObjIsClass( ) ....................... 30gmsObjIsClassName( ) ............. 30gmsObjNameStr( ) ................... 275gmsOpenGroup( ) .................... 185gmsPan( ) ................................. 434gmsPartRpPs( ) ........................ 290gmsPGet( ) ............................... 306gmsPie( ) .................................. 282gmsPie2( ) ................................ 282gmsPlotClear( ) ........................ 284gmsPlotData( ) ......................... 284gmsPlotDataX( ) ....................... 284gmsPlotDataY( ) ....................... 284gmsPlotReset( ) ....................... 284gmsPlotShiftX( ) ....................... 284gmsPlotShiftY( ) ....................... 284

gmsPMerge( ) .......................... 306gmsPoints( ) ............................. 290gmsPolygon( ) .......................... 296gmsPopOff( ) ............................ 311gmsPopOn( ) ............................ 311gmsPopReset( ) ....................... 311gmsPort( ) ................................. 431gmsPortXY( ) ............................ 431gmsProcessLowEvent( ) ......... 140gmsProject( ) ............................ 306gmsPSave( ) ............................. 306gmsPsLViewWrite( ) ................ 298gmsPsPolyMaxPoints( ) .......... 298gmsPsSetParams( ) ................. 298gmsPsViewWrite( ) .................. 298gmsPsWsProcArgs( ) .............. 298gmsPsWsProcArgsStr( ) ......... 298gmsQAllStates( ) ...................... 378gmsQArcLength( ) ................... 340gmsQAutoUpdateMode( ) ......... 85gmsQBackgrFlag( ) .................... 15gmsQBColor( ) ......................... 407gmsQBitmapFlag( ) .................... 20gmsQCenter( ) ........................... 24gmsQClosed( ) ........................... 34gmsQColor( ) .............................. 36gmsQConfig( ) .......................... 347gmsQCurGroup( ) ...................... 40gmsQCurModel( ) ...................... 40gmsQCurrent( ) .......................... 40gmsQCurView( ) ........................ 40gmsQDefaultWsClass( ) .......... 482gmsQDefRefPt( ) ..................... 322gmsQDetect( ) .......................... 436gmsQDisplayId( ) ..................... 482gmsQDynStr( ) ........................... 70gmsQDynStrList( ) ..................... 70gmsQDynUpdateMode( ) .......... 85gmsQEColor( ) ........................... 36gmsQEStyle( ) .......................... 391

SL-GMS Function Reference vVersion 6.2a- 26 May 2006

gmsQEvAction( ) ...................... 132gmsQEvButtons( ) .................... 132gmsQEvData( ) ......................... 132gmsQEvExtent( ) ...................... 132gmsQEvKeysym( ) ................... 132gmsQEvModifiers( ) ................. 132gmsQEvObject( ) ...................... 132gmsQEvPoint( ) ........................ 132gmsQEvStringC( ) .................... 132gmsQEvStringSO( ) ................. 132gmsQEvTime( ) ........................ 132gmsQEvTrigger( ) ..................... 132gmsQEvType( ) ......................... 132gmsQEvView( ) ........................ 132gmsQEvViewIndex( ) ............... 132gmsQEvWorkst( ) ..................... 132gmsQEWidth( ) ......................... 118gmsQExtCenter( ) .................... 143gmsQExtent( ) .......................... 143gmsQExtentMode( ) ................... 85gmsQExternalEventLoopFlag( ) 140gmsQExtModelList( ) ............... 237gmsQExtSubModMode( ) ........ 240gmsQFastDynPropMode( ) ........ 85gmsQFColor( ) ............................ 36gmsQFDir( ) .............................. 148gmsQFilerDataAction( ) ........... 244gmsQFilerDataFilename( ) ...... 244gmsQFilerDataFiler( ) .............. 244gmsQFilerDataPseudoFile( ) .. 244gmsQFilerDataSize( ) .............. 244gmsQFilerDataType( ) ............. 244gmsQFilled( ) ............................ 151gmsQFInter( ) ........................... 391gmsQFPercent( ) ...................... 148gmsQFStyle( ) .......................... 391gmsQGismoEvent( ) ................ 130gmsQGmsHome( ) ................... 346gmsQGridSizeX( ) .................... 181gmsQGridSizeY( ) .................... 181

gmsQLocModelList( ) .............. 237gmsQMaxTraceLength( ) ......... 178gmsQMColor( ) ........................... 36gmsQModCacheCapacity( ) .... 269gmsQModCacheCount( ) ........ 269gmsQModelList( ) .................... 237gmsQModNonReplicate( ) ....... 261gmsQModPermanent( ) ........... 261gmsQMSize( ) .......................... 234gmsQMStyle( ) ......................... 391gmsQMUserHeaderStr( ) ........ 258gmsQNoFlagsMode( ) ............... 85gmsQNumParts( ) .................... 278gmsQNumTraces( ) .................. 278gmsQNumVarRefs( ) ................. 94gmsQObjNameStr( ) ................ 275gmsQOwner( ) .......................... 276gmsQOwnerList( ) .................... 276gmsQOwnerModel( ) ............... 276gmsQOwnerState( ) ................. 276gmsQOwnerView( ) ................. 276gmsQPartExtent( ) ................... 143gmsQPartList( ) ........................ 278gmsQPartNum( ) ...................... 278gmsQPartPointList( ) ............... 287gmsQPointList( ) ...................... 287gmsQRadius( ) ......................... 310gmsQRastOp( ) .......................... 20gmsQRefPoint( ) ...................... 322gmsQRefPointX( ) .................... 322gmsQRefPointY( ) .................... 322gmsQReleaseDate( ) ............... 347gmsQRenamedStr( ) .................. 70gmsQScreenExt( ) ................... 482gmsQSRStringSO( ) ................ 190gmsQStartAngle( ) ................... 340gmsQStClassName( ) .............. 378gmsQStCurState( ) .................. 378gmsQStEvState( ) .................... 378gmsQStIsActive( ) .................... 378

SL-GMS Function Reference viVersion 6.2a- 26 May 2006

gmsQStModel( ) ....................... 378gmsQStModelList( ) ................. 378gmsQStModelName( ) ............. 378gmsQStName( ) ....................... 378gmsQStress( ) .......................... 389gmsQStringC( ) ........................ 208gmsQStringWC( ) ..................... 208gmsQStStrMsgState( ) ............ 378gmsQStSubStates( ) ................ 378gmsQStSuperState( ) .............. 378gmsQStTextEditObj( ) .............. 378gmsQStTopState( ) .................. 378gmsQStVarDefAddress( ) ........ 386gmsQStVarDefCount( ) ............ 386gmsQStVarDefSize( ) .............. 386gmsQStView( ) ......................... 378gmsQStViewName( ) ............... 378gmsQStWorkst( ) ...................... 378gmsQStWorkstName( ) ............ 378gmsQSubModel( ) .................... 261gmsQSubModelName( ) .......... 261gmsQSubModReplicateMode( ) 261gmsQTAlignX( ) ........................ 407gmsQTAlignY( ) ........................ 407gmsQTColor( ) ............................ 36gmsQTFont( ) ........................... 407gmsQTHeight( ) ........................ 407gmsQTimerEventMask( ) ......... 138gmsQTPath( ) ........................... 407gmsQTPrec( ) ........................... 407gmsQTraceNum( ) .................... 278gmsQTrapSignalMode( ) .......... 411gmsQTRectTextConstraint( ) ... 409gmsQTSizeX( ) ......................... 407gmsQTSizeY( ) ......................... 407gmsQTStringC( ) ...................... 401gmsQTStringSO( ) ................... 401gmsQTStringWC( ) .................. 401gmsQuery( ) ............................. 308gmsQuit( ) ................................. 344

gmsQUserData( ) ..................... 422gmsQUserWord( ) .................... 422gmsQUseShadowMode( ) ......... 85gmsQVarDefAddress( ) ............. 90gmsQVarDefCount( ) ................. 90gmsQVarDefName( ) ................. 90gmsQVarDefSize( ) .................... 90gmsQVarDefType( ) ................... 90gmsQVarRefAddr( ) ................... 94gmsQVarRefName( ) ................. 94gmsQVDTCount( ) ..................... 96gmsQVDTVarDefAtIndex( ) ....... 96gmsQVDTVarDefByName( ) ..... 96gmsQVersion( ) ........................ 347gmsQVis( ) ............................... 436gmsQVuLocCaptureMode( ) ... 424gmsQWidgetId( ) ...................... 482gmsQWinBannerName( ) ........ 480gmsQWindowId( ) .................... 480gmsQWinExt( ) ......................... 480gmsQWinIconName( ) ............. 480gmsQWorkst( ) ......................... 480gmsQWsBackgroundColor( ) .. 448gmsQWsBitplaneMask( ) ........ 451gmsQWsColDef( ) .................... 482gmsQWsColormapId( ) ............ 482gmsQWsColormapIndex( ) ...... 482gmsQWsCursor( ) ...................... 43gmsQWsCursorInfo( ) ................ 43gmsQWsCursorNames( ) .......... 43gmsQWsEchoMask( ) .............. 482gmsQWsEventMask( ) ............. 462gmsQWsFontNameIndex( ) ..... 160gmsQWsNumColors( ) ............ 482gmsQWsPopMode( ) ............... 482gmsQWsView( ) ....................... 482gmsQWsViewport( ) ................ 482gmsQXPointList( ) .................... 287gmsRadius( ) ............................ 310gmsRastOp( ) ........................... 316

SL-GMS Function Reference viiVersion 6.2a- 26 May 2006

gmsRect( ) ................................ 319gmsRedraw( ) ........................... 415gmsRedrawNoErase( ) ............ 415gmsRefPoint( ) ......................... 322gmsRefPointX( ) ....................... 322gmsRefPointY( ) ....................... 322gmsRemUserFctn( ) ................. 418gmsRemVarDefLinks( ) ........... 107gmsRenamedStr( ) ..................... 70gmsRenamedStrNoRelink( ) ..... 70gmsRenVarStrConstReplSO( ) . 70gmsResChk( ) .......................... 426gmsRFRect( ) ........................... 319gmsRFTRect( ) ......................... 319gmsRMove2( ) .......................... 325gmsRMoveX( ) .......................... 325gmsRMoveY( ) .......................... 325gmsRRect( ) ............................. 319gmsRRotZ( ) ............................. 328gmsRScale( ) ............................ 330gmsRScaleX( ) ......................... 330gmsRScaleY( ) ......................... 330gmsRSTran( ) ........................... 167gmsRTran( ) .............................. 333gmsRvrsPts( ) ........................... 290gmsSec2( ) ............................... 337gmsSec3( ) ............................... 337gmsSect( ) ................................ 337gmsSetFileFindFctn( ) ............. 153gmsSetTraps( ) ......................... 411gmsSetup( ) .............................. 344gmsSNPXY( ) ........................... 273gmsSpline( ) ............................. 350gmsSRApplyLocFileSO( ) ....... 190gmsSt30Flag( ) ......................... 375gmsStActivate( ) ....................... 363gmsStAddModelName( ) ......... 363gmsStartAngle( ) ...................... 340gmsStateClass( ) ..................... 356gmsStateInst( ) ......................... 363

gmsStAutoDeactFlag( ) ........... 352gmsStClassFindByName( ) ..... 375gmsStClassInstall( ) ................ 356gmsStClearFlag( ) .................... 352gmsStClrModelNames( ) ......... 363gmsStD1Flag( ) ........................ 352gmsStDatFlag( ) ....................... 352gmsStDeactivate( ) .................. 363gmsStDebugFlag( ) .................. 375gmsStEventFctn( ) ................... 375gmsStFindByName( ) .............. 375gmsStFindVarDefAll( ) ............. 382gmsStFindVarDefByAddrAll( ) 382gmsStFindVarDefByNameAll( ) 382gmsStFreeAllVarDefs( ) ........... 382gmsStFreeFlag( ) ..................... 352gmsStGismoFlag( ) .................. 352gmsStLocMotionEnable( ) ....... 359gmsStM2Flag( ) ....................... 375gmsStMark( ) ............................ 369gmsStPopFlag( ) ...................... 352gmsStPStrMsg( ) ...................... 371gmsStPStrMsg1( ) ................... 371gmsStPStrMsg2( ) ................... 371gmsStReset( ) .......................... 369gmsStResetToMark( ) .............. 369gmsStResetToTop( ) ................ 369gmsStress( ) ............................. 389gmsStringC( ) ........................... 208gmsStringEmpty( ) ................... 208gmsStringResource( ) ............. 190gmsStringSetC( ) ..................... 208gmsStringSetWC( ) .................. 208gmsStringWC( ) ....................... 208gmsStStrMsg( ) ........................ 371gmsStStrMsg1( ) ...................... 371gmsStStrMsg2( ) ...................... 371gmsStStrMsgNI( ) .................... 371gmsStStrMsgNI1( ) .................. 371gmsStStrMsgNI2( ) .................. 371

SL-GMS Function Reference viiiVersion 6.2a- 26 May 2006

gmsStTextEditObj( ) ................. 363gmsStTextEditObjName( ) ....... 363gmsStUpdFlag( ) ...................... 352gmsStVarChanged( ) ............... 382gmsStVarDefAddress( ) ........... 386gmsStVarDefChanged( ) ......... 382gmsStVarDefCount( ) ............... 386gmsStVarDefine( ) .................... 382gmsStVarDefineChanged( ) .... 382gmsStVarDefSize( ) ................. 386gmsStVarInitFctn( ) .................. 382gmsStViewName( ) .................. 363gmsStVisFlag( ) ........................ 352gmsStWasFreed( ) ................... 375gmsStWorkstName( ) .............. 363gmsSubModelName( ) ............. 261gmsSubModReplicateMode( ) 261gmsSWPXY( ) .......................... 487gmsTAlign( ) ............................. 396gmsTColor( ) .............................. 36gmsText( ) ................................. 401gmsTFont( ) .............................. 396gmsTHeight( ) ........................... 396gmsTimeLevel( ) ....................... 281gmsTimerEventFctn( ) ............. 138gmsTimerPeriod( ) ................... 138gmsTPath( ) .............................. 396gmsTPrec( ) .............................. 396gmsTPrec0RotFlag( ) .............. 396gmsTran( ) ................................. 342gmsTran0( ) .............................. 335gmsTrapSignalMode( ) ............ 411gmsTRectTextConstraint( ) ..... 409gmsTRepl( ) .............................. 401gmsTSize( ) .............................. 396gmsTStr( ) ................................. 396gmsTStringC( ) ......................... 401gmsTStringSO( ) ...................... 401gmsTStringWC( ) ..................... 401gmsUnFillGroup( ) ................... 185

gmsUnlinkVarDefs( ) ................ 107gmsUpdate( ) ........................... 415gmsUpdateDisplayOnly( ) ....... 415gmsUpdateEraseOnly( ) .......... 415gmsUpdateExtents( ) ............... 415gmsUserData( ) ........................ 422gmsUserMarkerFctn( ) ............ 229gmsUserWord( ) ....................... 422gmsUseShadowMode( ) ............ 85gmsValueLimits( ) .................... 174gmsVarChanged( ) ................... 107gmsVarChangedAll( ) .............. 107gmsVarDefAddress( ) ................ 90gmsVarDefChanged( ) ............. 107gmsVarDefCount( ) .................... 90gmsVarDefine( ) ....................... 107gmsVarDefineChanged( ) ........ 107gmsVarDefineNoTable( ) ......... 107gmsVarDefSize( ) ....................... 90gmsVarDefType( ) ...................... 90gmsVarInitFctn( ) ....................... 81gmsVarTypeDefine( ) ............... 107gmsVDTIndicesChanged( ) ....... 96gmsView( ) ................................ 426gmsVis( ) .................................. 436gmsVuDim( ) ............................. 426gmsVuFindObject( ) ................. 157gmsVuList( ) ............................. 426gmsVuLocCaptureMode( ) ...... 424gmsVuPri( ) ............................... 426gmsVuRedrawOnNextUpdate( ) 424gmsVuRFile( ) .......................... 314gmsVuRRest( ) ......................... 314gmsVuRSave( ) ........................ 314gmsVuWorkst( ) ........................ 426gmsWaitEvent( ) ....................... 130gmsWCoordX( ) ....................... 487gmsWCoordY( ) ....................... 487gmsWCScale( ) ........................ 487gmsWinBannerName( ) ........... 439

SL-GMS Function Reference ixVersion 6.2a- 26 May 2006

gmsWinClear( ) ........................ 439gmsWind( ) ............................... 431gmsWinDestroy( ) .................... 439gmsWindowDestructionFctn( ) 439gmsWindXY( ) .......................... 431gmsWinExt( ) ............................ 439gmsWinFlags( ) ........................ 439gmsWinIconName( ) ................ 439gmsWinMap( ) .......................... 439gmsWinPop( ) ........................... 439gmsWinPts( ) ............................ 431gmsWinPush( ) ......................... 439gmsWinSetFocus( ) ................. 439gmsWinUnmap( ) ..................... 439gmsWorkst( ) ............................ 469gmsWPoint( ) ............................ 487gmsWPXY( ) ............................. 487gmsWsAct( ) ............................. 469gmsWsAddCursor( ) .................. 43gmsWsAddEvent( ) .................. 120gmsWsBackgroundColor( ) ..... 448gmsWsBitplaneMask( ) ............ 451gmsWsClear( ) ........................... 32gmsWsClose( ) ......................... 469gmsWsColDef( ) ....................... 451gmsWsCursor( ) ......................... 43gmsWsDeact( ) ......................... 469gmsWsDefaultOpts( ) .............. 469gmsWsEchoMask( ) ................. 469gmsWsEventFctn( ) ................. 462gmsWsEventMask( ) ................ 462gmsWsKbdFilterFctn( ) ............ 462gmsWsLocEcho( ) .................... 469gmsWsLowEventFctn( ) ........... 462gmsWsNum( ) ........................... 426gmsWsPointDCToIC( ) ............. 460gmsWsPort( ) ........................... 439gmsWsPortXY( ) ...................... 439gmsWsProcArgs( ) ................... 469gmsWsProcArgsStr( ) .............. 469

gmsWsSoftClip( ) ..................... 426gmsWsSynchronize( ) ............. 462gmsWsTextEditObj( ) ............... 462gmsWsWind( ) .......................... 439gmsWsWindXY( ) ..................... 439gmsWValue( ) ........................... 487gmsWVXY( ) ............................. 431gmsXKillTimer( ) ...................... 411gmsXTran( ) ................................ 13gmsXTran1( ) .............................. 13gmsXValueLimits( ) .................. 178gmsYesFlag( ) .......................... 344gmsYValueLimits( ) .................. 178gmsZmIn( ) ............................... 434gmsZmOut( ) ............................ 434gmsZoom( ) .............................. 434gmsZpr( ) .................................. 434gmsZps( ) ................................. 434

MmsDsMsg1( ) .............................. 59msQVarDefTable( ) .................... 96

PpntClone( ) ................................ 292pntFree( ) .................................. 292pntNew( ) .................................. 292pntNewXY( ) ............................. 292pntSetXY( ) ............................... 292pntX( ) ....................................... 292pntY( ) ....................................... 292

RrefAdd( ) .................................... 215refAppend( ) ............................. 215refAt( ) ....................................... 215refAtInsert( ) ............................. 215refAtPut( ) ................................. 215refCloAll( ) ................................ 215refCount( ) ................................ 215

SL-GMS Function Reference xVersion 6.2a- 26 May 2006

refDo1All( ) ............................... 215refDo2All( ) ............................... 215refDo3All( ) ............................... 215refDo4All( ) ............................... 215refDoAll( ) ................................. 215refDupAll( ) ............................... 215refFilter( ) .................................. 215refFind( ) ................................... 215refFndName( ) .......................... 215refFreAll( ) ................................. 215refFree( ) ................................... 215refIndex( ) ................................. 215refKilAll( ) .................................. 215refLast( ) ................................... 215refNew( ) ................................... 215refNewN( ) ................................ 215refNewRef( ) ............................. 215refQReference( ) ...................... 215refQSuccessor( ) ...................... 215refRemove( ) ............................. 215refReplace( ) ............................. 215

SL-GMS Function Reference xiVersion 6.2a- 26 May 2006

sl-gms function referencesldownloads.sl.com › docs › c++dev › 6.2x › pdffiles › fref ›...

Documents