Sl-gms Function Reference

Transcript

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 should not be construed as a commitment by the Sherrill-Lubinski Corporation. The Sherrill-Lubinski Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used 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 Reference This manual is for use only in connection with the described software and may not be used for any commercial purpose or copied, distributed, sold, displayed, modified, published, or posted in whole or in part without the prior written permission of Sherrill-Lubinski Corporation. SL-GMS, SL Corporation, the SL Logo, and all Sherrill-Lubinski product names referenced in this manual are trademarks or registered trademarks of the Sherrill-Lubinski Corporation; any unauthorized use of these marks is strictly prohibited. All trademarks and registered trademarks referenced in this document are property of their respective companies. SL-GMS (6.2x) 26 May 2006 Configuration: 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 as set forth in the Technical Data - Commercial Items clause at DFARS 252.227-7015, the Rights in Data - General clause at FAR 52.227-14, and any other applicable provisions of the DFARS, FAR, or the NASA FAR supplement. SL CORPORATION 240 Tamal Vista Blvd. Corte Madera, CA 94925 CUSTOMER SUPPORT Phone 800.548.6881 (inside U.S.) 415.927.8400 Fax 415.927.8401 E-mail [email protected] 5/26/06 v6.2x Table of Contents 1. SL-GMS Function Reference Absolute move......................................................................................... 5 Absolute rotation ..................................................................................... 8 Absolute scale ......................................................................................... 10 Apply Transformation ............................................................................. 13 Background ............................................................................................. 15 Bitmap object .......................................................................................... 20 Center point ............................................................................................. 24 Circle object ............................................................................................ 28 Class query .............................................................................................. 30 Clear ........................................................................................................ 32 Clone ....................................................................................................... 33 Closure attribute ...................................................................................... 34 Color........................................................................................................ 36 Current object.......................................................................................... 40 Cursor ...................................................................................................... 43 Datasource — ".dat" files........................................................................ 51 Datasource — class ................................................................................. 52 Datasource — Instance............................................................................ 54 Datasource — Lists ................................................................................. 57 Datasource — messages.......................................................................... 59 Directories and paths ............................................................................... 62 Display, erase, highlight.......................................................................... 65 Dump....................................................................................................... 68 Dynamics — double-buffering................................................................ 69 Dynamics — DynProps/RenamedVariables ........................................... 70 Dynamics — erasure ............................................................................... 78 Dynamics — initialize, update, restore, end ........................................... 81 Dynamics — optimization ...................................................................... 85 Dynamics — query and set Variable Definition attributes ..................... 90 Dynamics — query Variable References ................................................ 94 Dynamics — Variable Definition Table attached to Models .................. 96 Dynamics — variables ............................................................................ 107 Edge width attribute ................................................................................ 118 Events — create ...................................................................................... 120 Events — miscellaneous ......................................................................... 130 Events — query....................................................................................... 132 Version 6.2a- 26 May 2006 SL-GMS Function Reference i Events — timer........................................................................................ 138 Events — Xt and X applications ............................................................. 140 Extent ...................................................................................................... 143 Fill direction and fill percent attributes ................................................... 148 Filled........................................................................................................ 151 Find file ................................................................................................... 153 Find object............................................................................................... 157 Font Name Index..................................................................................... 160 Free object ............................................................................................... 162 General transformation — absolute ........................................................ 164 General transformation — relative.......................................................... 167 GISMOs — initialization ........................................................................ 169 GISMOs — processing ........................................................................... 170 Gradient fill attribute............................................................................... 171 GraphAxis object..................................................................................... 174 GraphTrace object ................................................................................... 178 Grid object............................................................................................... 181 Group object............................................................................................ 185 Group object - redrawing ........................................................................ 189 Internationalization — localization files ................................................. 190 Internationalization — String object ....................................................... 208 Line object............................................................................................... 214 LinkRef object......................................................................................... 215 Main — SL-GMS main functions ........................................................... 223 Marker — custom.................................................................................... 229 Marker — object ..................................................................................... 233 Marker — size attribute........................................................................... 234 Message tracing....................................................................................... 236 Model — object....................................................................................... 237 Model — save, get, merge ...................................................................... 240 Model — save, get from pseudo-files ..................................................... 244 Model — user header string .................................................................... 258 Model Instance (ModInst) object ............................................................ 261 Model Instance (ModInst) — caching .................................................... 269 NDC (Normalized Device Coordinates) ................................................. 273 Object — name........................................................................................ 275 Object — owner ...................................................................................... 276 Version 6.2a- 26 May 2006 SL-GMS Function Reference ii Object — parts ........................................................................................ 278 Performance optimization ....................................................................... 281 Pie object ................................................................................................. 282 Plotted Points........................................................................................... 284 Point Lists................................................................................................ 287 Point Lists — replace .............................................................................. 290 Point object.............................................................................................. 292 Polygon object......................................................................................... 296 PostScript ................................................................................................ 298 Projects .................................................................................................... 306 Query user ............................................................................................... 308 Radius set and get.................................................................................... 310 Raster image of objects — save and restore ........................................... 311 Raster image of View — save, restore, create ........................................ 314 Raster Operation Mode attribute ............................................................. 316 Rectangle object ...................................................................................... 319 Reference Point ....................................................................................... 322 Relative move.......................................................................................... 325 Relative rotation ...................................................................................... 328 Relative scale........................................................................................... 330 Relative transformation ........................................................................... 333 Reset transformation ............................................................................... 335 Sector object............................................................................................ 337 Sectors, Pies, Splines — miscellaneous .................................................. 340 Set transformation ................................................................................... 342 Setup, quit, close SL-GMS...................................................................... 344 SL-GMS Installation Directory — query................................................ 346 SL-GMS Libraries — version, configuration, date................................. 347 Spline object............................................................................................ 350 State — attributes .................................................................................... 352 State — class ........................................................................................... 356 State — initialization............................................................................... 359 State — Instance...................................................................................... 363 State — mark and reset ........................................................................... 369 State — messaging .................................................................................. 371 State — miscellaneous ............................................................................ 375 State — query.......................................................................................... 378 Version 6.2a- 26 May 2006 SL-GMS Function Reference iii State — variables .................................................................................... 382 State — variables, set and query attributes ............................................. 386 Stress attribute ......................................................................................... 389 Style attribute .......................................................................................... 391 SubModel List ......................................................................................... 394 Text — attributes..................................................................................... 396 Text — object.......................................................................................... 401 Text — query attributes........................................................................... 407 Text Rectangle — constraint attribute .................................................... 409 Traps — signal handling ......................................................................... 411 Update ..................................................................................................... 415 User-defined functions ............................................................................ 418 UserData and UserWord ......................................................................... 422 View — miscellaneous............................................................................ 424 View — object ........................................................................................ 426 View — WC-window and Viewport....................................................... 431 View — zoom and pan............................................................................ 434 Visibility and detectability attributes ...................................................... 436 Workstation/Window — attribute changes ............................................. 439 Workstation/Window — background color ............................................ 448 Workstation/Window — bitplanes.......................................................... 451 Workstation/Window — coordinate conversion..................................... 460 Workstation/Window — events .............................................................. 462 Workstation/Window — object .............................................................. 469 Workstation/Window — Window query ................................................ 480 Workstation/Window — Workstation query .......................................... 482 World Coordinates .................................................................................. 487 Index Function Name Index Version 6.2a- 26 May 2006 SL-GMS Function Reference iv Sherrill−Lubinski SL-GMS Function Reference How to use this manual This manual provides information concerning the use of the SL-GMS Run-time Functions as part of C language programs. This manual is divided into many sections, each containing a group of related functions. Each section is comprised of the following parts: 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 This manual is designed for quick and versatile reference: 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 1 SL-GMS data types In addition to the normal C types used as arguments or returned from functions, SL-GMS defines several additional data types. The following are the pointer types: Pointer Type id idPoint idLinkRef Attribute class pointer class pointer xy coordinates class pointer successor pointer reference pointer Description to arbitrary object to a Point object to a LinkRef object The ".h" files for all SL-GMS objects are distributed in the lib directory. Version 6.2a- 26 May 2006 SL-GMS Function Reference 2 SL-GMS Run-time Functions: return values SL-GMS functions return a 1 when they are successful, and a 0 when they have 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 success. 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 or ref. The gms*( ) functions operate on the graphics portion of the SL-GMS system itself, while the others are support functions primarily used for constructing Points, and Lists, which are used as arguments for the gms*( ) set of functions. Programming notes Ordering of include files SL-GMS application programs written in C begin with include files which must be listed in the following order: 1. "gms.h" 2. 3. 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 functions. The type id is defined as a generic pointer to an object, for example. Functions returning non-integer values are also declared through this header 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". Version 6.2a- 26 May 2006 SL-GMS Function Reference 3 EXPORT/IMPORT macro definitions Most SL-GMS objects are defined as type id. variable to hold a View object is created. In the statement below, a EXPORT id v_main = 0; The location of this statement outside of a function makes it available for use by other source code modules. The word EXPORT is a C language macro definition convention used in SL-GMS to clearly indicate that a variable is available for use by other source modules. On most platforms, the above statement is equivalent to id v_main = 0; The statement below creates a reference to an SL-GMS State object that is defined in another source code module. IMPORT id appl_top;/* States in the application */ The word IMPORT is a C language macro definition convention used in SL-GMS to clearly indicate that a variable is defined in another source module. On most platforms, the above statement is equilvalent to extern id appl_top; Application command-line argument processing The gmsWsProcArgs( ) function is used in an application program to process any options given in the command line. The section Workstation/Window — object on page 469 describes the gmsWsProcArgs( ) function. It is also called by the gmsMainInit( ) function, as documented in the section Main — SL-GMS main functions on page 223. The gmsWsPsProcArgs() function may be called to process command-line PostScript options. The section PostScript on page 298 provides more information. Version 6.2a- 26 May 2006 SL-GMS Function Reference 4 Absolute move Absolute move SUMMARY APPLY an absolute move transformation NAME gmsAMove2( ), gmsLAMove2( ), gmsMAMove2( ), gmsAMoveX( ), gmsAMoveY( ), gmsLAMoveX( ), gmsLAMoveY( ), gmsMAMoveX( ), gmsMAMoveY( ) SYNTAX int gmsAMove2 (obj, point) d obj; idPoint point; int gmsLAMove2 (objlist, point) idLinkRef objlist; idPoint point; int gmsMAMove2 (point) idPoint point; int gmsAMoveX (obj, mx) id obj; int mx; int gmsAMoveY (obj, my) id obj; int my; Version 6.2a- 26 May 2006 SL-GMS Function Reference 5 Absolute move int gmsLAMoveX (objlist, mx) idLinkRef objlist; int mx; int gmsLAMoveY (objlist, my) idLinkRef objlist; int my; int gmsMAMoveX (mx) int mx; int gmsMAMoveY (my) int my; DESCRIPTION These functions define absolute move transformations. Absolute transformations replace any current transformation matrix. The object is erased, the transformation applied, and the object is redrawn. The erase 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 the gmsLAMove2( ) function operates on a List of objects. The gmsMAMove2( ) function sets a modal offset transformation, which applies to all objects subsequently created. The point argument specifies the location to which the object is moved, and must be a pointer to a Point object. With the gmsAMoveX( ) and gmsAMoveY( ) functions, the other coordinate is set to 0. The mx and my arguments specify the distance that the object is to be translated. The user is responsible for scaling the integer argument by the World Coordinate Scale Factor using gmsWValue( ). The gmsAMove2( ) function, or gmsLAMove2( ), should be used to move an object in both the x and y directions. Calling gmsAMoveX( ) and then gmsAMoveY( ) produces a different result than calling Version 6.2a- 26 May 2006 SL-GMS Function Reference 6 Absolute move gmsAMove2( ) because an absolute move forces an object to move back to its initial position before applying the move. The gmsAMoveX( ) function should be used to move an object in only the x direction and gmsAMoveY( ) should be used to move an object in only the y direction. EXAMPLE To move an object 10 units in the x direction, the gmsWValue( ) function is used to convert World Coordinate units to Internal Coordinates (integer representation). gmsAMoveX (obj, gmsWValue(10.0)); SEE ALSO gmsRMove2( ), gmsLRMove2( ), gmsCRMv2( ), gmsMRMove2( ), gmsXTran( ), gmsRefPoint( ) The gmsXTran( ) function is used to apply existing gmsWValue( ) transformations to the object’s Points. The gmsRMove2( ) function is used to combine the translation with existing transformations. The Reference Point for an object is set by the gmsRefPoint( ) function. SL-GML COMMANDS name amove x y name amovex x name amovey y Version 6.2a- 26 May 2006 SL-GMS Function Reference 7 Absolute rotation Absolute rotation SUMMARY set an absolute rotation NAME gmsARotZ( ), gmsLARotZ( ), gmsMARotZ( ) SYNTAX int gmsARotZ (obj, angle) id obj; double angle; int gmsLARotZ (objlist, angle) idLinkRef objlist; double angle; int gmsMARotZ (point, angle) idPoint point; double angle; DESCRIPTION These functions define absolute z-axis rotation transformations. Absolute transformations replace any current transformation matrix. The object is erased, the transformation applied, and the object is redrawn. The erase and redisplay occur the next time an update pass occurs — immediately if Immediate Update Mode is set. The gmsARotZ( ) function operates on an individual object, while the gmsLARotZ( ) function operates on a List of objects. The rotation Version 6.2a- 26 May 2006 SL-GMS Function Reference 8 Absolute rotation angle is a double counterclockwise. argument specified as degrees to rotate The gmsMARotZ( ) function sets a modal rotation transformation which applies to all objects subsequently created. The point argument is the center of rotation and must be a a pointer to a Point object. If the argument is nil, the Point (0,0) is assumed. SEE ALSO gmsRRotZ( ), gmsLRRotZ( ), gmsXTran( ), gmsRefPoint( ) gmsCRRotz( ), gmsMRRotZ( ), The gmsXTran( ) function is used to apply existing transformations to the object’s Points, or gmsRRotZ( ) is used to combine the translation with existing transformations. The Reference Point for an object or List of objects is set by the gmsRefPoint( ) function. SL-GML COMMAND name arotz angle Version 6.2a- 26 May 2006 SL-GMS Function Reference 9 Absolute scale Absolute scale SUMMARY set an absolute 2D scale transformation NAME gmsAScale( ), gmsLAScale( ), gmsMAScale( ), gmsAScaleX( ), gmsAScaleY( ), gmsLAScaleX( ), gmsLAScaleY( ), gmsMAScaleX( ), gmsMAScaleY( ), gmsCASca2( ) SYNTAX int gmsAScale (obj, sxy) id obj; double sxy; int gmsLAScale (objlist, sxy) idLinkRef objlist; double sxy; int gmsMAScale (point, sx, sy) idPoint point; double sx; double sy; int gmsAScaleX (obj, sx) id obj; double sx; int gmsAScaleY (obj, sy) id obj; double sy; Version 6.2a- 26 May 2006 SL-GMS Function Reference 10 Absolute scale int gmsLAScaleX (objlist, sx) idLinkRef objlist; double sx; int gmsLAScaleY (objlist, sy) idLinkRef objlist; double sy; int gmsMAScaleX (point, sx) idPoint point; double sx; int gmsMAScaleY (point, sy) idPoint point; double sy; int gmsCASca2 (point, sx, sy) idPoint point; double sx; double sy; DESCRIPTION These functions define absolute scale transformations. Absolute transformations replace any current transformation matrix. The object is erased, the transformation applied, and the object is redrawn. The erase 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 the gmsLAScale( ) function operates on a List of objects. The gmsMAScale( ) function sets a modal scale transformation which applies to all objects subsequently created. The x and y scale factors must be double arguments. If x or y is not specified, it is set to 1.0. The point argument is the center of scaling Version 6.2a- 26 May 2006 SL-GMS Function Reference 11 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 or Instances. The gmsAScale( ) function (or gmsLAScale( )) should be used to scale an object in both the x and y directions. Calling gmsAScaleX( ) and then gmsAScaleY( ) produces a different result than calling gmsAScale( ) because an absolute scale forces an object to scale back to its initial size before applying the scale. The gmsAScaleX( ) function should be used to scale an object in only the x direction and gmsAScaleY( ) should be used to scale an object in only the y direction. SEE ALSO gmsRScale( ), gmsLRScale( ), gmsXTran( ), gmsRefPoint( ) gmsCRSca2( ), gmsMRScale( ), The gmsXTran( ) function is used to apply existing transformations to the object’s Points, or gmsRScale( ) is used to combine the translation with existing transformations. The Reference Point for an object or List of objects is set by the gmsRefPoint( ) function. SL-GML COMMANDS name ascale x y name ascalex x name ascaley y Version 6.2a- 26 May 2006 SL-GMS Function Reference 12 Apply Transformation Apply Transformation SUMMARY apply the transformation to the Points of an object; apply an object’s transformation one level deep NAME gmsXTran( ), gmsLXTran( ), gmsXTran1( ), gmsLXTran1( ) SYNTAX int gmsXTran (obj) id obj; int gmsLXTran (objlist) idLinkRef objlist; int gmsXTran1 (obj) id obj; int gmsLXTran1 (objlist) idLinkRef objlist; DESCRIPTION These 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 the objects. 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 their appearance or position. When transformations are applied to objects, a representation of the transformation (a matrix) is stored with the object. The Points that Version 6.2a- 26 May 2006 SL-GMS Function Reference 13 Apply Transformation define an object are not modified so that multiple transformations do not induce incremental errors in the Points. Storing the transformation matrix around requires overhead which can be eliminated by applying the transformations directly to the Points using the gmsXTran( ) functions. Often this is done after a Model has been made with SL-DRAW2 or SL-DRAW to reduce the storage overhead associated with the Model. In some cases the application of the tranformation has no effect. For example, if a Rectangle is rotated, applying the rotation transformation to the two defining Points of the Rectangle is not permitted because the operation would completely change the Rectangle. The gmsXTran1( ) function applies an object’s transformation matrix to its sub-objects one level deep. This function is used when a Group is freed without destroying its parts. The Group object may have a transformation applied that also applies to its parts. If a Group object is freed, its transformation must be applied to the objects in its Parts List, or those objects are redisplayed where they were created before being transformed as a Group. The gmsLXTran1( ) function performs the gmsXTran1( ) functionality for each object in a List of objects. SEE ALSO gmsDeGroup( ), gmsQPointList( ) SL-GML COMMAND [name] xtran Version 6.2a- 26 May 2006 SL-GMS Function Reference 14 Background Background SUMMARY set a Model’s background flag; query a Model’s background flag NAME gmsBackgrFlag( ), gmsQBackgrFlag( ) SYNTAX int gmsBackgrFlag (model, flag) id model; /* Model */ int flag; /* background flag = G_ON/G_OFF */ int gmsQBackgrFlag (model) id model; DESCRIPTION The gmsBackgrFlag( ) function sets a Model’s background flag. If the background flag is set to G_ON, the Model erases objects in the fill color of the first object in the Model, if the object is filled. The color used by the Model to erase objects is called the background color. If the first object is not filled, or there are no objects in the Model, the background color is set to the Workstation/Window background color (refer to the section Workstation/Window — background color on page 448). The background color is used as the erase color for all objects in the Model except for parts within a SubModel Instance which has its own background color. To change the background color, the fill color of the first object in the Model must be changed. Usually the first object in the Model is a Filled Rectangle that covers the entire workspace. This is the background object on top of which other objects are drawn and erased. Normally, objects are erased using color Version 6.2a- 26 May 2006 SL-GMS Function Reference 15 Background 0. If the background object is not also color 0 (white), “holes” are left as objects are dynamically changed. An example of using the background flag is illustrated below. The needle representing the value of a variable moves over the “face” of the meter. The “face” of the meter is a large rectangle. Because it is the first object in the Model, it is the background object. Therefore, the background color of the Model is set to the same color as the “face” of the meter. With the background flag set to G_ON, the needle erases in the 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 the needle 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. This is illustrated in Figure 2. When the needle moves to 50, a white line Version 6.2a- 26 May 2006 SL-GMS Function Reference 16 Background appears at 0 because the needle erased in white on the grey background. 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 Model shown in Figure 3 the first object in the Model is a large yellow rectangle and therefore the background color is yellow when the background flag is set to G_ON. yellow grey red Figure 3.A sample Model with background flag on With the background flag set to G_ON, the red circles, using yellow as the erase color, will leave yellow “holes” in the grey rectangles at the Version 6.2a- 26 May 2006 SL-GMS Function Reference 17 Background old position as the circles are moved to a new position. This is shown in Figure 4. new position old position 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 object must have a Fill color of grey. Since the first object in the present Model is a large yellow rectangle, another object (e.g., a large rectangle) with a Fill color of grey must be created and made the first object in the Model using the Back Of All option of the Order Pull-Down Menu in SL-DRAW2. In addition, since this grey object is only being created so it can set the background color and it is not to be seen, it must be made invisible using the Vis Off option of the Convert Pull-Down Menu. The background flag may be set on Models and SubModels to provide different background colors in different portions of a Model. If a SubModel is created with the background flag set to G_ON and it is then Instanced into a top-level Model which also has the background flag set to G_ON, the objects within the SubModel are erased using the background color of the SubModel, but the SubModel Instance is erased using the background color of the top-level Model. Version 6.2a- 26 May 2006 SL-GMS Function Reference 18 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. MODEL A SubModel B SubModel C Figure 5.Model “A” with SubModels “B” and “C” If a background is not specified for a SubModel, the objects are erased in the background color of the parent Model. In SL-DRAW2, the background flag is toggled ON and OFF by clicking the Backgr button in the Color Attribute Control Panel. When the background flag is ON, the Backgr button becomes selectable. To change the background color of the Model (i.e., the fill color of the first object in the Model), click the appropriate color in the Color Attribute Control Panel when the Backgr button is highlighted. Both the color bar to the right of the Backgr button and the fill color of the first object in the Model will change to the selected background color. The gmsQBackgrFlag( ) function queries a Model’s background flag. Version 6.2a- 26 May 2006 SL-GMS Function Reference 19 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 id gmsBitmap (name, filename, point) char *name; char *filename; idPoint point; int gmsQRastOp (bitmap) id bitmap; int gmsBitmapFlag (obj, flag) id obj; /* Bitmap object */ int flag; /* G_BTM_NO_TRANS or G_BTM_TRANS_IMPULSE */ int gmsLBitmapFlag (list, flag) id list; /* List of Bitmap objects */ int flag; /* G_BTM_NO_TRANS or G_BTM_TRANS_IMPULSE */ int gmsMBitmapFlag (flag) int flag; /* G_BTM_NO_TRANS or G_BTM_TRANS_IMPULSE */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 20 Bitmap object int gmsQBitmapFlag (obj) id obj; /* Bitmap object */ DESCRIPTION The gmsBitmap( ) function creates Bitmap objects. The name is optional; a null string may be used as an argument. point positions the lower left corner of the Bitmap’s extent in the current Model. On the X platform, filename is an X Window dump file created with the gmsVuRFile( ) function or an X Window utility. For the Win32 platform, 1 filename is a Windows Bitmap file created with the gmsVuRFile( ) 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 file that matches is loaded. On Win32 platforms, the gmsBitmap( ) function will look for filename with a ".bmp" extension and then filename with a ".i" extension. The first file that matches is loaded. Bitmap objects are displayed by combining the Bitmap’s raster image with the raster image beneath the Bitmap. The manner in which the images are combined depends upon the Raster Operation Mode (or Bitmap Write Mode). Bitmap objects can be moved or scaled but they cannot be rotated. Bitmap objects are drawn by copying the raster image to the Workstation (there is currently no way to modify this raster image to rotate). Bitmaps are used to provide fast update and display of static images. The gmsQRastOp( ) operation. function returns a Bitmap object’s raster The gmsBitmapFlag( ) function sets a permanent bitmap flag on a Bitmap object. Possible values for flag are: 1. Win32 refers to a platform with a 32-bit architecture running Microsoft Windows NT or Windows 95. Version 6.2a- 26 May 2006 SL-GMS Function Reference 21 Bitmap object Bitmap Flag Description G_BTM_NO_TRAN S do not transform the Bitmap object G_BTM_TRANS_IM PULSE transform the Bitmap object using an impulse resampling filter Setting G_BTM_TRANS_IMPULSE causes a Bitmap to store a Reference Extent on itself on the next extent update pass. This Reference Extent is set to be the Internal Coordinate (IC) extent of the Bitmap. It is analogous to the lower-left and upper-right corner Points that define a Rectangle. This fixes the size of the Bitmap relative to other objects in the Model. When created, this reference is dependent upon any transformation in the Graphical Modeling Hierarchy (in the Appendix entitled SL-GMS System Organization of the SL-GMS Advanced Tutorial). Examples of transformations 2 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 to rescale its image whenever a transformation to the window, View, Model, or objects within the Model occurs. The Bitmap can only scale and translate its image; it cannot rotate the image. If the G_BTM_TRANS_IMPULSE flag is set, the Bitmap will rescale its image using an impulse filter kernel. This is the fastest possible filter kernel, but it often causes aliasing in the target image. An impulse filter is better at magnification than minification. When magnifiying an image with an impulse filter, pixels in the source image are replicated in 2. The chapter entitled Display of Models of the SL-GMS Reference provides an illustration of these transformations. Version 6.2a- 26 May 2006 SL-GMS Function Reference 22 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 to G_BTM_NO_TRANS, the Reference Extent is freed. It is recalculated, dependent upon any transformations in the Graphical Modeling Hierarchy, the next time the G_BTM_TRANS_IMPULSE flag is set on the object. SEE ALSO gmsRastOp( ), gmsLRastOP( ), gmsVuRFile( ) SL-GML COMMANDS [name:] bitmap fname x y [name:] bitmapflag bitmapflag Version 6.2a- 26 May 2006 SL-GMS Function Reference 23 Center point Center point SUMMARY set or get the center Point of Circle, Sector, and Pie objects NAME gmsCenter( ), gmsLCenter( ), gmsQCenter( ) SYNTAX int gmsCenter (obj, center) id obj; idPoint center; int gmsLCenter (objlist, center) idLinkRef objlist; idPoint center; idPoint gmsQCenter (obj) id obj; DESCRIPTION The gmsCenter( ) function sets the center Point for Circle, Sector, and Pie objects. Changing the center does not affect the radius. The gmsLCenter( ) function changes the center for a List of objects. The gmsQCenter( ) function returns a copy of the center Point only for Circle, Sector and Pie objects, and returns zero for all other types of objects. The returned Point should be freed with pntFree( ). For objects other than a Circle, Sector, or Pie, the gmsQExtCenter( ) function (described on page 144) should be used to find the center of the extent of the object. The table page 26 illustrates, using an "X", the Version 6.2a- 26 May 2006 SL-GMS Function Reference 24 Center point center Point of a Circle, Sector, and Pie object, 1 as well as extent centers 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( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 25 Center point Center Point and center of extent Center Point returned from gmsQCenter( ) Object Rectangle Center of extent returned from gmsQExtCenter( ) zero (Use the function gmsQExtCenter( ) on page 144) Model Instance zero (Use the function gmsQExtCenter( ) on page 144) Group of objects zero (Use the function gmsQExtCenter( ) on page 144) Circle Version 6.2a- 26 May 2006 SL-GMS Function Reference 26 Center point Center Point and center of extent (continued) Object Center Point returned from gmsQCenter( ) Center of extent returned from gmsQExtCenter( ) Sector Pie SEE ALSO gmsLQExtCenter( ), gmsQExtCenter( ) The function returning the center of the extent for a List of objects is gmsLQExtCenter( ). The gmsQExtCenter( ) function returns a Point which locates the center of the extent of any SL-GMS object. SL-GML COMMAND name center x y Version 6.2a- 26 May 2006 SL-GMS Function Reference 27 Circle object Circle object SUMMARY create a Circle object NAME gmsCirc( ), gmsCir2( ), gmsFCirc( ), gmsFCir2( ) SYNTAX id gmsCirc (name, point, radius) char *name; idPoint point; double radius; id gmsCir2 (name, pointlist) char *name; idLinkRef pointlist; id gmsFCirc (name, point, radius) char *name; idPoint point; double radius; id gmsFCir2 (name, pointlist) char *name; idLinkRef pointlist; DESCRIPTION The gmsCirc( ) function is used to create a Circle, given a center Point and a radius. The Circle is created using the current attributes. The Version 6.2a- 26 May 2006 SL-GMS Function Reference 28 Circle object radius is in World Coordinates and is multiplied by the World Coordinate Scale Factor. The gmsCir2( ) function creates a Circle, given a center Point and a Point which is on the radius. The Points must be passed in a Point List. The gmsFCirc( ) and gmsFCir2( ) functions are similar to their counterparts without the "F," but the Circles they create are filled. The name argument may be a null string, otherwise it is the name assigned to the object when it is added to the current Model. The current 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 29 Class query Class query SUMMARY reply whether an object belongs to a class NAME gmsObjIsClass( ), gmsObjIsClassName( ) SYNTAX int gmsObjIsClass (obj, aClass) id obj; struct ClassDef *aClass; int gmsObjIsClassName (obj, classname) id obj; char *classname; DESCRIPTION The gmsObjIsClass( ) function is used to test whether a given object is a member of a specific class. This function returns 1 when the object is a member of the class and 0 when it is not. Classes are defined in the C include file "gmscodes.h" in the lib subdirectory. The name of the object defined in the ".h" file is used with the gmsObjIsClass( ) function. The gmsObjIsClassName( ) function works in a similar manner to the gmsObjIsClass( ) function, returning 1 when an object is a member of the given class and 0 when it is not. The difference between the two functions is that gmsObjIsClassName( ) takes a class name string, or a macro as one of its parameters, while gmsObjIsClass( ) takes a pointer to a class definition object. Version 6.2a- 26 May 2006 SL-GMS Function Reference 30 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, and Marker is the class name for the G_MARKER class. The macro for the G_PRIM class name string is G_PRIM_NAME. It is recommended that the macros be used instead of the class name strings to ensure upward compatibility. 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 PartPrim class: if(gmsObjIsClass(anObject, PartPrim)) { . . . /* an Object is member */ } else { . . . /* an Object is not a member */ } Version 6.2a- 26 May 2006 SL-GMS Function Reference 31 Clear Clear SUMMARY clear a View, clear a Workstation, or clear all Workstations NAME gmsClear( ), gmsWsClear( ), gmsClrAllWs( ) SYNTAX int gmsClear (view) id view; int gmsWsClear (workst) id workst; int gmsClrAllWs( ) DESCRIPTION The gmsClear( ) function is used to clear the rectangular region defined by a View object. If nil is used as an argument, all Workstations are cleared. The gmsWsClear( ) function is used to clear an entire Workstation. All Workstations are cleared by calling gmsClrAllWs( ). DIAGNOSTICS At present, there is no way to specify a background color for a View. The clear color is determined by the Workstation. This functionality will be provided in a future release. SL-GML COMMANDS [name] clear [wsname] clear Version 6.2a- 26 May 2006 SL-GMS Function Reference 32 Clone Clone SUMMARY create a Clone of a Graphical Primitive object or List of objects NAME gmsClone( ), gmsLClone( ) SYNTAX id gmsClone (name, obj) char *name; id obj; int gmsLClone (objlist) idLinkRef objlist; DESCRIPTION The gmsClone( ) function is used to create a Clone of a SL-GMS Graphical Primitive object and add it to the current Model. The gmsLClone( ) function makes a copy of each object in the given List and adds the objects to the current Model’s Part List. A 1 is returned if all objects on the List are successfully duplicated, 0 if duplicating fails before traversing the entire List. SL-GML COMMAND [name:] clone Version 6.2a- 26 May 2006 SL-GMS Function Reference 33 Closure attribute Closure attribute SUMMARY set or reset closure NAME gmsClosed( ), gmsLClosed( ), gmsMClosed( ), gmsQClosed( ) SYNTAX int gmsClosed (obj, closed) id obj; int closed; int gmsLClosed (objlist, closed) idLinkRef objlist; int closed; int gmsMClosed (closed) int closed; int gmsQClosed (obj) id obj; DESCRIPTION The gmsClosed( ) function sets or resets the closure attribute for an object. With closure set to 1, the first and last Points in an object are connected with an Edge using the same Edge attributes used with the other Edges in the object. Lines, Splines, and Sectors may have the closure attribute. Resetting this attribute (making it 0) removes the Version 6.2a- 26 May 2006 SL-GMS Function Reference 34 Closure attribute Edge that connects the last two Points in the object. gmsMClosed( )function sets the modal closure attribute. The The gmsLClosed( ) function sets the closure attribute for all the objects in the given List. The gmsQClosed( ) function returns the closure attribute of the given object. SL-GML COMMANDS [name] closed int Version 6.2a- 26 May 2006 SL-GMS Function Reference 35 Color Color SUMMARY sets the color attribute for objects; set modal color for all objects or types of objects; query an object’s color attribute; change color table NAME gmsMColor( ), gmsEColor( ), gmsLMColor( ), gmsLEColor( ), gmsMMColor( ), gmsMEColor( ), gmsQColor( ), gmsQMColor( ), gmsQTColor( ), gmsCTB( ) gmsFColor( ), gmsLFColor( ), gmsMFColor( ), gmsQEColor( ), gmsTColor( ), gmsLTColor( ), gmsMTColor( ), gmsQFColor( ), SYNTAX int gmsMColor (obj, index) id obj; int index; int gmsEColor (obj, index) id obj; int index; int gmsFColor (obj, index) id obj; int index; int gmsTColor (obj, index) id obj; int index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 36 Color int gmsLMColor (objlist, index) idLinkRef objlist; int index; int gmsLEColor (objlist, index) idLinkRef objlist; int index; int gmsLFColor (objlist, index) idLinkRef objlist; int index; int gmsLTColor (objlist, index) idLinkRef objlist; int index; int gmsMMColor (index) int index; int gmsMEColor (index) int index; int gmsMFColor (index) int index; int gmsMTColor (index) int index; int gmsQColor (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 37 Color int gmsQMColor (obj) id obj; int gmsQEColor (obj) id obj; int gmsQFColor (obj) id obj; int gmsQTColor (obj) id obj; int gmsCTB (index, r,g,b, pen) int index; double r,g,b; int pen; DESCRIPTION This is a complete set of functions for the manipulation of the different color attributes supported by SL-GMS. The first group of functions applies to individual objects, the second to Lists of objects, and the third to the modal attributes. The fourth group of functions are color attribute Query functions. The character preceding the word "color" in Version 6.2a- 26 May 2006 SL-GMS Function Reference 38 Color the function name indicates whether the attribute applies to the color of Edges ("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 attribute used in an object. For example, the gmsQFColor( ) function returns the Fill color attribute used in a Fill object. The gmsQColor( ) function returns either the color index for any object that has a single color attribute, or the Fill color if the object has several color attributes, such as a Filled Text Rectangle. The gmsCTB( ) function is used to set the Red-Green-Blue color definition for a particular color index. This definition becomes a part of the current View. The pen number may be specified for devices like a pen-plotter which do not deal with RGB color. Color definitions are system-wide, and may also be established by using the "colordef.dat" file. DIAGNOSTICS No bounds checking is done for attributes. It is assumed that the device driver software, at the SL-GWS layer of SL-GMS, deals with the attributes appropriately. If an object is queried for an attribute not present in that object, the query function returns 0. For instance, querying a Text object for Edge color returns 0. SEE ALSO The 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 39 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 int gmsCurrent (obj) id obj; /* Group, Model, or View */ int gmsCurModel (model) id model; int gmsCurView (view) id view; int gmsCurGroup (group) id group; id gmsQCurrent( ) id gmsQCurModel( ) id gmsQCurView( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 40 Current object id gmsQCurGroup( ) int gmsEndCurrent( ) DESCRIPTION The 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-created Model active. This Model is the current Model until closed with gmsEndModel( ). A 0 is returned if the model argument is invalid. The gmsCurView( ) function sets the notion of the current View. top Model objects created go into the current View. Any The gmsCurGroup( ) function is used to make a previously-created Group active. This Group is the current Group until closed with gmsEndGroup( ). A 0 is returned if the group argument is invalid. The gmsQCurrent( ) query function returns a pointer to the current Group, Model, or View that is the lowest-level current object. The gmsQCurModel( ) query function returns a pointer to the current Model. The notion of the current Model is maintained by the System object. The gmsQCurView( ) query function returns a pointer to the current View. The gmsQCurGroup( ) query function returns a pointer to the current Group. The notion of the current Group is maintained by the System object. The gmsEndCurrent( ) function ends (closes) the lowest-level current object. EXAMPLE To close all open Models, the following code may be used: while (gmsQCurModel( )) gmsEndModel( ); Version 6.2a- 26 May 2006 SL-GMS Function Reference 41 Current object SEE ALSO gmsEndModel( ), gmsEndView( ), gmsGroup( ), gmsEndGroup( ) The Appendix entitled SL-GMS System Organization in the SL-GMS Advanced Tutorial Version 6.2a- 26 May 2006 SL-GMS Function Reference 42 Cursor Cursor SUMMARY set, or query, the mouse cursor for SL-GMS windows NAME gmsWsCursor( ), gmsWsAddCursor( ), gmsQWsCursor( ), gmsQWsCursorNames( ), gmsQWsCursorInfo( ) SYNTAX int gmsWsCursor (workst, cursor_name) id workst; /* Workstation object*/ char *cursor_name int gmsWsAddCursor (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; Version 6.2a- 26 May 2006 SL-GMS Function Reference 43 Cursor id gmsQWsCursorInfo (workst, cursor_name, cursor_type, cursor_data) id workst; char *cursor_name;/* in */ int cursor_type;/* out */ t_addr cursor_data;/* out */ DESCRIPTION The cursor functions allow applications to change the mouse cursor in SL-GMS windows. Since mouse cursors are inherently platform dependent, the approach taken by SL-GMS is to register and access cursors by name. This allows applications to perform platform-dependent initialization followed by platform-independent usage. Without explicit initialization, SL-GMS supports 13 predefined cursors under 32-bit Windows and 77 font cursors under X Windows. These are pre-registered using names formed by removing the system-dependent prefix (e.g. "IDC_" or "XC_") from the system #defines (and in the 32-bit Windows 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 from XC_top_left_arrow. The gmsWsCursor( ) function sets the mouse cursor for the specified Workstation/Window. If the cursor matching the cursor_name argument exists in the current SL-GMS list of cursors, the function returns non-zero and that cursor immediately becomes active. If workst is the exemplar Workstation/Window object (e.g. the object returned by gmsQDefaultWsClass( )) then that cursor will be used as the default cursor for subsequently created Workstation/Windows. The gmsWsAddCursor( ) function is used to add a cursor to the SL-GMS list of cursors. If a cursor matching cursor_name already exists, it is replaced. The cursor_type and cursor_data arguments are platform dependent. Values and data structures for 32-bit Windows applications are supplied in the C include file "gmswin.h". Version 6.2a- 26 May 2006 SL-GMS Function Reference 44 Cursor X Windows Values and data structures for X Windows applications are supplied in the C include file "gmsX.h". The cursor_type argument must be one of the 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 a pointer to an integer value from "X11/cursorfont.h" such as XC_top_left_arrow. NOTE: The only reason to "add" a font cursor would be to rename it (for instance to have a portable name between X and Windows) since SL-GMS already supports all available font cursors with names formed by removing the "XC_" prefix from the "X11/cursorfont.h" definition. If cursor_type is G_WS_PIXMAP_CURSOR then cursor_data must be a pointer to a gmsXcursorStruct, defined in "gmsX.h": typedef struct { Pixmap source, mask; XColor *foreground, *background; unsigned int hotspot_x, hotspot_y; } gmsXcursorStruct; Version 6.2a- 26 May 2006 SL-GMS Function Reference 45 Cursor 32-bit Windows Values and data structures for 32-bit Windows applications are supplied in the C include file "gmsWin.h". The cursor_type argument must be one 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 be a 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 a pointer 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 name string for the cursor that is currently active for the specified Workstation/Window object. If the workst argument is the exemplar Workstation/Window object, the name of the current default cursor for newly-created Workstation/Windows is returned. The gmsQWsCursorNames( ) query function returns a NULL-terminated array of pointers to strings containing the names of currently registered cursors. The application must not modify the strings but should free the array of pointers. The gmsQWsCusorInfo( ) query function returns information about a named cursor. This function is provided primarily for debugging. It returns the device-dependent cursor_type and cursor_data information as described in the section on gmsWsAddCursor( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 46 Cursor EXAMPLE Configure an application for six mouse cursors with the following code: #include "gms.h" #include "gms_sms.h" #include #ifdef _WIN32 #include "gmsWin.h" static static static static static static intsimpleCursorType intsimple_cursor1 = intsimple_cursor2 = intsimple_cursor3 = intsimple_cursor4 = intsimple_cursor5 = = G_WS_PREDEF_CURSOR; IDC_CROSS; IDC_SIZEALL; IDC_IBEAM; IDC_NO; IDC_WAIT; #else /* ifdef _WIN32 */ #include "gmsX.h" #include static static static static static static intsimpleCursorType intsimple_cursor1 = intsimple_cursor2 = intsimple_cursor3 = intsimple_cursor4 = intsimple_cursor5 = = G_WS_FONT_CURSOR; XC_crosshair; XC_fleur; XC_xterm; XC_iron_cross; XC_watch; #endif/* ifdef/else _WIN32 */ static void initialize_cursors () { #ifndef _WIN32 int x_uparrow = XC_sb_up_arrow; Version 6.2a- 26 May 2006 SL-GMS Function Reference 47 Cursor #endif /* set default cursor to be an "uparrow"; on win32, this is a predefined name using IDC_UPARROW, but needs to be renamed for X, where it's known as XC_sb_up_arrow */ #ifndef _WIN32 gmsWsAddCursor(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); gmsWsAddCursor(gmsQDefaultWsClass(),"simple_cursor3", simpleCursorType, &simple_cursor3); gmsWsAddCursor(gmsQDefaultWsClass(),"simple_cursor4", simpleCursorType, &simple_cursor4); gmsWsAddCursor(gmsQDefaultWsClass(),"simple_cursor5", simpleCursorType, &simple_cursor5); } Set the mouse cursor when needed. The code below changes the mouse cursor each time the mouse is clicked. static int loc_press (state, event) idCLASS state; id event; Version 6.2a- 26 May 2006 SL-GMS Function Reference 48 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 '2': new_cursor[len - 1] = '3'; break; case '3': new_cursor[len - 1] = '4'; break; case '4': new_cursor[len - 1] = '5'; break; case '5': default: new_cursor[len - 1] = '1'; } gmsWsCursor(gmsQStWorkst(state), new_cursor); Version 6.2a- 26 May 2006 SL-GMS Function Reference 49 Cursor return 1; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 50 Datasource — ".dat" files Datasource — ".dat" files SUMMARY free memory associated with processing of ".dat" files NAME gmsDatDsFreeAll( ) SYNTAX int gmsDatDsFreeAll ( ) DESCRIPTION The gmsDatDsFreeAll( ) function frees the memory for all ".dat" files that 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 set up in ".dat" files. It clears the simulation information associated with the variable but does not free the SL-GMS internal Variable Definitions. The Variable Definitions can be freed only by using the gmsFreeAllVarDefs( ) function. SEE ALSO gmsFreeAllVarDefs( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 51 Datasource — class Datasource — class SUMMARY create and install Datasource class NAME gmsDsClass( ), gmsDsClassInstall( ), gmsDsClassFindByName( ), gmsClassAddMethod( ) SYNTAX id gmsDsClass (classname, instsize) char *classname;/* name of class */ int instsize; /* size of class object */ int gmsDsClassInstall (dsclassdef) idCLASS dsclassdef;/* a Datasource class */ id gmsDsClassFindByName (classname) char *classname;/* name of a class */ int gmsClassAddMethod (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 */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 52 Datasource — class DESCRIPTION The gmsDsClass( ) function dynamically creates a Datasource class object, given the class name and the size of the object in bytes. It is intended that it be called once from the Datasource’s global initialization function, which by convention is named xxxClassInit( ) where "xxx" is the classname. If successful, the non-0 return value may be passed to all gmsDs*( ) functions which act on a single Datasource 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 global initialization function, which by convention is named xxxClassInit( ) where "xxx" is classname. It should be called after all gmsClassAdd*( ) functions have returned successfully. A non-0 return value indicates success. The gmsDsClassFindByName( ) function looks up a Datasource class object, given a class name. If successful, the non-0 return value may be passed to all gmsDs*( ) functions which act on a single Datasource class. The gmsClassAddMethod( ) function adds a method to a Datasource class’ set of methods. The function returns 1 for success, 0 for failure. Valid codes for fctntype are G_INTEGER and G_POINTER. argtypes is not used and should be passed with a 0. Version 6.2a- 26 May 2006 SL-GMS Function Reference 53 Datasource — Instance Datasource — Instance SUMMARY create, activate, deactivate a Datasource Instance; retrieve, add, delete Variable Definitions (VarDefs) for a Datasource Instance NAME gmsDsActivate( ), gmsDsAddVarDef( ), gmsDsFindVarDef( ), gmsDsInst( ), gmsDsVarDefFree( ), gmsDsUpdate( ) gmsDsDeactivate( ), gmsDsInstFree( ), SYNTAX int gmsDsActivate (dsinst) idCLASS dsinst; /* a Datasource Instance */ int gmsDsAddVarDef (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 */ int gmsDsDeactivate (dsinst) idCLASS dsinst; /* a Datasource Instance */ id gmsDsFindVarDef (self, varname) idCLASS self; /* a Datasource Instance */ char *varname; /* a variable name */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 54 Datasource — Instance id gmsDsInst (instname, classname) char *instname; /* a Datasource Instance */ char *classname;/* name of a Datasource class */ int gmsDsInstFree (dsinst) idCLASS dsinst; /* a Datasource Instance */ int gmsDsVarDefFree (dsinst, vardef) idCLASS dsinst; /* a Datasource Instance */ id vardef; /* a VarDef object */ int gmsDsUpdate (dsinst) idCLASS dsinst; /* a Datasource Instance */ DESCRIPTION The gmsDsActivate( ) function activates a single Datasource Instance. The Datasource’s superclass activate method allocates memory, if necessary, for each VarDef attached to the Instance, notifies SL-GMS that 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 called repetitively from the application after the gmsDsInst( ) function and before the Instance is activated. The reason for this calling sequence is for proper memory allocation; although the memory for the VarDef is allocated in gmsDsAddVarDef( ), the variable space (the space to which the address argument of gmsVarDefine( ) points) is allocated in the Instance’s superclass activate method. The varinfo argument is provided for application convenience: the input string is copied into space allocated for the VarDef’s Version 6.2a- 26 May 2006 SL-GMS Function Reference 55 Datasource — Instance char * varinfo; field and is ignored by SL-GMS. much as gmsVarDefine( ). Otherwise, this function behaves The gmsDsDeactivate( ) function deactivates a single Datasource Instance. Currently nothing is done at the superclass level except to use the gmsDsMsg( ) interface to invoke the Datasource-specific deactivate method. The gmsDsFindVarDef( ) function accepts a pointer to a Datasource Instance and a variable name. If successful, it returns a pointer to the associated VarDef; null is returned upon failure. The gmsDsInst( ) function dynamically creates a named Datasource Instance, given an Instance name and the name of an initialized Datasource class. The Instance name must be currently unused within the class. The class must have been initialized by the Datasource’s global initialization function, by convention named xxxClassInit( ) where "xxx" is the "classname". If successful, the non-0 return value may be passed to all gmsDs*( ) functions which act on a single Datasource Instance. The gmsDsInstFree( ) function frees the memory associated with a single Datasource Instance. It is the caller’s responsibility to null the dsinst pointer if there is a chance that dsinst will be accessed again in its current state. The gmsDsVarDefFree( ) function frees a Datasource Instance’s individual VarDef object. The gmsDsUpdate( ) function updates an individual Datasource Instance. SEE ALSO gmsDsMsg( ), gmsVarDefine( ), gmsDsListDeactivate( ), gmsDsClass( ), gmsDsObjNew( ), gmsDsListUpdate( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 56 Datasource — Lists Datasource — Lists SUMMARY manipulate Lists of Datasource Instances NAME gmsDsListActivate( ), gmsDsListDeactivate( ), gmsDsListFree( ), gmsDsListGet( ), gmsDsListSave( ), gmsDsListUpdate( ), gmsDsObjFree( ), gmsDsObjNew( ) SYNTAX int gmsDsListActivate (dslist) idLinkRef dslist;/* a list (idLinkRef) of Datasource Instances */ int gmsDsListDeactivate (dslist) idLinkRef dslist;/* a list of Datasource Insts */ int gmsDsListFree (dslist) idLinkRef dslist;/* a list of Datasource Insts */ idLinkRef gmsDsListGet (filename) char *filename; /* name of file */ int gmsDsListSave (dslist, filename) idLinkRef dslist;/* a list of Datasource Insts */ char *filename; /* name of file */ int gmsDsListUpdate (dslist) idLinkRef dslist;/* a list of Datasource Insts */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 57 Datasource — Lists int gmsDsObjFree (datasource) id datasource; id gmsDsObjNew (classname) char *classname; DESCRIPTION The gmsDsListActivate( ) function activates a linked List of Datasource Instances. It is the equivalent of calling gmsDsActivate( ) for each Instance in the List. The gmsDsListDeactivate( ) function deactivates a linked List of Datasource Instances. It is the equivalent of calling gmsDsDeactivate( ) for each Instance in the List. The gmsDsListFree( ) function frees a List of Datasource Instances. The gmsDsListGet( ) function retrieves a List of Datasources stored in filename. The gmsDsListSave( ) function saves a List of Datasources in filename. The gmsDsListUpdate( ) function updates a List of Datasources. The gmsDsObjFree( ) function frees a Datasource object. The gmsDsObjNew( ) function creates a new Datasource object. SEE ALSO gmsDsActivate( ), gmsDsDeactivate( ), gmsDsUpdate( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 58 Datasource — messages Datasource — messages SUMMARY send message to Datasource Instance NAME gmsDsMsg( ), gmsDsPMsg( ), gmsDsMsg1( ), gmsDsPMsg1( ), gmsDsMsg2( ), gmsDsPMsg2( ), gmsDsMsg3( ), gmsDsPMsg3( ), gmsDsMsg4( ), gmsDsPMsg4( ) SYNTAX int gmsDsMsg (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 */ int gmsDsMsg1 (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 */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 59 Datasource — messages int gmsDsMsg2 (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, idCLASS self; /* a char *msgstr; /* a long arg1; /* a long arg2; /* a arg1, arg2) Datasource Instance */ message string */ method argument */ method argument */ int gmsDsMsg3 (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, idCLASS self; /* a char *msgstr; /* a long arg1; /* a long arg2; /* a long arg3; /* a arg1, arg2, arg3) Datasource Instance */ message string */ method argument */ method argument */ method argument */ int gmsDsMsg4 (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 */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 60 Datasource — messages void * gmsDsPMsg4 (self, msgstr, idCLASS self; /* a char *msgstr; /* a long arg1; /* a long arg2; /* a long arg3; /* a long arg4; /* a arg1, arg2, arg3, arg4) Datasource Instance */ message string */ method argument */ method argument */ method argument */ method argument */ DESCRIPTION These functions send messages to a specific Datasource Instance. The msgstr parameter must match the method name registered for the Instance’s class with the gmsClassAddMethod( ) function. The value returned by the functions gmsDsMsg( ), gmsDsMsg1( ), gmsDsMsg2( ), gmsDsMsg3( ), and gmsDsMsg4( ) is that of the invoked method. 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 functions must be declared or cast to long. The DataSource Instance receiving the message will be passed longs. SEE ALSO gmsClassAddMethod( ) in the section Datasource — class on page 52 Version 6.2a- 26 May 2006 SL-GMS Function Reference 61 Directories and paths Directories and paths SUMMARY set the current directory for SL-GMS; add or free library search paths NAME gmsChdir( ), gmsAddLibPath( ), gmsFALibPaths( ) SYNTAX int gmsChdir(dirname) char *dirname; int gmsAddLibPath (pathname) char *pathname; int gmsFALibPaths( ) DESCRIPTION These 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 default SL-GMS search path (shown in the table on the following page). The gmsFALibPath( ) function limits the search to the current directory by permanently removing all library directories from the search path. Version 6.2a- 26 May 2006 SL-GMS Function Reference 62 Directories and paths SL-GMS Directory Search Path Order 1. The current directory 2. The default SubModel subdirectories of the current directory UNIX Systems ./GISMOS, ./GRAPHS, ./SUBMODS VAX/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, ../SUBMODS VAX/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 directory UNIX Systems $GMS_HOME/lib VAX/VMS Systems gms$home:[lib] NT Systems %GMS_HOME%\lib Version 6.2a- 26 May 2006 SL-GMS Function Reference 63 Directories and paths SL-GMS Directory Search Path Order continued) 6. The default SubModel directories in the gismos, graphs, and models subdirectories of the demo directory UNIX Systems demo/gismos/GISMOS, demo/graphs/GRAPHS, demo/models/SUBMODS VAX/VMS Systems [demo.gismos.gismos], [demo.graphs.graphs], [demo.models.submods] NT Systems demo\gismos\GISMOS, demo\graphs\GRAPHS, demo\models\SUBMODS 7. The SL-GMS home directory UNIX Systems $GMS_HOME VAX/VMS Systems gms$home NT Systems %GMS_HOME% EXAMPLE UNIX Systems gmsAddLibPath("/usr/mydir"); VAX/VMS Systems gmsAddLibPath("[usr.mydir]"); NT Systems 1 gmsAddLibPath("\\usr\\mydir"); or gmsAddLibPath("/usr/mydir"); 1. Two backslashes (\\) are required by the compiler on NT Systems to "escape" the usual interpretation of the single backslash. Version 6.2a- 26 May 2006 SL-GMS Function Reference 64 Display, erase, highlight Display, erase, highlight SUMMARY display, erase, or highlight an object or List of objects NAME gmsDisplay( ), gmsLDisplay( ), gmsHilite( ), gmsLHilite( ) gmsErase( ), gmsLErase( ), SYNTAX int gmsDisplay (obj) id obj; int gmsLDisplay (objlist, nclass, class1, class2, ...) idLinkRef objlist; int nclass; struct ClassDef *class1, *class2, ... ; int gmsErase (obj) id obj; int gmsLErase (objlist, nclass, class1, class2, ...) idLinkRef objlist; int nclass; struct ClassDef *class1, *class2, ... ; int gmsHilite (obj, flash) id obj; int flash; Version 6.2a- 26 May 2006 SL-GMS Function Reference 65 Display, erase, highlight int gmsLHilite (objlist, flash) idLinkRef objlist; int flash; DESCRIPTION This set of functions is used to display, erase, or highlight individual objects or Lists of objects. The system must be in Immediate Update Mode (gmsImmu( )) for these functions to work. If the system is in Deferred Update Mode, nothing will happen. The gmsDisplay( ) and gmsLDisplay( ) functions set a flag in objects marking them for redraw. The gmsErase( ) and gmsLErase( ) functions mark objects to be erased. The gmsLDisplay( ) and gmsLErase( ) functions are used with class-definition arguments. When used with class-definition arguments, only the objects on the List in one of the class arguments are displayed or erased. Using this, a List of objects is passed to one of these functions and only a certain class of objects is displayed or erased while other objects are unaffected. The argument nclass must be set to the number of class definition arguments. The include files (".h") in the lib directory should be examined for the names of these classes and more information regarding class-definition objects. The argument nil is used in place of a List of class definitions when no filtering of objects by class is desired, in which case nclass is set to 0. The gmsHilite( ) and gmsLHilite( ) functions take an argument which indicates how to highlight the object. When flash is equal to 1, the object(s) is made visible and then invisible (through the use of gmsSVis( )). When flash is equal to 0, the object(s) is erased then displayed. DIAGNOSTICS Setting the visibility is a solution to highlighting for those devices that do not support it in hardware. Presently, the gmsHilite( ) function does not support the use of hardware blink. Version 6.2a- 26 May 2006 SL-GMS Function Reference 66 Display, erase, highlight 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 a List of objects: gmsLDisplay(objlist, 2, Edge, CompEdge); SEE ALSO gmsImmu( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 67 Dump Dump SUMMARY dump an SL-GMS object for debugging purposes NAME gmsDump( ), gmsDumpViews( ) SYNTAX int gmsDump (obj) id obj; int gmsDumpViews( ) DESCRIPTION The gmsDump( ) function is used to dump the contents of any object created by SL-GMS. If the argument given is nil, this function dumps the contents of the current Model. The gmsDump( ) function is primarily useful to those with an intimate knowledge of the internals of the SL-GMS system, although the format is simple enough to be understood in most cases. The gmsDumpViews( ) function is useful in debugging applications. It prints out all Views and their Models in a readable format (not the usual dump format). SEE ALSO The chapter entitled Variables Dumped for SL-GMS Object Classes in the SL-GMS Quick Reference SL-GML COMMAND [name] dump Version 6.2a- 26 May 2006 SL-GMS Function Reference 68 Dynamics — double-buffering Dynamics — double-buffering SUMMARY enable or disable software double-buffering for an object NAME gmsDoubleBufferFlag( ) SYNTAX int gmsDoubleBufferFlag (obj, flag) idPrim obj; int flag; /* 0 = disable, 1 = enable */ DESCRIPTION The gmsDoubleBufferFlag( ) function enables or disables software double-buffering on an object. The object must be an SL-GMS Graphical Primitive (Model, Group, Line, Circle, and the like). 2 The function does not allow a View or a Workstation/Window to be marked for double-buffering. SEE ALSO gmsNoErase( ) Workstation/Windows can be marked for double-buffering with the G_WS_DBUFF_ERASE or G_WS_DBUFF_CLEAR flags. Further information about these flags is provided in the Installation Notes. The chapter entitled Dynamics in the SL-GMS Reference SL-GML COMMAND name 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 69 Dynamics — DynProps/RenamedVariables Dynamics — DynProps/RenamedVariables SUMMARY create DynProps and Renamed Variables at run-time; query an object’s DynProp and Renamed Variables NAME gmsDynStr( ), gmsRenamedStr( ), gmsRenamedStrNoRelink( ), gmsRenVarStrConstReplSO( ), gmsQDynStr( ), gmsQDynStrList( ), gmsQRenamedStr( ) SYNTAX int gmsDynStr (obj, string) id obj; char *string; int gmsRenamedStr (obj, string) id obj; char *string; int gmsRenamedStrNoRelink (obj, string) id obj; char *string; int gmsRenVarStrConstReplSO (modinst, var_name, new_string) id modinst; id var_name; id new_string; char * gmsQDynStr (object) id object; Version 6.2a- 26 May 2006 SL-GMS Function Reference 70 Dynamics — DynProps/RenamedVariables char * gmsQDynStrList (object) id object; char * gmsQRenamedStr (inst) id inst; DESCRIPTION The gmsDynStr( ) function enables an application to create dynamic descriptions. Although most applications use Models where the dynamic descriptions have already been created by using SL-DRAW2 or SL-DRAW, objects can have new dynamic descriptions associated with them by using this function. The string used as an argument must include a set of parentheses for each line of a dynamic description (as displayed by the Edit Dyn option of the Dyn Pull-Down Menu in SL-DRAW2 or SL-DRAW). The limit on the number of characters for the string is 8192. Adding a new description removes any previous description. The gmsVarDefine( ) function must be called to associate the variables in the new description with data addresses. This description does not become a permanent part of the Model unless the Model is saved (e.g., with gmsMSave( )). The gmsRenamedStr( ) function permits an application to rename variables associated with a Model Instance. This function works like the Rename Vars option of the Dyn Pull-Down Menu in SL-DRAW2 or SL-DRAW. The first argument is the pointer to the Model Instance. The string contains pairs of variable names and the new names separated by a double colon. The limit on the number of characters for the string is 8192. For example, to rename the variable x_value to magnitude, the string x_value :: magnitude is used. If there are many variables to be renamed, the string will contain many pairs of values, each pair separated by a space. After calling gmsRenamedStr( ), the Model must be re-initialized with gmsDynInit( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 71 Dynamics — DynProps/RenamedVariables NOTE: All Variable Definitions must be unlinked before gmsDynStr( ) or gmsRenamedStr( ) is called. After the gmsDynInit( ) function has been called, gmsUnlinkVarDefs( ), gmsRemVarDefLinks( ), or gmsDynEnd( ) must be called before calling either gmsDynStr( ) or gmsRenamedStr( ) or a crash may result. Following these calls, gmsDynInit( ) must be called 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 Variable List for a Model Instance (obj) from string. Unlike gmsRenamedStr( ), gmsRenamedStrNoLink( ) does not relink Instances. The gmsRenamedStrNoLink( ) function is used when in SubModel Replicate Mode, reached by calling gmsSubModReplicateMode( ), or after renaming the variables of a Model Instance (obj). The gmsRenVarStrConstReplSO( ) function replaces the string constant referenced by a Renamed Variable in a Model Instance with a different string constant. The var_name argument specifies the name of the Renamed Variable defined in the given Model Instance. The new_string argument, a String object, specifies the new value of the string constant. If new_string is NULL, the new value of the variable specified by var_name will be an empty string. If the gmsDynInit( ) function has been previously called, all Variable Definitions must be unlinked from the Model containing the given Model Instance before gmsRenVarStrConstReplSO( ) is called. The gmsUnlinkVarDefs( ) function must be called before calling gmsRenVarStrConstReplSO( ) or a crash may result. Following the call, gmsDynInit( ) must be called on the changed Model to re-initialize its dynamic variables. Therefore, it is best to call gmsRenVarStrConstReplSO( ) before gmsDynInit( ). gmsRenVarStrConstReplSO( ) returns 1 for success, 0 for failure. Version 6.2a- 26 May 2006 SL-GMS Function Reference 72 Dynamics — DynProps/RenamedVariables EXAMPLE Change the label of an m_quit GISMO. In the following Model "top.g": top_mod: model exit_button: inst m_quit 0 0 . move 40 15 . scale 40 15 2 2 renamedvars \ button_label :: "QUIT" \ edge_width :: 3 \ text_align_x :: 2 \ text_height :: 1 endm the variable button_label has the constant string "QUIT" as its value. If "QUIT" is to be replaced with "EXIT" during runtime, gmsRenVarStrConstReplSO( ) can be called, as illustrated in the following 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(); Version 6.2a- 26 May 2006 SL-GMS Function Reference 73 Dynamics — DynProps/RenamedVariables The gmsQDynStr( ) function returns an object’s dynamic description string. The gmsQDynStrList( ) function returns a dynamic description string with level codes. The gmsQRenamedStr( ) function returns the object’s Renamed Variable string. This function works only on Model Instance objects. The string contains pairs of variables and renamed variables separated by whitespace. For example, in the Renamed Variable string x::x1 y::y1 z::z1 x, y, and z are renamed x1, y1, and z1. EXAMPLE While working in SL-DRAW2, a Rectangle with the following dynamic description 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"); Version 6.2a- 26 May 2006 SL-GMS Function Reference 74 Dynamics — DynProps/RenamedVariables EXAMPLE A DynProp with several variables and ranges is shown as it would appear 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 is accomplished 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 %d failed.\n", i); Version 6.2a- 26 May 2006 SL-GMS Function Reference 75 Dynamics — DynProps/RenamedVariables EXAMPLE The following code fragment shows a loc_press method that renames a string associated with an Instance. static int loc_press(state, event) id state; id event; { char rnmstr[1000]; id obj; /* retrieve object clicked */ obj = gmsQEvObject(event); /* remove links between Variable Definitions and Variable References */ 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 without marking for update */ gmsDynInitNoMarks(obj); /* change b1 and mark for change */ b1++; gmsVarDefineChanged("b1", &b1, G_INTEGER, 1, 1); gmsDynUpdate(gmsQStModel(state)); gmsUpdate(gmsQStView(state)); Version 6.2a- 26 May 2006 SL-GMS Function Reference 76 Dynamics — DynProps/RenamedVariables return 1; } EXAMPLE Any unconditionally-renamed variables should be followed with a call to gmsRenamedStr( ). Next, if other variables are conditionally renamed, the renaming should be followed by a call to gmsRenamedStrNoRelink( ) 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 ALSO gmsVarDefine( ), gmsDynInit( ), gmsUnlinkVarDefs( ), gmsRemVarDefLinks( ), gmsDynEnd( ), gmsString( ) Internationalization — String object on page 208 The chapter entitled Dynamics in the SL-GMS Reference SL-GML COMMANDS name dynprop string name renamedvars string Version 6.2a- 26 May 2006 SL-GMS Function Reference 77 Dynamics — erasure Dynamics — erasure SUMMARY set flag options and Batch Erase Modes for object erasure NAME gmsBatchErase( ), gmsBatchEraseMode( ), gmsNoErase( ) SYNTAX int gmsBatchErase (object, flag) id object; int flag; /* "batch erase" flag = G_ON/G_OFF */ int gmsBatchEraseMode (flag) int flag; int gmsNoErase (object, flag) id object; int flag; /* "no-erase" flag = G_ON/G_OFF */ DESCRIPTION The gmsBatchErase( ) function sets an object’s batcherase flag. The batcherase flag has meaning only for objects with parts: Models and Groups. When the batcherase flag is set to G_ON, all dynamic erasures are done first, before redrawing the object. The batcherase flag is useful for objects which require, for example, a move action on multiple objects which may collide. The batcherase flag can be used in conjunction with the repair flag. The gmsRepairFlag( ) function sets an object’s repair flag. When the repair flag is set to G_ON, then if any object in the Group is redrawn, all objects in the Group are redrawn. Version 6.2a- 26 May 2006 SL-GMS Function Reference 78 Dynamics — erasure EXAMPLE Figure 1-1: illustrates a diamond object with attached dynamics that move 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 of the line is erased. A "hole" marking each previous position of the diamond 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 diamond objects each time, x_pos, the variable driving the movex dynamic action of the diamond, changes and then redraw them. The line and the diamond are made into a Group. The dynamics for the line and diamond Group are as follows: group Version 6.2a- 26 May 2006 SL-GMS Function Reference 79 Dynamics — erasure . repairflag 1 . batcherase 1 With the repair flag set to G_ON for the Group, whenever the diamond is redrawn the line is automatically redrawn. With the batcherase flag set to G_ON for the Group, both the line and the diamond are erased first and then redrawn as illustrated in Figure 1-3:. The diamond moves over the line without erasing it. Figure 1-3: .Diamond moving over line The gmsBatchEraseMode( ) function sets Batch Erase Mode G_ON or G_OFF globally for all SL-GMS objects. When turned to G_ON, the display and erase passes occur separately (split at View level). This is equivalent to having the batcherase flag set to G_ON for all Models. For displays that have many objects moving across each other, such as a radar screen, it is not practical to use batcherase. It is more efficient to make use of noerase in conjunction with double-buffering or clearing of Views. This scheme avoids the overhead of marked erasure and simply redraws everything. The gmsNoErase( ) function sets the noerase flag on an object. With the noerase flag set to G_ON, an object is never erased. SEE ALSO gmsDoubleBufferFlag( ) gmsRepairFlag( ) The chapter entitled Dynamics in the SL-GMS Reference SL-GML COMMANDS name batcherase name noerase Version 6.2a- 26 May 2006 SL-GMS Function Reference 80 Dynamics — initialize, update, restore, end Dynamics — initialize, update, restore, end SUMMARY initialize, update, or end dynamics; restore a Graphical Primitive to its original state NAME gmsDynInit( ), gmsDynInitNoMarks( ), gmsVarInitFctn( ), gmsDynUpdate( ), gmsDynRestore( ), gmsDynEnd( ) SYNTAX int gmsDynInit (model) id model; int gmsDynInitNoMarks (obj) id obj; int gmsVarInitFctn (fctn) id (*fctn)( ); int gmsDynUpdate (model) id model; int gmsDynRestore (obj) id obj; int gmsDynEnd( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 81 Dynamics — initialize, update, restore, end DESCRIPTION The gmsDynInit( ) function initializes the dynamic descriptions of parts within Models. When the model argument is nil, the dynamic attributes in all loaded Models are initialized. The gmsDynInit( ) function internally creates a Variable Reference object for each variable referenced in the Model and performs other housekeeping work necessary to set up dynamics. This function returns 0 for failure, such as "out of memory." It must be called explicitly by the application to re-associate dynamic descriptions after gmsDynEnd( ) or gmsRenamedStr( ) is called. NOTE: If gmsDynInit( ) is called repeatedly on a Model, without calling one of the functions gmsDynEnd( ), gmsRemVarDefLinks( ), or gmsUnlinkVarDefs( ) each time, memory leakage will result. The gmsDynInit( ) function looks for variable definitions in the global table. It also automatically looks for variable definitions in State Variable Tables, whenever the gmsDynInit( ) function is called implicitly during the State activation. The search begins at the State which is being activated; if a variable definition is not found in that State, each SuperState is then searched until the variable is found. If it is still not found after searching all SuperStates, the global table is searched. NOTE: The lookup of variables in State Variable Tables is automatic only if done by the State activation. If the gmsDynInit( ) function is done manually, it must be set by global identification g_dyninit_state to be the State in which to start the search. The gmsDynInitNoMarks( ) function initializes dynamics for a Primitive without marking anything for update. If the nil argument is given, this function initializes dynamics for all Models. The gmsVarInitFctn( ) function sets a single internal function pointer that is called during dynamics initialization (gmsDynInit( )). The user-defined callback is called whenever a Variable-Reference is encountered during initialization. The user-defined callback function must take two arguments: the variable’s name (char *) and the Version 6.2a- 26 May 2006 SL-GMS Function Reference 82 Dynamics — initialize, update, restore, end variable’s typecode (int). The user-defined callback should return the Variable Definition object (VarDef) created. During dynamics initialization, gmsVarInitFctn( ) is called once with a type code of 0 ("variable type unknown") and a second time with the type 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 is still unknown. The gmsVarInitFctn( ) function callbacks are typically used to access information or further variables from a database or to check for errors (i.e., how a variable is used in a DynProp compared with its type in the database). EXAMPLE gmsVarInitFctn(my_var_init_func); . . . id my_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 of parts within Models. When the model argument is nil, the dynamic attributes in all loaded Models are updated. Version 6.2a- 26 May 2006 SL-GMS Function Reference 83 Dynamics — initialize, update, restore, end NOTE: Before the dynamic descriptions can be updated, they must be associated with data addresses by using gmsVarDefine( ). The gmsDynUpdate( ) function initiates a dynamic update pass on a Model. This pass accesses the data and makes changes to objects according to the dynamic descriptions of those objects. This function does not result in the display of changed objects until gmsUpdate( ) is called, (unless SL-GMS is in Immediate Update Mode). The gmsDynUpdate( ) function must be called prior to calling gmsUpdate( ) in order to be certain all dynamic attributes are up-to-date with the variables. SL-SMS calls the gmsDynUpdate( ) and gmsUpdate( ) functions automatically. The gmsDynRestore( ) function restores a Primitive to its original state, 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 the objects with which they are associated. An application may also call gmsDynEnd( ) when a dynamic action makes a Model invisible, thus preventing SL-GMS from updating the dynamics associated with the Model’s parts. (If a Model is made invisible through a direct function call, such as gmsSetVis(model, 0); calling gmsDynEnd( ) is unnecessary.) The Variable Definitions can be re-associated by calling gmsDynInit( ) on the Model once again. SEE ALSO gmsVarChanged( ), gmsVarDefine( ), gmsRemVarDefLinks( ), gmsUnlinkVarDefs( ) gmsRenamedStr( ), The chapter entitled Dynamics in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 84 Dynamics — optimization Dynamics — optimization SUMMARY set or query internal SL-GMS optimization flags to implement optimized dynamics NAME gmsAutoUpdateMode( ), gmsQAutoUpdateMode( gmsFastDynPropMode( ), gmsQFastDynPropMode( gmsDynUpdateMode( ), gmsQDynUpdateMode( gmsAllVarsChanged( ), gmsUseShadowMode( gmsQUseShadowMode( ), gmsExtentMode( ), gmsQExtentMode( gmsNoFlags( ), gmsNoFlagsMode( ), gmsQNoFlagsMode( gmsDynUpdArrayFlag( ) ), ), ), ), ), ), SYNTAX int gmsAutoUpdateMode (mode) int mode; /* G_ON or G_OFF */ int gmsQAutoUpdateMode ( ) int gmsFastDynPropMode (mode) int mode; /* G_ON or G_OFF (default) */ int gmsQFastDynPropMode ( ) int gmsDynUpdateMode (mode) int mode; /* G_UPDATE_PASS or G_DYNUPDATE_PASS (default) */ int gmsQDynUpdateMode ( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 85 Dynamics — optimization int gmsAllVarsChanged ( ) int gmsUseShadowMode (mode) int mode; /* G_ON or G_OFF */ int gmsQUseShadowMode ( ) int gmsExtentMode (mode) int mode; /* G_ON or G_OFF */ int gmsQExtentMode( ) int gmsNoFlags(obj, flag) idPrim obj; /* Graphical Primitive object */ int flag; /* 0 = OFF, 1 = ON */ int gmsNoFlagsMode (mode) int mode; /* G_ON or G_OFF */ int gmsQNoFlagsMode( ) int gmsDynUpdArrayFlag (object, flag) id object; int flag; Version 6.2a- 26 May 2006 SL-GMS Function Reference 86 Dynamics — optimization DESCRIPTION These functions work independently to implement optimized dynamics. The gmsAutoUpdateMode( ) function causes gmsDynUpdate(nil) and gmsUpdate(nil) to be done after each Event is processed in gmsMainLoop( ). The gmsQAutoUpdateMode( ) function returns the current Auto Update Mode, either G_ON or G_OFF. The gmsFastDynPropMode( ) function controls the use of optimized dynamics, while the gmsDynUpdateMode( ) function affects the way in which the update and display processes occur. The Fast DynProp Mode set to G_ON with the gmsFastDynPropMode( ) function tells SL-GMS that all DynProps in the application are structured for optimization as described in the chapter entitled of the SL-GMS Reference, and DynProps that are conditional or use expressions should automatically be skipped without any diagnostic messages. Setting of the Fast DynProp Mode must occur before gmsDynInit( ) is called on a Model. Calling gmsDynInit( ) triggers the conversion from ordinary dynamics into optimized dynamics. If the application does not know the names of the variables to define, gmsDynInit( ) and gmsVarRefName( ) may be used to acquire the names of the variables. After defining the variables with gmsVarDefine( ), gmsDynInit( ) is called a second time to convert to optimized dynamics. Calling the gmsFastDynPropMode( ) function with G_ON presumes that all variables are resident in memory each time that gmsUpdate( ) or gmsDynUpdate( ) is called. In applications where there are so many variables that not all variables are mapped into memory at all times, this function should not be called. The gmsQFastDynPropMode( ) function returns the current Fast DynProp Mode, either G_ON or G_OFF. The DynUpdate Mode set to G_UPDATE_PASS with the gmsDynUpdateMode( ) function causes the functionality of gmsDynUpdate( ) to be performed when the gmsUpdate( ) function is Version 6.2a- 26 May 2006 SL-GMS Function Reference 87 Dynamics — optimization called. Setting of the DynUpdate Mode must occur before the gmsDynUpdate( ) or gmsUpdate( ) functions are called. The gmsQDynUpdateMode( ) function returns the current DynUpdate Mode, either G_UPDATE_PASS or G_DYNUPDATE_PASS. Calling the gmsAllVarsChanged( ) function tells SL-GMS that all variables have changed between every update. The normal procedure is to call gmsVarChanged( ) to mark each changed variable. When gmsAllVarsChanged( ) is called, gmsVarChanged( ) is never called on any variable. The gmsDynUpdate( ) function must still be called to update the dynamics unless the gmsAllVarsChanged( ) function is also called. The gmsUseShadowMode( ) function called with G_OFF disables the use of a Shadow to erase objects when attributes are changed. The use of this function is appropriate only if the application never needs erasure, uses double-buffering, or clears and redraws screens with each update. The gmsQUseShadowMode( ) function returns the current Shadow Mode, either G_ON or G_OFF. The gmsExtentMode( ) function disables extent calculation on objects that are not detectable. This disablement makes the update pass quicker, but disables clipping — non-detectable objects must not pass outside of the WC-window. The gmsQExtentMode( ) function returns the current Extent Mode, either G_ON or G_OFF. The gmsNoFlags( ) function minimizes unnecessary flag propagation when attribute changes occur. Calling this function is only useful when it is known that an object is going to redraw on every update pass. The gmsNoFlagsMode( ) function is intended for use when gmsAllVarsChanged( ) is used and graphics are redrawn with either gmsRedraw( ) 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 which reference array values. Version 6.2a- 26 May 2006 SL-GMS Function Reference 88 Dynamics — optimization SEE ALSO The chapter entitled in the SL-GMS Reference SL-GML COMMAND name dynarray int Version 6.2a- 26 May 2006 SL-GMS Function Reference 89 Dynamics — query and set Variable Definition attributes 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 a Variable Definition object. NAME gmsVarDefAddress( ), gmsQVarDefAddress( ), gmsVarDefCount( ), gmsQVarDefCount( ), gmsVarDefSize( ), gmsQVarDefSize( ),gmsVarDefType( ), gmsQVarDefType( ), gmsQVarDefName( ) SYNTAX int gmsVarDefAddress (vardef, address) id vardef; /* id of Variable Definition object*/ void *address; /* address of variable */ void * gmsQVarDefAddress (vardef) id vardef; /* id of Variable Definition object*/ int gmsVarDefCount (vardef, count) id vardef; /* id of Variable Definition object*/ int count; /* number of data elements*/ int gmsQVarDefCount(vardef) id vardef; /* id of Variable Definition object*/ Version 6.2a- 26 May 2006 SL-GMS Function Reference 90 Dynamics — query and set Variable Definition attributes int gmsVarDefSize (vardef, size) id vardef; /* id of Variable Definition object*/ int size; /* size of each data element*/ int gmsQVarDefSize(vardef) id vardef; /* id of Variable Definition object*/ int gmsVarDefType(vardef, type) id vardef; /* id of Variable Definition object */ int type; /* type of variable */ int gmsQVarDefType(vardef) id vardef; /* id of Variable Definition object */ char * gmsQVarDefName(vardef) id vardef; /* id of Variable Definition object */ DESCRIPTION A Variable Definition object is created using gmsVarDefine( ) or gmsVarDefineNoTable( ). 3 A Variable Definition object’s address, size, and count attributes may be accessed individually. The gmsVarDefAddress( )4 function sets the address of an existing Variable 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 91 Dynamics — query and set Variable Definition attributes elements, and gmsVarDefSize( ) sets the size of each data element of an existing Variable Definition object. The gmsVarDefType( ) function sets the type attribute of an existing Variable Definition object. Currently, gmsVarDefType( ) must be called before the first gmsDynUpdate( ) pass occurs on objects referencing this Variable Definition, otherwise errors may occur in the evaluation of dynamics descriptions. The gmsQVarDefType( ) function returns the value of the type attribute of an existing Variable Definition object. The gmsVarDefType( ) function is typically used to set the type attribute of a Variable Definition in a Variable Definition Table. Further information about Variable Definition Tables and usage examples of gmsVarDefType( ) are provided in the section SubModel Preparation on page 101. Because both gmsVarDefine( ) and gmsStVarDefine( ) set the type attribute of a Variable Definition, it is not necessary to use gmsVarDefType( ) in conjunction with these functions. The gmsQVarDefAddress( ), gmsQVarDefCount( ), and gmsQVarDefSize( ) functions are used to query individual attributes on an existing Variable Definition object. They are passed the id of the Variable Definition object. The gmsQVarDefAddress( ) function returns the address. The gmsQVarDefCount( ) function returns the number of data elements in the Variable Definition object. The gmsQVarDefSize( ) function returns the size of each data element. The gmsQVarDefType( ) function returns the value of the type attribute of an existing Variable Definition object. NOTE: A Variable Definition object’s name attribute cannot be changed in this way. To specify a new Variable Definition object name, a new Variable Definition object must first be created using gmsVarDefine( ) or gmsVarDefineNoTable( ). The gmsDynInit( ) function must then be called to re-establish the Version 6.2a- 26 May 2006 SL-GMS Function Reference 92 Dynamics — query and set Variable Definition attributes links between the Variable Definition object and the Variable Reference objects which reference it. The gmsQVarDefName( ) function returns a string containing the name of a Variable Definition object. This string should not be freed by the caller. The gmsQVarDefName( ) function is typically used to identify a Variable Definition. For example, an application may have initially created a Variable Definition using gmsVarDefineNoTable( ) and retained a pointer 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 with vardef. If the application did not save the name, it could be: char *name; name = gmsQVarDefName(vardef); SEE ALSO gmsVarDefine( ), gmsDynInit( ) gmsVarDefineNoTable( ), gmsStVarDefine( ), State — variables on page 382 Version 6.2a- 26 May 2006 SL-GMS Function Reference 93 Dynamics — query Variable References Dynamics — query Variable References SUMMARY query number, name, or address of variables used in Models NAME gmsQNumVarRefs( ), gmsQVarRefName( ), gmsQVarRefAddr( ) SYNTAX int gmsQNumVarRefs (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) */ DESCRIPTION These functions query an object for its Variable References. By providing a way for the application to query the List of variables referenced in each Model, the application can obtain a subset of the complete database for use on each of several display screens. The application also responds to loading new Models by making the connections between the Models’ variables, using gmsVarDefine( ) and gmsDynInit( ) if these connections have not been made previously. Both gmsQNumVarRefs( ) and gmsQVarRefName( ) can be called on any Graphical Primitive, including Models or Graph objects. An application can discover all variable names used in an object or Model Version 6.2a- 26 May 2006 SL-GMS Function Reference 94 Dynamics — query Variable References through the use of these functions, enabling each variable to be defined without the application knowing in advance which variables are present. The gmsQNumVarRefs( ) function returns the number of Variable References in the object given as the argument. The gmsQVarRefName( ) function is then called to return the variable name of each Variable Reference. Variable References are numbered beginning with 1 (rather than 0 as in the way arrays start in C language 5 applications). The string returned by this function should not be altered; it is intended for use with gmsVarDefine( ), gmsVarChanged( ), and information retrieval in the application’s own database. The gmsQVarRefAddr( ) function can be called on any Graphical Primitive, including Models or Graph objects. An application can retrieve the variable addresses that were defined for an object or Model through the use of this function. The gmsVarDefine( ) function must be used to define the variable’s name, address, and type before the gmsQVarRefAddr( ) function can be called. SEE ALSO gmsDynInit( ), gmsVarDefine( ), gmsVarChanged( ) The chapter entitled Dynamics in the SL-GMS Reference 5. This function has a FORTRAN counterpart, and FORTRAN does not permit an array index of 0. Version 6.2a- 26 May 2006 SL-GMS Function Reference 95 Dynamics — Variable Definition Table attached to Models Dynamics — Variable Definition Table attached to Models SUMMARY initialize dynamics and create a Variable Defintion Table, query Variable Definition Table associated with an object, query Variable Definition by index and name in Variable Definition Table, query Variable Definition Table count, flag data in Variable Definition Table as "changed" NAME gmsModDynInitVarDefTable( ), gmsQVarDefTable( ), gmsQVDTCount( ), gmsQVDTVarDefAtIndex( ), gmsQVDTVarDefByName( ), gmsVDTIndicesChanged( ) SYNTAX int gmsModDynInitVarDefTable (model, preserve_sub_vdt) id model; int preserve_sub_vdt;/* G_ON or G_OFF */ id gmsQVarDefTable (object) id object; int gmsQVDTCount (vdtable) id vdtable; id gmsQVDTVarDefAtIndex (vdtable, index) id vdtable; unsigned int index; id gmsQVDTVarDefByName (vdtable, name, index) id vdtable; char *name; int *index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 96 Dynamics — Variable Definition Table attached to Models int gmsVDTIndicesChanged (vdtable, indices, indices_count) id vdtable; int indices[]; int indices_count; DESCRIPTION The gmsModDynInitVarDefTable( ) function initializes the dynamic descriptions of all parts in the given Model. It also creates and stores a Variable Definition Table in the Model. If the Model already contains a Variable Definition Table, that table will be destroyed. The Variable Definitions in the Variable Definition Table are referenced only by Variable References contained in the Model. Unlike Variable Definitions in global or State tables, Variable Definitions in a Variable Definition Table contained in a Model cannot be used by any other Model. If the preserve_sub_vdt parameter is set to G_OFF, Variable Definition Tables contained in SubModels of the given Model will be destroyed by gmsModDynInitVarDefTable( ). If preserve_sub_vdt is set to G_ON, Variable Definition Tables contained in SubModels of the given Model will not be affected by gmsModDynInitVarDefTable( ). The gmsModDynInitVarDefTable( ) function can be used to initialize dynamics descriptions on SubModels prior to their replication. If this is done, there is no need to perform the initialization on the replicates. When a SubModel is replicated, its Variable Definition Table is also replicated. Further information about SubModel replication is provided in the section 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 97 Dynamics — Variable Definition Table attached to Models 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 on the SubModel. The blocking effect is local; SubModels which do not contain a Variable Definition Table are processed normally by gmsDynInit( ) calls on parents of the SubModel. Variable Definition Tables are generally used in the following types of applications: • 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 a non-replicated SubModel if that SubModel contains dynamics descriptions. The gmsDynInit( ) function does not work correctly in this situation. Only limited forms of dynamics descriptions work correctly on a non-replicated SubModel, even when Variable Definition Tables are used. Further information about these limitations is provided in the SL-GMS® Reference. Applications having a strong correlation between data-driving structures and Model Instances may use Variable Definition Tables as an alternative to State Variable Definitions (created through gmsStVarDefine( )). The Variable Definition names in a Variable Definition Table are local in scope to a single top-level Model or Model Instance. If an application uses a separate structure to contain the data driving the dynamics in each Model Instance in a top-level Model, Variable Definition Tables provide a convenient mechanism for binding the data in those structures to the Model Instances. Renamed Variables are not needed Version 6.2a- 26 May 2006 SL-GMS Function Reference 98 Dynamics — Variable Definition Table attached to Models in the Model Instances because the names in each Variable Definition Table are local in scope to each Model Instance. A Variable Definition Table can also be used on a top-level Model without interfering with any Variable Definition Tables on Model Instances in that Model. Variable Definition Tables should not be used on Model Instances contained in SubModels. The gmsQVarDefTable( ) function returns a pointer to the Variable Definition Table associated with the given Model or Model Instance object. When gmsQVarDefTable( ) is passed a pointer to a Model, the function returns a pointer to the Variable Definition Table contained in the Model. When gmsQVarDefTable( ) is passed a pointer to a Model Instance which references a replicated SubModel, the function returns a pointer to the Variable Definition Table contained in the SubModel replicate. A SubModel's Variable Definition Table is replicated when the SubModel is replicated. When gmsQVarDefTable( ) is passed a pointer to a Model Instance which references a non-replicated SubModel, the function returns a pointer to a Variable Definition Table contained in the Model Instance. A Model Instance which references a non-replicated SubModel always contains a replicate of the Variable Definition Table contained in the SubModel. This is done to enable gmsQVarDefTable( ) to return a unique Variable Definition Table for each Model Instance. The gmsQVDTCount( ) function returns the number of Variable Definition objects stored in the given Variable Definition Table. The gmsQVDTVarDefAtIndex( ) function returns a pointer to the Variable Definition object found at the given index in the given Variable Definition Table. The gmsQVDTVarDefByName( ) function returns a pointer to the Variable Definition object with the given name found in the given Variable Definition Table. If a non-NULL index pointer is passed as a parameter, gmsQVDTVarDefByName( ) also sets index to the location of the found Variable Definition object within the Variable Definition Table. If a Variable Definition with the given name is not found in the Version 6.2a- 26 May 2006 SL-GMS Function Reference 99 Dynamics — Variable Definition Table attached to Models Variable Definition Table or a NULL index pointer is passed, the value of index is not modified. The gmsVDTIndicesChanged( ) function informs SL-GMS that one or more application variable values have changed. The function is passed a pointer to a Variable Definition Table (vdtable), an array of indices into that 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 at that index in the Variable Definition Table. This Variable Definition is then flagged "changed," which later causes dynamics expressions referencing that Variable Definition to be evaluated. The gmsVDTIndicesChanged( ) function is similar to gmsVarChanged( ), except gmsVDTIndicesChanged( ) is restricted to a Variable Definition Table located on a single Model or Model Instance. EXAMPLE This 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 which reference SubModel submodel1. One Model Instance is named inst1, the other is named inst2. The SubModel submodel1 contains a Text Rectangle. The Text Rectangle has the following dynamics description: * fcolor fcolor_var stext stext_var "%d" This is the only dynamics description contained in submodel1. A total of two Variable References are in submodel1: fcolor_var and stext_var. Version 6.2a- 26 May 2006 SL-GMS Function Reference 100 Dynamics — Variable Definition Table attached to Models The application defines the following structures: /* Structure corresponding to each Variable Definition */ 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_parts array) are hard-coded to correspond exactly to SL-GMS objects. A more flexible application would use generic structures allocated at run time. SubModel Preparation Currently, Variable Definition Tables cannot be saved in ".m1" or ".g" files. They must be created at run time. To associate a Variable Definition Table with a Model Instance, the SubModel referenced by that Model Instance must also have an associated Variable Definition Table, created using gmsModDynInitVarDefTable( ). This call must occur before Model Instances referencing that SubModel are created or Version 6.2a- 26 May 2006 SL-GMS Function Reference 101 Dynamics — Variable Definition Table attached to Models loaded from disk. The SubModel gmsMXGet( ) or gmsM2XGet( ): must be pre-loaded using id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1"); The SubModel should be marked permanent so it is not inadvertently freed by SL-GMS (causing the Variable Definition Table to be lost): gmsModPermanent(submodel1, G_ON); The dynamics descriptions are then initialized, and a Variable Definition Table 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 is irrelevant in this example. The Variable Definition Table stored in submodel1 will never be bound directly to data. This table serves only as a template for the Variable Definition Tables accessed through the Model Instances which reference submodel1. Type, size, and count information is loaded into the Variable Definitions in the Variable Definition Table attached to submodel1. First a pointer to 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 also determines the indices of the Variable Definitions in the Variable Definition Table: id fcolor_vd; id stext_vd; int fcolor_index; int stext_index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 102 Dynamics — Variable Definition Table attached to Models 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 later use. 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 for submodel1: gmsModCacheCapacity(submodel1, 2); gmsModCacheCount(submodel1, 2); If the cache is created, and it is populated using gmsModCacheCount( ), it is important that gmsModCacheCount( ) be called after the SubModel has been initialized using the above procedures. In this way, the Variable Definition Table and the Variable Definition attribute information stored in the template SubModel will be cloned and available in the replicates. Version 6.2a- 26 May 2006 SL-GMS Function Reference 103 Dynamics — Variable Definition Table attached to Models Non-Replicated SubModel Initialization To make submodel1 non-replicated, gmsModNonReplicate( ) should be called after submodel1 is loaded, but before gmsModDynInitVarDefTable( ) is called: gmsModNonReplicate(submodel1, G_ON); If gmsModNonReplicate( ) is gmsModDynInitVarDefTable( ), the dynamics submodel1 will not be initialized properly. called after descriptions in Top Model Preparation After submodel1 has been loaded and initialized, the top-level Model topmodel1 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 Model Instance is obtained and stored in the topmodel1_parts array: topmodel1_parts[0].vdtable = gmsQVarDefTable(inst1); topmodel1_parts[1].vdtable = gmsQVarDefTable(inst2); Version 6.2a- 26 May 2006 SL-GMS Function Reference 104 Dynamics — Variable Definition Table attached to Models 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 id id id inst1_fcolor_vd; inst1_stext_vd; inst2_fcolor_vd; inst2_stext_vd; inst1_fcolor_vd = gmsQVDTVarDefAtIndex( topmodel1_parts[0].vdtable, topmodel1_parts[0].fcolor.vdt_ind ex); 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_ind ex); inst2_stext_vd = gmsQVDTVarDefAtIndex( topmodel1_parts[1].vdtable, topmodel1_parts[1].stext.vdt_inde x); 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); Version 6.2a- 26 May 2006 SL-GMS Function Reference 105 Dynamics — Variable Definition Table attached to Models Inform SL-GMS of Data Changes When data associated with a Variable Definition are modified, SL-GMS must be informed. This causes dynamics descriptions which reference the Variable Definition to be re-evaluated. When using a Variable Definition Table, currently only one function can inform SL-GMS of changes to data referenced by that Table: gmsVDTIndicesChanged( ). This function takes as parameters a Variable Definition Table, an array of indices into that Variable Definition Table, and the number of indices contained in that array. The indices specify which Variable Definitions in the Table should be flagged "changed." The gmsVDTIndicesChanged( ) function is typically called from the State 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 ALSO gmsVarDefType( ), gmsVarDefCount( ), gmsVarDefSize( ), gmsDynInit( ), gmsVarChanged( ), gmsStVarDefine( ), gmsMXGet( ), gmsM2XGet( ), gmsModCacheCount( ), gmsModCacheCapacity( ), gmsModNonReplicate( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 106 Dynamics — variables Dynamics — variables SUMMARY bind Variable References in Models to application program variables; notify SL-GMS that values of application program variables have changed NAME gmsVarDefine( ), gmsVarDefineNoTable( ), gmsVarTypeDefine( ), gmsVarChanged( ), gmsVarChangedAll( ), gmsVarDefChanged( ), gmsVarDefineChanged( ), gmsUnlinkVarDefs( ), gmsRemVarDefLinks( ), gmsFreeAllVarDefs( ), gmsFindVarDefAll( ) SYNTAX id gmsVarDefine (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 */ id gmsVarDefineNoTable char *name; void *address; int type; int count; int size; (name, address, type, count, size) /* name of variable */ /* address of variable */ /* type of variable */ /* number of data elements */ /* size of each data element */ int gmsVarTypeDefine (typecode, size) int typecode; /* type of variable */ int size; /* size of each data element */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 107 Dynamics — variables int gmsVarChanged (name, address) char *name; /* name of variable */ void *address; /* address of variable */ int gmsVarChangedAll (name, address) char *name; /* name of variable */ void *address; /* address of variable */ int gmsVarDefChanged (vardef) id vardef; /* pointer to Variable Definition object returned from gmsVarDefine( ) */ id gmsVarDefineChanged char *name; void *address; int type; int count; int size; (name, address, type, count, size) /* name of variable */ /* address of variable */ /* type of variable */ /* number of data elements */ /* size of each data element */ int gmsUnlinkVarDefs (obj) id obj; /* object to remove VarDefs from*/ int gmsRemVarDefLinks( ) int gmsFreeAllVarDefs( ) id gmsFindVarDefAll(name, address) char *name; /* name of variable */ void *address; /* address of variable */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 108 Dynamics — variables DESCRIPTION The gmsVarDefine( ) function internally creates Variable Definition objects and links them to the Variable Reference objects, created by gmsDynInit( ) in the global Variable Table — connecting Variable References in Models to the location where the variable’s value is stored in the application program. In addition to the location of the variable, SL-GMS must also be informed about the type of the variable because variables are stored internally in different forms, depending upon their type. The name of the variable as it appears in one or more dynamic descriptions is used as the first argument, name. The address argument is a location in the application where the value for this variable is stored. The type argument defines the data type of the value found at this address. The data type codes, defined in the file "gmscodes.h" distributed in the lib directory, are shown in the following table: Version 6.2a- 26 May 2006 SL-GMS Function Reference 109 Dynamics — variables gmsVarDefine( ) — Valid Codes for "type" Argument Code Base Types G_SHORT G_INTEGER G_LONG G_FLOAT G_PTR_TO_P TR G_DOUBLE G_REAL G_CHAR G_STRING G_POINTER Meta Type G_ARRAY (OR’d with Base Types)1 Description 2-byte integer 4-byte integer long integer (size is machine dependent) 4-byte real pointer to an arbitrary pointer 8-byte real 0x1 0x2 0x3 Decimal Value 1 2 3 0x4 0x5 4 5 0x8 8 Hex Value 1-byte char 0x10 pointer to pointer 0x100 to a null-terminated string 16 256 pointer to a byte or character (arbitrary address) 0x200 512 array — OR’d with any of the other types; count argument indicates length of the array 0x4000 16384 1. Other types can be created using gmsVarTypeDefine( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 110 Dynamics — variables EXAMPLE G_INTEGER|G_ARRAY specifies an array of integers with a hex value of 0x4002 and a decimal value of 16386. G_DOUBLE|G_ARRAY specifies an array of doubles with a hex value of 0x4008 and a decimal value of 16392. G_CHAR|G_ARRAY specifies an array of characters with a hex value of 0x4010 and a decimal value of 16400. Using the correct data type code is important. If the wrong type code is used, incorrect values may be implemented for updating dynamics, or a bus error can result from an attempt to access memory outside of the process limits. count denotes the number of data elements in a defined variable. size is the size of those data elements. If either count or size is greater than 1, SL-GMS forces the data type to G_ARRAY. NOTE: gmsVarDefine( ) must be called on variables whose memory have been allocated (e.g., via malloc( )) before an update pass. Variables which are locally defined to functions are not valid arguments to gmsVarDefine( ). The gmsVarDefine( ) function returns a pointer to the Variable Definition object created. A variable may be redefined whenever necessary to change the name and type attributes to which this variable refers by calling gmsVarDefine( ) again. The gmsDynInit( ) function must then be called to re-establish the links between the Variable Definition object and the Variable Reference objects which reference it. Version 6.2a- 26 May 2006 SL-GMS Function Reference 111 Dynamics — variables EXAMPLE The base of an array (i.e., the address of the Variable Definition object defining 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 Definition object. One method is to use gmsVarDefine( ), in which case the following call is made: /* define array to start at "base2" */ gmsVarDefine("y_array", &y_array[base2], G_DOUBLE | G_ARRAY, 100, 1); The Variable Definition object created with gmsVarDefine( ) may also be given a new address by calling gmsVarDefAddress( ). The count and size attributes can also be changed by calling gmsVarDefCount( ) and gmsVarDefSize( ). The gmsVarDefineNoTable( ) function defines variables similar to the way gmsVarDefine( ) does, however no internal global Variable Table is created thereby making this function faster than gmsVarDefine( ). The calling format (arguments) for gmsVarDefineNoTable( ) is the same as for gmsVarDefine( ). A Variable Definition object is returned from this function. Eliminating the internal look-up table requires that gmsVarDefChanged( ) be used to indicate that variables have changed rather than gmsVarChanged( ). The gmsVarDefineNoTable( ) function must be used in conjunction with gmsVarInitFctn( ) — an application maintains its own list of variable names and creates only the Variable Definition objects it needs by returning the appropriate pointers from the callback function set up by gmsVarInitFctn( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 112 Dynamics — variables 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 types can be defined. The gmsVarTypeDefine( ) function is used to define new data types to SL-GMS, such as arrays, structures, and so on. The data type codes already established by SL-GMS are listed in the table on page 110. The gmsVarChanged( ), gmsVarChangedAll( ), and gmsVarDefChanged( ) functions are used to inform SL-GMS that an application variable’s value has changed. These functions flag objects that are affected by a variable as "needs to be changed" which informs SL-GMS that the graphical objects referring to the named variable must be 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, as SL-GMS accesses the values of the other variables while updating the object. Likewise, if multiple graphics objects are dependent upon a single variable, SL-GMS needs to be informed only once that the value of the variable has changed. The gmsVarChanged( ) function is used in applications that do not contain multiple variables with the same address, whereas gmsVarChangedAll( ) is used in applications that do contain multiple variables with the same address. The gmsVarChanged( ) function is faster than gmsVarChangedAll( ) because it looks only for the first variable referring to a particular address, whereas gmsVarChangedAll( ) affects all Variable References, not just the first one. The update is not performed until the gmsDynUpdate( ) function is called. The gmsDynUpdate( ) function performs the task of referencing the variable’s value and making changes to the object(s). The gmsVarChanged( ) and gmsVarChangedAll( ) functions can be called with a nil argument for either the variable name or the variable address. The variable name is the same name as the string given in gmsVarDefine( ) and used in the DynProp. If the variable address in Version 6.2a- 26 May 2006 SL-GMS Function Reference 113 Dynamics — variables the application is present it should be used, since the search for the Variable Reference is somewhat faster than if the search were based upon the variable’s name. EXAMPLE Multiple variables may share the same address. If temp1 and temp2 are both defined as having address &temp, when gmsVarChangedAll( ) is called, all objects with references to the variables temp1 and temp2 are 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 used to notify SL-GMS that a variable has changed. The gmsVarDefChanged( ) function is more efficient than gmsVarChanged( ) because it takes a pointer to a Variable Definition returned by gmsVarDefineNoTable( ), whereas gmsVarChanged( ) must perform a lookup using the address of the variable (passed as a parameter) in the global Variable Table to retrieve the pointer to the Variable Definition. The gmsVarDefineChanged( ) function defines a variable and marks it as changed. This function is equivalent to calling both gmsVarDefine( ) and gmsVarChanged( ) on a variable, and it returns a pointer to the Variable Definition object created. In most cases, gmsVarDefineChanged( ) is used for first-time definition of variables to SL-GMS. In the case where separate calls for definition and change are used, a call to gmsVarChanged( ) is required to enable a variable defined by gmsVarDefine( ). A variable is recognized by SL-GMS the first time gmsVarChanged( ) is called for it, and is valid and usable thereafter. Once gmsVarChanged( ) has been called, however, there is no way to mark a variable as "not usable." When using SL-SMS, gmsVarDefine( ) is usually put in a State’s definevars method, and gmsVarChanged( ) in the State’s update method or user-defined GISMO Action function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 114 Dynamics — variables 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 mark them 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 size 12 */ gmsVarDefineChanged ("fieldbuf", fieldbuf, G_CHAR | G_ARRAY, 1, 12); /* "buf_array" has 3 elements of size 6 */ gmsVarDefineChanged ("buf_array", buf_array, G_CHAR | G_ARRAY, 3, 6); /* "string_array" has three elements in it */ gmsVarDefineChanged ("string_array", string_array, G_STRING | G_ARRAY, 3, 1); Version 6.2a- 26 May 2006 SL-GMS Function Reference 115 Dynamics — variables NOTE: The variable string_array can be used in Variable References as string_array[indexvar] where buf_array cannot since it is a two-dimensional array. The gmsRemVarDefLinks( ) function removes the links between Variable Reference objects and Variable Definition objects created by the gmsDynInit( ) and gmsVarDefine( ) functions. Removing these links is useful for use in conjunction with the gmsRenamedStr( ) function. In earlier versions of SL-GMS, if the user wished to free an object, two function calls were required. gmsRemVarDefLinks( ); was required before freeing the object to remove all of the links between Variable References and Variable Definitions in the global Variable Table and gmsDynInitNoMarks(nil); was required after freeing the object to re-establish the links for all Models. These two function calls were sometimes time-consuming. The gmsUnlinkVarDefs( ) function is more efficient and only a single call 6 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 116 Dynamics — variables gmsVarDefineNoTable( ), or gmsVarDefineChanged( ) must be unlinked using the function gmsUnlinkVarDefs( ) or gmsRemVarDefLinks( ) (or gmsDynEnd( )) before the Model is freed, otherwise the Variable Definitions will contain pointers to freed objects. The gmsFreeAllVarDefs( ) function frees the variable names and variable addresses in the Variable Definition table. Variable Definitions cannot be freed individually. The gmsObjFree( ) function is used to free Variable Definition objects created with the gmsVarDefineNoTable( ) function. To avoid erratic behavior, the gmsFreeAllVarDefs( ) function should be called only after calling either gmsDynEnd( ) or gmsUnlinkVarDefs( ). The gmsFindVarDefAll( ) function returns a pointer to a Variable Definition object in the global Variable Table. The gmsFindVarDefAll( ) function can be called with a nil argument for either the variable name or the variable address. The variable name is the same name as the string given in gmsVarDefine( ) and used in the DynProp. If the variable address in the application is present it should be used, since the search for the Variable Reference is somewhat faster than if the search were based upon the variable’s name. If both the address and the name are passed to gmsFindVarDefAll( ), first it searches by address, and then by name. SEE ALSO gmsDynInit( ), gmsDynUpdate( ), gmsVarDefCount( ), gmsVarDefSize( ), gmsObjFree( ) gmsVarDefAddress( ), gmsVarDefType( ), State — variables on page 382 Version 6.2a- 26 May 2006 SL-GMS Function Reference 117 Edge width attribute Edge width attribute SUMMARY set the edge width attribute for objects or query the current edge width attribute NAME gmsEWidth( ), gmsLEWidth( ), gmsMEWidth( ), gmsQEWidth( ) SYNTAX int gmsEWidth (obj, width) id obj; double width; int gmsLEWidth (objlist, width) id objlist; double width; int gmsMEWidth (width) double width; double gmsQEWidth (obj) id obj; DESCRIPTION This is a complete set of functions for the manipulation of the different width attributes supported by SL-GMS. The gmsEWidth( ) function applies to individual objects, gmsLEWidth( ) applies to Lists of objects, and gmsMEWidth( ) applies to the modal attributes. The query function, gmsQEWidth( ), returns the width attribute of the object, or Version 6.2a- 26 May 2006 SL-GMS Function Reference 118 Edge width attribute the modal attribute if a nil pointer is used. If an object without the width attribute is queried, 0 is returned. The modal attribute is referred to as the current width and is applied whenever new Primitive objects are created. DIAGNOSTICS Edge width is specified as a double argument. In most cases, it is desirable to represent it as an integer. This may be modified in future releases of SL-GMS. No bounds checking is done for attributes. It is assumed that the device driver software, at the SL-GWS layer of SL-GMS, deals with the attributes appropriately. SL-GML COMMAND [name] ewidth real Version 6.2a- 26 May 2006 SL-GMS Function Reference 119 Events — create Events — create SUMMARY create and modify events; add events to the SL-GMS Workstation event queue NAME gmsEvent( ), gmsWsAddEvent( ), gmsEvAction( ), gmsEvData( ), gmsEvExtent( ), gmsEvKeysym( ), gmsEvModifiers( ), gmsEvObject( ), gmsEvPoint( ), gmsEvStringC( ), gmsEvStringSO( ), gmsEvTime( ), gmsEvTrigger( ), gmsEvType( ), gmsEvView( ), gmsEvWorkst( ) SYNTAX id gmsEvent (event_type, workst, destroyCB) int event_type; /* event type code */ id workst; /* Workstation object */ int (*destroyCB)();/* optional destroy callback */ int gmsWsAddEvent (workst, event) id workst; /* Workstation object */ id event; /* SL-GMS event object */ int gmsEvAction (event, action) id event; /* Message event */ int action; /* event action code */ int gmsEvData (event, data) id event; /* Message event */ long data; /* event data */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 120 Events — create int gmsEvExtent (event, extent) id event; /* Window event */ id extent; /* event extent */ int gmsEvKeysym (event, keysym) id event; /* Key event */ unsigned long keysym;/* event keysym */ int gmsEvModifiers (event, modifiers) id event; /* Key or Locator event */ unsigned int modifiers;/* modifier codes */ int gmsEvObject (event, object) id event; /* Key or Locator event */ id object; /* SL-GMS object */ int gmsEvPoint (event, point) id event; /* Locator event */ id point; /* SL-GMS point object */ int gmsEvStringC (event, char_str) id event; /* Key event */ char *char_str; /* C string */ int gmsEvStringSO (event, str_obj) id event; /* Key event */ id str_obj; /* SL-GMS string object */ int gmsEvTime (event, sec, usec) id event; /* Any SL-GMS event */ unsigned long sec;/* event time - seconds */ unsigned long usec;/* event time - microseconds */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 121 Events — create int gmsEvTrigger (event, trigger) id event; /* Locator event */ int trigger; /* event trigger code */ int gmsEvType (event, type) id event; /* Any SL-GMS event */ int type; /* event type code */ int gmsEvView (event, view) id event; /* Key or Locator event */ id view; /* SL-GMS View object */ int gmsEvWorkst (event, workst) id event; /* Any SL-GMS event */ id workst; /* SL-GMS Workstation object */ DESCRIPTION The gmsEvent( ) function creates an SL-GMS event. The first argument, event_type, is an integer code for the desired event type. There are four event subclasses in SL-GMS: Locator, Key, Window, and Message Events. The event codes refer to event types within the event subclasses. The valid event types are found in the header "gmscodes.h" in the lib subdirectory and are listed below by event subclass for convenience. G_LOC_PRESS/* Locator Events */ G_LOC_RELEASE G_LOC_MOTION G_KEY_PRESS/* Key Events */ G_KEY_RELEASE G_WIN_EXPOSE/* Window Events */ G_WIN_EXPOSE_RECT G_WIN_RESIZE Version 6.2a- 26 May 2006 SL-GMS Function Reference 122 Events — create G_WIN_FOCUS_IN G_WIN_FOCUS_OUT G_WIN_ENTER G_WIN_LEAVE G_WIN_MAP G_WIN_UNMAP G_WIN_DESTROY G_MSG_CLIENT/* Message Events */ G_USER_EVENT The second argument, workst, is an SL-GMS Workstation object. The third argument, destroyCB, is a pointer to an optional "destroy callback" function for SL-GMS to call when it has finished processing the event. If NULL, or if the callback returns 0, SL-GMS will deallocate the 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 its Workstation, type, and timestamp attributes set. Before an event is added to the Workstation event queue, it must be populated with data appropriate for the event type. For instance, locator events need a Point object, key events need a key, window events need an extent, and message events should have data. Functions are provided that set an event’s data fields. After an event’s data is set, it is added to the Workstation event queue with the gmsWsAddEvent( ) function. The gmsEvAction( ) function sets the action attribute of a Message Event. The action argument is an integer value. The values assigned to the 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 the data attribute are application dependent. The gmsEvExtent( ) function sets the extent attribute of a Window Event. The extent argument is a Point list which contains two Points that define a rectangular area. See Point object on page 292 and LinkRef object on page 215 of this document for functions that create Version 6.2a- 26 May 2006 SL-GMS Function Reference 123 Events — create Point and LinkRef objects. After the call to gmsEvExtent( ) has been made, the LinkRef and Point objects should be freed. The gmsEvKeysym( ) function sets the keysym attribute of a Key Event. The keysym argument is a key code that represents a character that does not have a drawn representation such as a function key, or a control key. Valid keysym codes are found in the "keysymdef.h" header located in the lib directory. The gmsEvModifiers( ) funciton sets the modifiers attribute of a Key or Locator Event. The modifiers argument is an unsigned integer that contains one or more modifier codes. Event modifiers are the buttons or keys held down at the time of an Event. Event modifiers provide additional information about Locator and Keyboard Events. The valid Version 6.2a- 26 May 2006 SL-GMS Function Reference 124 Events — create Event modifier codes are contained in "gmscodes.h". This function used to be called gmsSEvModifiers( ) in earlier versions of SL-GMS. Event Modifier Codes Code G_LOC_BUTTON_1 G_LOC_BUTTON_2 G_LOC_BUTTON_3 G_LOC_BUTTON_4 G_LOC_BUTTON_5 G_LOC_BUTTON_LE FT G_LOC_BUTTON_MI DDLE G_LOC_BUTTON_RIG HT G_SHIFT_KEY G_LOCK_KEY G_CONTROL_KEY G_MOD1_KEY G_MOD2_KEY G_MOD3_KEY G_MOD4_KEY G_MOD5_KEY G_BPAD_BUTTON_0 G_BPAD_BUTTON_1 G_BPAD_BUTTON_2 G_BPAD_BUTTON_3 Version 6.2a- 26 May 2006 Description Mouse button 1 Mouse button 2 Mouse button 3 Mouse button 4 Mouse button 5 (syn. for G_LOC_BUTTON_1) (syn. for G_LOC_BUTTON_2) (syn. for G_LOC_BUTTON_3) key key key Workstation-dependent modifier key 1 Workstation-dependent modifier key 2 Workstation-dependent modifier key 3 Workstation-dependent modifier key 4 Workstation-dependent modifier key 5 Bitpad button 1 Bitpad button 2 Bitpad button 3 Bitpad button 4 SL-GMS Function Reference 125 Events — create The gmsEvObject( ) function sets the object attribute of a Key or Locator 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 the event in SL-GMS Internal Coordinates. See Point object on page 292 of this document for functions that create Point objects. SL-GMS Key events contain a String object that supports internationalized applications. There are two functions provided for setting a Key event’s String object. The gmsEvStringC( ) function’s char_str argument points to a C string (NULL terminated character array). The gmsEvStringSO( ) function’s str_obj argument is a String object. See Internationalization — String object on page 208 of this document for an explanation of String objects, and functions that create them. The gmsEvTime( ) sets the timestamp attribute of any SL-GMS event. The sec argument contains the seconds portion of the timestamp. The usec argument contains the microseconds portion of the timestamp. The gmsEvTrigger( ) function sets the trigger attribute of a Locator Event. The trigger argument contains the code for the button that Version 6.2a- 26 May 2006 SL-GMS Function Reference 126 Events — create triggered the event. The valid codes for this function are the locator button codes found in "gmscodes.h". . Locator Event Trigger Codes Code G_LOC_BUTTON_1 G_LOC_BUTTON_2 G_LOC_BUTTON_3 G_LOC_BUTTON_4 G_LOC_BUTTON_5 G_LOC_BUTTON_LEF T G_LOC_BUTTON_MID DLE G_LOC_BUTTON_RIG HT Description Mouse button 1 Mouse button 2 Mouse button 3 Mouse button 4 Mouse button 5 (syn. for G_LOC_BUTTON_1) (syn. for G_LOC_BUTTON_2) (syn. for G_LOC_BUTTON_3) The gmsEvType( ) function sets the type attribute for any SL-GMS event. The type argument can contain any valid event type. This function was called gmsEvCode( ) in earlier versions of SL-GMS. The gmsEvView( ) function sets the SL-GMS View associated with Key and Locator Events. The view argument must contain a valid View object. The gmsEvWorkst( ) function sets the SL-GMS Workstation associated with any event type. The workst argument must contain a valid Workstation object. DESTROY CALLBACK A destroy callback can be used to manage a pool of event objects. The event pool is created during application initialization and events are added to the Workstation queue as needed. When SL-GMS executes the destroy callback, it is an indication that SL-GMS is done with the event, and the event can be tagged for later reuse. If an event pool is used, care should be taken to clear an event’s data before it is reused. Version 6.2a- 26 May 2006 SL-GMS Function Reference 127 Events — create KEY EVENTS The keysym and String object attributes of a Key event are mutually exclusive. Only one of them should be set for any given Key event. EXAMPLE Create a Locator event, and set its point and object attributes. The following code is designed for use in a State method or a DsModelState 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 object named "test2" */ gmsCurModel(evModel); inputObject = gmsFindByName("test2"); /* Get the coordinates for the object’s reference point */ x = pntX(gmsQRefPoint(inputObject)); y = pntY(gmsQRefPoint(inputObject)); /* Create a Point object */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 128 Events — create tempPoint = pntNewXY(x,y); /* Set the event’s object and point attributes */ gmsEvObject(customEvent, inputObject); gmsEvPoint(customEvent,tempPoint); /* Free the temporary Point object */ pntFree(tempPoint); /* Add the event to the Workstation event queue */ gmsWsAddEvent(workst, customEvent); SEE ALSO Events — miscellaneous on page 130 The chapter entitled Event Handling in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 129 Events — miscellaneous Events — miscellaneous SUMMARY miscellaneous Event functions NAME gmsWaitEvent( ), gmsDispatchInputEvents( ), gmsDispatchTimerEvents( ), gmsEventPriority( ), gmsQGismoEvent( ) SYNTAX int gmsWaitEvent (workst) id workst; /* Workstation/Window object */ int gmsDispatchInputEvents ( ) int gmsDispatchTimerEvents ( ) int gmsEventPriority (flag) int flag; id gmsQGismoEvent ( ) DESCRIPTION The gmsWaitEvent( ) function causes SL-GMS to wait for an Event to occur on any Workstation/Window. The workst argument can be set to nil. In the future it may be possible to wait for an Event on a particular Workstation/Window. The gmsDispatchInputEvents( ) function dispatches all input Events (non-timer events) from each Workstation/Window. The function Version 6.2a- 26 May 2006 SL-GMS Function Reference 130 Events — miscellaneous returns 0 if there are no available input Events on any active Workstation/Windows. The gmsDispatchTimerEvents( ) function dispatches all timer Events from each Workstation/Window. The function returns 0 if no timer Events have arrived. The gmsEventPriority( ) function affects the priority of Events dispatched in the gmsMainLoop( ) function. It can set the relative dispatching priority of timer and non-timer events. The table below describes how gmsMainLoop( ) dispatches events each time around the event loop, according to the value of flag set by gmsEventPriority( ). 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_PRIORIT Y dispatch all non-timer events; dispatch all timer events G_NO_TIMERS dispatch all non-timer events; timer events are not dispatched at all The gmsQGismoEvent( ) function queries the Event which caused a GISMO to trigger. In previous versions of SL-GMS, it was required to IMPORT the SL-GMS internal variable g_event for this purpose. SEE ALSO The chapter entitled Event Handling in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 131 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 int gmsQEvAction (event) id event; /* Message Event */ int gmsQEvButtons (event) id event; /* Locator Event */ int gmsQEvData (event) id event; /* Message Event */ id gmsQEvExtent (event) id event; /* Window Event */ unsigned long gmsQEvKeysym (event) id event; /* Key Event */ int gmsQEvModifiers (event) id event; /* Key or Locator Event */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 132 Events — query id gmsQEvObject (event) id event; /* Key or Locator Event */ id gmsQEvPoint (event) id event; /* Locator Event */ int gmsQEvStringC (event, buffer, buffer_size, needed_size) id event; /* Key event */ char *buffer; int buffer_size; int *needed_size; int gmsQEvStringSO (event, buffer) id event; /* Key Event */ id buffer; /* String Object */ int gmsQEvTime (event, sec, usec) id event; /* any SL-GMS Event */ unsigned long *sec; unsigned long *usec; int gmsQEvTrigger (event) id event; /* Locator Event */ int gmsQEvType (event) id event; /* any SL-GMS Event */ id gmsQEvView (event) id event; /* Key or Locator Event */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 133 Events — query int gmsQEvViewIndex (event) id event; /* Key or Locator Event */ id gmsQEvWorkst (event) id event; /* any SL-GMS Event */ DESCRIPTION The gmsQEvAction( ) function queries the data attribute of a Message Event. The gmsQEvButtons( ) function queries the buttons held down for a Locator Event. This function returns a mask which may contain any of the G_LOC_* or G_BPAD_BUTTON_* codes. For a Locator Event triggered by G_LOC_PRESS, this function returns the state of the buttons just after the Event occurred. For a LocEvent triggered by G_LOC_RELEASE, it returns the state of the buttons just before the Event occurred. For a LocEvent triggered by G_LOC_MOTION, it returns the current state of the buttons. The gmsQEvData( ) function queries the data attribute of a Message Event. The gmsQEvExtent( ) function queries a Window’s extent and is used with Window Event objects. The function returns a pointer to a linked list which contains two Point objects. The values in the Point objects are in device coordinates (usually pixels). See Point object on page 292 and LinkRef object on page 215 of this document for functions that handle Point and LinkRef objects. The gmsQEvKeysym( ) function queries the keysym associated with a Key Event. The keysym definitions are found in "keysymdef.h". This function replaces the gmsQEvKeyCode( ) function in earlier versions of SL-GMS. The gmsQEvModifiers( ) function queries the buttons and/or keys held down when a Locator Event or Key Event occurred. This function returns a mask which may contain any of the Event modifier codes: G_LOC_BUTTON or G_BPAD_BUTTON codes, as well as G_SHIFT_KEY, G_CONTROL_KEY, and G_LOCK_KEY. This function Version 6.2a- 26 May 2006 SL-GMS Function Reference 134 Events — query returns the state of the modifier keys held down immediately before the Event occurred. The gmsQEvObject( ) function queries the object selected by a Locator Event with a G_LOC_PRESS Event code. This function only returns an object for States that have their gismoflag set to G_ON. If a State’s gismoflag is turned to G_OFF, this function returns 0. Internally, the gmsQEvObject( ) function calls gmsFindObject( ) only if 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 application program can call gmsFindObject( ) in the loc_press or loc_release callback functions, for example. The gmsQEvObject( ) function, when called in loc_motion or loc_release, returns the object saved in loc_press. The gmsQEvPoint( ) function queries the Point at which a LocEvent occurred. The Point object is returned in World Coordinates. The actual 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 the given Key Event object to the given character buffer. The buffer_size argument specifies the maximum number of bytes which can be copied to the given buffer, including the terminating character. If the needed_size argument is not equal to NULL, gmsQEvStringC( ) stores in the memory location referenced by needed_size an integer specifying the buffer size required to copy the entire string in the Key Event 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 buffer size required to copy the entire string in the Text or Text Rectangle. This enables an application to determine the exact buffer size needed before allocating the buffer. Version 6.2a- 26 May 2006 SL-GMS Function Reference 135 Events — query The gmsQEvStringC( ) function returns one of the values indicated in the following table: 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_FAIL URE Information was lost when the wide-character text string in the given object was converted to multi-byte form. If gmsQEvStringC( ) returns G_OVERFLOW, the number returned by needed_size can be used to allocate a larger buffer. After allocating a larger buffer, if buffer_size is greater than or equal to the number in needed_size, a second call to gmsQEvStringC( ) will not return G_OVERFLOW. The gmsQEvStringSO( ) function copies the string contained in the given Key Event object to the given String object. If the buffer in the given String object is not large enough to contain the entire string, it is freed and a larger one is allocated. The String object itself is not reallocated. The function returns 1 if it succeeds and 0 if it fails. The gmsQEvTime( ) function returns the timestamp of an SL-GMS event. The timestamp is returned in two portions. The sec argument will contain the seconds portion if the timestamp. The the usec argument will contain the microseconds portion of the timestamp. This function Version 6.2a- 26 May 2006 SL-GMS Function Reference 136 Events — query replaces the gmsQEvTimeSec( ) and gmsQEvTimeUSec( ) functions in earlier versions of SL-GMS. The gmsQEvTrigger( ) function queries the button which triggered a Locator Event. The function is only applicable for Locator Events with a code of G_LOC_PRESS or G_LOC_RELEASE. The trigger may be any 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 earlier versions 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 the SL-GMS View list in which the input Event (Locator Event, or Key Event) occurred. The gmsQEvWorkst( ) function queries any Event to determine the Workstation in which it occurred. SEE ALSO Events — miscellaneous on page 130 Internationalization — String object on page 208 The chapter entitled Event Handling in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 137 Events — timer Events — timer SUMMARY install callback function for timer Event; set timer period for an application; enable or disable timer Events for an application; query timer Event mask NAME gmsTimerEventFctn( ), gmsTimerPeriod( ), gmsTimerEventMask( ), gmsQTimerEventMask( ) SYNTAX int gmsTimerEventFctn (fctn) int (*fctn)( ); int gmsTimerPeriod (interval) int interval; /* interval in milliseconds */ int gmsTimerEventMask (action) int action; /* G_ENABLE or G_DISABLE */ int gmsQTimerEventMask ( ) DESCRIPTION The gmsTimerEventFctn( ) function installs a Workstation/Window callback function for a timer Event. Under X, the callback function is always installed for the first Workstation/Window. The gmsTimerEventFctn( ) function immediately enables timer Events and overrides the handling of timer Events by SL-SMS (i.e., overrides executing an update message for each active State). The gmsTimerPeriod( ) function resets the timer period to interval after a timer Event function has been set. If interval is set to 0 (the default), Version 6.2a- 26 May 2006 SL-GMS Function Reference 138 Events — timer updates are performed as fast as possible. The gmsTimerPeriod( ) function does not alter the Event dispatching order, rather, it affects the rate at which Event-handling functions are called. The gmsTimerPeriod( ) function requires a Workstation to be already in existence, otherwise it just returns. NOTE: A call to gmsTimerPeriod( ) must be done after a gmsInitStatesOnWs( ) call for timer intervals greater than 0. The gmsInitStatesOnWs( ) function sets the timer interval to 0. The gmsTimerEventMask( ) function enables or disables all timer Events. Timer Events are enabled by default when using SL-SMS (i.e., with a call to gmsInitStates( )). Timer Events are disabled by default when not using SL-SMS. NOTE: To disable timer Events for a particular State, the updflag flag for the State must be set to G_OFF. The gmsQTimerEventMask( ) function returns the current timer Event mask, either G_ENABLE or G_DISABLE. DIAGNOSTICS On X platforms, if a non-zero timer period is set with the gmsTimerPeriod( ) function, a timer application, gmstimer, is started. gmstimer sends a client message to the main SL-GMS application notifying it that a time interval has passed. There is overhead associated with the message being passed from one client to another. If the timer period is too small, messages may be sent from the gmstimer process to the main application faster than the system and main application can process them, thereby causing increased overhead and actually slowing down the main application. Therefore, for X platforms, SL recommends that the timer period be set greater than the time it takes for the main application to update the screen. For instance, if the main application takes 250 ms to update the screen, the timer period should be set to be somewhat greater than 250 ms (say, 300 ms). This setting allows the main application to process the timer Events as quickly as they are being sent to it, avoiding a backlog in the X event queue. Version 6.2a- 26 May 2006 SL-GMS Function Reference 139 Events — Xt and X applications Events — Xt and X applications SUMMARY enable a main loop external to SL-GMS for dispatching of events; pass events to SL-GMS gathered by an external loop function NAME gmsExternalEventLoopFlag( ), gmsQExternalEventLoopFlag( ), gmsProcessLowEvent( ) SYNTAX int gmsExternalEventLoopFlag (flag) int flag; /* 0 - normal 1 - no gather, may collapse 2 - no collapse */ int gmsQExternalEventLoopFlag ( ) int gmsProcessLowEvent (xev) XEvent *xev; DESCRIPTION The gmsExternalEventLoopFlag( ) function is used to specify that SL-GMS should not gather events, but that an application event loop function external to SL-GMS will do this instead. A three-level flag is used to control how events are gathered. The value of flag has the following effect: Version 6.2a- 26 May 2006 SL-GMS Function Reference 140 Events — Xt and X applications 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 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 events because an application event loop function external to SL-GMS is being used for this purpose. The value of 1 for flag specifies that SL-GMS is not to gather events but may compress and/or extract related events while processing an event that it has received from the application’s event loop function. For example, this will avoid multiple redraws in response to an expose and/or a configuration change of the window-manager window where SL-GMS is drawing dynamic graphics. The value of 2 for flag specifies that SL-GMS is not to gather or compress and/or extract related events while processing an event that it has received from the application’s event loop function. The application is assumed to have complete responsibility for such artifacts as multiple redraws in response to expose and/or configuration changes to the window-manager window where SL-GMS is drawing dynamic 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 to the gmsExternalEventLoopFlag( ) function). Version 6.2a- 26 May 2006 SL-GMS Function Reference 141 Events — Xt and X applications SEE ALSO gmsWsLowEventFctn( ), gmsNonWsLowEventFctn( ) — for further information about their use, especially in conjunction with the internal SL-GMS event loop function, gmsMainLoop( ) Without the functions documented in this section, the dispatching of Events is done inside of gmsMainLoop( ). The gmsmotifrun program of the gmsmotif on-line example shows how these functions are used. The appendix entitled SL-GMS Interface with the X Toolkit and X Windows in the SL-GMS Reference. Version 6.2a- 26 May 2006 SL-GMS Function Reference 142 Extent Extent SUMMARY return the extent and center of an object; set system-wide extent calculation flag NAME gmsQExtent( ), gmsLQExtent( ), gmsQPartExtent( ), gmsQExtCenter( ), gmsLQExtCenter( ) SYNTAX idLinkRef gmsQExtent (obj) id obj; idLinkRef gmsLQExtent (objlist) idLinkRef objlist; idLinkRef gmsQPartExtent (owner, object) id owner; /* the owning object */ id object; /* the object to query */ idPoint gmsQExtCenter (obj) id obj; idPoint gmsLQExtCenter (objlist) idLinkRef objlist; DESCRIPTION The gmsQExtent( ) function is used to obtain a Point List containing two Points which define the extent of any SL-GMS Graphical Primitive object. The gmsQExtent( ) function returns the extent of an object Version 6.2a- 26 May 2006 SL-GMS Function Reference 143 Extent only within its own coordinate system, that is, it takes into account only the Points defining the object and any transformation on that object. If a Model or Group containing that object has a transformation applied to it, that transformation is not applied to the extent Points returned when gmsQExtent( ) is called on that object itself. The gmsLQExtent( ) function does the same thing, but merges the extents of all the objects on the given List. The returned LinkRef should be freed with refKilAll( ). The gmsQExtCenter( ) function returns, for any SL-GMS object, a single Point object which is the center of the extent of the object. The gmsLQExtCenter( ) function does the same thing, but for the merged extent of all the objects in the List. The returned Point should be freed with pntFree( ). The table Center Point and center of extent illustrates the center of the extent of various types of SL-GMS objects and compares it to the center 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 144 Extent page 1-24. The dashed line around the objects indicates the extent of the object, and the "X" indicates the center of the extent. Center Point and center of extent Center Point returned from gmsQCenter( ) Object Rectangle Center of extent returned from gmsQExtCenter( ) zero (Use the function gmsQExtCenter( ) on page 1-144) Model Instance zero (Use the function gmsQExtCenter( ) on page 1-144) Group of objects zero (Use the function gmsQExtCenter( ) on page 1-144) Version 6.2a- 26 May 2006 SL-GMS Function Reference 145 Extent Center Point and center of extent (continued) Object Center Point returned from gmsQCenter( ) Center of extent returned from gmsQExtCenter( ) Circle Sector Pie The gmsQPartExtent( ) function queries the extent of an object within the coordinate system of an owner object. This function combines the transformation of the given owner and all Groups, Models, or Instances between it and the given object, and applies it to the extent of the object when it is returned. DIAGNOSTICS The extent and center of Text objects is not set until the Text object is displayed because the extent of Text objects is Workstation-dependent. Version 6.2a- 26 May 2006 SL-GMS Function Reference 146 Extent SEE ALSO gmsCenter( ), gmsQCenter( ) SL-GML COMMANDS name extent name center Version 6.2a- 26 May 2006 SL-GMS Function Reference 147 Fill direction and fill percent attributes 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 int gmsFDir (obj, filldir) id obj; int filldir; int gmsLFDir (objlist, filldir) idLinkRef objlist; int filldir; int gmsMFDir (filldir) int filldir; int gmsFPercent (obj, fpercent) id obj; double fpercent; int gmsLFPercent (objlist, fpercent) idLinkRef objlist; double fpercent; int gmsMFPercent(fpercent) double fpercent; Version 6.2a- 26 May 2006 SL-GMS Function Reference 148 Fill direction and fill percent attributes int gmsQFDir (obj) id obj; double gmsQFPercent (obj) id obj; DESCRIPTION These are a complete set of functions for the manipulation of the special attributes for percent-filled objects supported by SL-GMS. The gmsFDir( ) function applies to individual objects, gmsLFDir( ) to Lists of objects, and gmsMFDir( ) to the modal attributes. The four possible fill directions are represented in the following table. Fill DIrections 0 1 2 3 fill fill fill fill from from from from bottom left top right Other values are silently converted to the default of 0. The gmsFPercent( ) function changes the percent-filled attribute of the given 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 for objects 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 fill percent and is applied whenever new percent-filled objects are created. Version 6.2a- 26 May 2006 SL-GMS Function Reference 149 Fill direction and fill percent attributes DIAGNOSTICS As noted above, attributes are silently constrained to the stated limits. SL-GMS was enhanced in version 4.0e1 to percent-fill objects other than Rectangles. In earlier releases, all subclasses of G_FillEdge_30, except G_Rect_30, were displayed as if the percent-fill attribute were set 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 value of 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 contain fpercent 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, except G_Rect_30, are given an fpercent value of 100%. By performing an m1g (using release 4.0e of SL-GML) for all existing pre-4.0e1 ".m1" files, all ".g" files are converted. Since ".m1" files containing Graph objects cannot be saved with m1g, ".g" files for Graphs which have fpercent errors must be edited with a text editor. SEE ALSO gmsFRect( ), gmsRFRect( ) SL-GML COMMANDS [name] percent real [name] direction int Version 6.2a- 26 May 2006 SL-GMS Function Reference 150 Filled Filled SUMMARY set, reset, or query the filled attribute an object NAME gmsFilled( ), gmsLFilled( ), gmsMFilled( ), gmsQFilled( ) SYNTAX int gmsFilled (obj, filled) id obj; int filled; int gmsLFilled (objlist, filled) idLinkRef objlist; int filled; int gmsMFilled (filled) int filled; int gmsQFilled (obj) id obj; DESCRIPTION The 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 151 Filled last Points in that object form the border to the filled area, although no Edge is created. The gmsLFilled( ) function sets the filled attribute for all the objects in the given List. The gmsMFilled( ) function sets the modal filled attribute, which applies to all objects subsequently created. The gmsQFilled( ) function returns the filled attribute of the given object. SL-GML COMMAND [name] filled int Version 6.2a- 26 May 2006 SL-GMS Function Reference 152 Find file Find file SUMMARY install a user-defined find file function NAME gmsSetFileFindFctn( ) SYNTAX int gmsSetFindFileFctn (funct, base_filter, extension_filter) char *(*funct)(); char *base_filter; char *extension_filter; DESCRIPTION The gmsSetFindFileFctn( ) installs a user-defined find file function. A find file function is used to enhance, or override the path and file name used by SL-GMS when reading color definition, font definition, Model, and bitmap data. This capability allows SL-GMS to read information from directories that are not in the library search path, or to read data from a temporary file that contains information retrieved from a database 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 pipe character, ’|’. The user-defined find file function is called when SL-GMS needs data from a file with a base name that matches one in the list. If a Version 6.2a- 26 May 2006 SL-GMS Function Reference 153 Find file a matching file is found from the contents of base_filter, the extension_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 data from a file with an extension that matches one in the list. The user-defined find file function is deactivated by gmsSetFindFileFctn( ) with all three arguments set to NULL. calling The user-defined find file function must accept three character pointer arguments, and return a character pointer as shown below. char * myfunct char char char { } (base_name, ext, pathname) *base_name; *ext; *pathname; Where base_name is the base file name of the file from which SL-GMS needs data, ext is the list of file extensions that SL-GMS used in its search for the desired file, and pathname is the complete path and name of the file. The pathname argument will only contain information when SL-GMS has already found the file. A NULL return value tells SL-GMS to continue file operations using the existing file path and name. A non-NULL return value supplies SL-GMS with a replacement path and name. To override color and font defintion files, there are several additional conditions that must be met. The first condition is that the user-defined find file function must be installed before the first Workstation/Window is created. Secondly, the user-defined find file function will be called twice for a color definition file. Note that if a find file function is installed for .m2 files, it will also be called for .m1 files. Version 6.2a- 26 May 2006 SL-GMS Function Reference 154 Find file LIMITATIONS Only one find file function is allowed. Multiple functions cannot be installed for different base and extension filters. Find file functions do Worsktation. not currently work with the PostScript EXAMPLE To 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); Version 6.2a- 26 May 2006 SL-GMS Function Reference 155 Find file return newpath; } else { return NULL; } } Version 6.2a- 26 May 2006 SL-GMS Function Reference 156 Find object Find object SUMMARY find an object NAME gmsFindObject( ), gmsVuFindObject( ), gmsFindByName( ) SYNTAX id gmsFindObject (locevent, aperture, depthFlag) id locevent; double aperture; int depthFlag; id gmsVuFindObject (view, point, aperture, depthFlag) id view; idPoint point; double aperture; int depthFlag; id gmsFindByName (name) char *name; DESCRIPTION The gmsFindObject( ) function is intended to be used within a State Event handler. This function finds the object closest to the Point and in the View, specified by a Locator Event. If Views overlap, only objects in the top View (the last View displayed) are found. The description for the gmsView( ) function in this manual provides additional information. depthFlag specifies how deep to look before returning a pointer to an object. If depthFlag is 0 (zero), it searches at the highest level in the Model (i.e., a Group, rather than an object in the Group, is returned). If depthFlag is 1, the search is one level deep within Groups and the Version 6.2a- 26 May 2006 SL-GMS Function Reference 157 Find object nearest object one level deep is returned. If depthFlag is 2, the object returned may be part of a Group within another Group (two levels deep). If depthFlag is 4, for example, and there are only two levels of parts in the Model, depthFlag is treated as 2 (i.e., as far down as possible). In summary, the larger the depthFlag, the deeper the level of the object returned. The aperture controls the resolution of the mouse, that is, it specifies an extent around a mouse pick in which to search for objects. Typically 3.0 is used for aperture. EXAMPLE To find the object closest to a Locator Event and print its name: int loc_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 given name in the Name List of the current Model. If not found, it searches in the Name List of the Model specified by concatenating Model names, as in "gms.model.model1.obj". The object named must either be in the current Model or in the Name List of the SubModel or Model specified by 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 Instanced Models may follow, separated by dots. The last name in the string is the name of the object itself. The name "gms" followed by Model or Version 6.2a- 26 May 2006 SL-GMS Function Reference 158 Find object Instance names directs SL-GMS to search by descending Model Name Lists 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 been named. EXAMPLE If a Model named "valve" is instanced in a Model named "engine," and the 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 ALSO gmsView( ), gmsWind( ), gmsLPFndPt( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 159 Font Name Index Font Name Index SUMMARY determine font index from a font name NAME gmsQWsFontNameIndex( ) SYNTAX int gmsQWsFontNameIndex (ws, font_name, font_index) id ws; char *font_name; int *font_index; DESCRIPTION The gmsQWsFontNameIndex( ) function determines the SL-GMS index associated with the given font name on the given Workstation. If the given name is associated with an index, the function stores the SL-GMS index in the memory location referenced by the font_index parameter and returns 1. If the given name is not associated with an index, the function returns 0 and does not modify the memory location referenced by the font_index parameter. Currently, this function works only for the Windows NT Workstation class. Font name syntax is described in the SL-GMS® Reference. EXAMPLE Assume an SL-GMS application running under Windows NT uses the system font dialog to select a font to be used within SL-GMS. The application uses a "fontdef.dat" file that enumerates all possible fonts and styles available on the system. The application then creates a font name consistent with the format of "fontdef.dat" and the gmsQWsFontNameIndex( ) function retrieves the SL-GMS index Version 6.2a- 26 May 2006 SL-GMS Function Reference 160 Font Name Index associated with that font name. The index is used to modify the font index of a Text or Text Rectangle object. The following is an example of a call to gmsQWsFontNameIndex( ): int set_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 NT TrueType fonts available to SL-GMS. The "/demo/fonts/README" file provides more information about "fontdef.dat" and its uses. Version 6.2a- 26 May 2006 SL-GMS Function Reference 161 Free object Free object SUMMARY free an object or List of objects NAME gmsObjFree( ), gmsLObjFree( ) SYNTAX int gmsObjFree (obj) id obj; int gmsLObjFree (objlist) id objlist; DESCRIPTION The gmsObjFree( ) function is used to delete any Graphical Primitive, View, inactive State, or Model objects, created using SL-GMS function calls from the Graphical Modeling Hierarchy, that is, by freeing memory allocated for them. It is also used to delete ColDef objects created by gmsQWsColDef( ) and Variable Definition objects created with gmsVarDefineNoTable( ).1 Programs should always free objects when they are no longer needed, otherwise the data area allotted to the program continues to grow, eventually degrading system performance. Any pointer to the object should always be set to 0 after freeing the object. 1. Variable Definitions created with gmsVarDefine( ) or gmsStVarDefine( ) cannot be freed with this function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 162 Free object EXAMPLE id an_object; . . . gmsObjFree(an_object) an_object = 0; The gmsLObjFree( ) function performs the same function on a List of SL-GMS objects. The List itself is not freed. The refFree( ) function is used 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 called if the Variable-Definitions remain linked. All variables defined with gmsVarDefine( ) or gmsVarDefineChanged( ) must be unlinked using the function gmsUnlinkVarDefs( ) or gmsRemVarDefLinks( ) (or gmsDynEnd( )) before the Model is freed so that the Variable-Definitions do not contain pointers to freed objects. For example, the following functions can be called in sequence to free a Model after gmsDynInit( ) has been called on that Model: gmsUnlinkVarDefs(model); gmsObjFree(model); SEE ALSO gmsObjFree( ) does not work on Variable-Definition objects, except for those created with gmsVarDefineNoTable( ), nor low-level objects such as LinkRefs or Points. Variable-Definition objects must be freed using gmsFreeAllVarDefs( ) or gmsStFreeAllVarDefs( ). LinkRefs must be freed using refKilAll( ), and Points must be freed using pntFree( ). SL-GML COMMAND name free Version 6.2a- 26 May 2006 SL-GMS Function Reference 163 General transformation — absolute General transformation — absolute SUMMARY set an absolute general transformation NAME gmsASTran( ), gmsLASTran( ), gmsCASTran( ), gmsMASTran( ) SYNTAX int gmsASTran (obj,d0,d1,d2,d3,d4,d5) id obj; double d0; d1, d2, d3, d4, d5; int gmsLASTran (objlist,d0,d1,d2,d3,d4,d5) idLinkRef objlist; double d0; d1, d2, d3, d4, d5; int gmsCASTran (objlist, d0,d1,d2,d3,d4,d5) id objlist; double d0; d1, d2, d3, d4, d5; int gmsMASTran (d0,d1,d2,d3,d4,d5) double d0; d1, d2, d3, d4, d5; DESCRIPTION These functions define an absolute generalized 2x3 transformation. The six double arguments are placed into a 2x3 transformation matrix Version 6.2a- 26 May 2006 SL-GMS Function Reference 164 General transformation — absolute and added to the objects. matrix is: The order of the function arguments in the | d0 d3 | | d1 d4 | | d2 d5 | Any previously existing transformation matrices belonging to the objects are lost. The gmsXTran( ) function is used to apply an existing transformation to an object’s Points, or gmsRSTran( ) is used to combine transformations. The gmsASTran( ) function operates on an individual object, while the gmsLASTran( ) 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 immediately only if SL-GMS is in Immediate Update Mode. The gmsCASTran( ) function applies to the creation of future Clones or Instances. The gmsMASTran( ) function sets a modal transformation which 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 the translation in the y-axis direction, produces the matrix: | 1 0 | | 0 1 | | DxDy | Version 6.2a- 26 May 2006 SL-GMS Function Reference 165 General transformation — absolute 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 the scaling 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 the matrix: | 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 of standard matrix multiplication. SEE ALSO gmsRSTran( ), gmsLRSTran( ), gmsCRSTran( ), gmsMRSTran( ), gmsXTran( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 166 General transformation — relative General transformation — relative SUMMARY apply a relative general transformation to an object NAME gmsRSTran( ), gmsLRSTran( ), gmsCRSTran( ), gmsMRSTran( ) SYNTAX int gmsRSTran (obj,d0,d1,d2,d3,d4,d5) id obj; double d0, d1, d2, d3, d4, d5; int gmsLRSTran (objlist, d0,d1,d2,d3,d4,d5) idLinkRef objlist; double d0, d1, d2, d3, d4, d5; int gmsCRSTran (d0,d1,d2,d3,d4,d5) double d0, d1, d2, d3, d4, d5; int gmsMRSTran (d0,d1,d2,d3,d4,d5) double d0, d1, d2, d3, d4, d5; DESCRIPTION These functions define a relative generalized 2x3 transformation. The six double arguments are placed into a 2x3 transformation matrix and applied to the objects. (The discussion on page 164 provides additional information about the 2x3 matrix.) Any transformation matrices belonging to the objects are combined with this transformation matrix. The gmsRSTran( ) function operates on an individual object, while the gmsLRSTran( ) function operates on a List of objects. The object(s) is Version 6.2a- 26 May 2006 SL-GMS Function Reference 167 General transformation — relative first erased, the transformation applied, and the object(s) is redrawn. The erase and redisplay occur automatically only if SL-GMS is in Immediate Update Mode. The gmsCRSTran( ) function applies to the creation of future Clones or Instances. The gmsMRSTran( ) function sets a modal transformation which applies to all objects subsequently created. SL-GML COMMANDS [name] tran d0 d1 d2 d3 d4 d5 mtran d0 d1 d2 d3 d4 d5 Version 6.2a- 26 May 2006 SL-GMS Function Reference 168 GISMOs — initialization GISMOs — initialization SUMMARY initialize the GISMO Manager NAME gmsInitGismos( ) SYNTAX int gmsInitGismos( ) DESCRIPTION The gmsInitGismos( ) function initializes the GISMO Manager; it is called automatically as part of gmsMainInit( ). The standard GISMO variables defined by gmsInitGismos( ) are: _ _selected_object, _ _button_hilite, _ _button_index, _ _locator, and button_label. It should be noted that, with the exception of button_label, these are hidden variables and should not be renamed. The GISMO Action functions are also defined by gmsInitGismos( ). A complete list of the GISMO Action functions is found in the appendix entitled SL-GMS GISMO Library Reference in the SL-GMS Reference. Version 6.2a- 26 May 2006 SL-GMS Function Reference 169 GISMOs — processing GISMOs — processing SUMMARY invoke an object’s GISMO function as a result of a key press NAME gmsFKeyProcess( ) SYNTAX int gmsFKeyProcess (string) char *string; DESCRIPTION The gmsFKeyProcess( ) function processes a function key press by looking in the current Model, of the current State, for an object named "string". If found, it invokes the object’s GISMO function so the object behaves as if it were selected with the mouse. If not found, it attempts to send a message to the current State class (only if the Screen State Manager is active). Version 6.2a- 26 May 2006 SL-GMS Function Reference 170 Gradient fill attribute Gradient fill attribute SUMMARY set the gradient attribute for filled objects NAME gmsFGradient( ), gmsLFGradient( ), gmsQFGradient( ) SYNTAX int gmsFGradient (obj, points) id obj; id LinkRefpoints; int gmsLFGradient (objlist, points) id LinkRefobjlist; id LinkRefpoints; idLinkRef gmsQFGradient (obj) id obj; DESCRIPTION These functions set and query the gradient attribute for filled objects. The gmsFGradient( ) function sets the gradient attribute on a single object, while the gmsLFGradient( ) function works on a list of objects. The gradient attribute passed to these functions is a list of points. The list must contain a minimum of four points (or be NULL) and can contain up to seven points. A NULL list is used to remove the gradient attribute from an object. The first point in the gradient attribute point list contains the gradient style and height. The height information is used only for the elliptic style of gradient. The second and third points are explained under each Version 6.2a- 26 May 2006 SL-GMS Function Reference 171 Gradient fill attribute gradient style in the table below. The fourth through seventh points define gradient color intervals. The following table summarizes point list information. Point point 1 point 2 point 3 point 4 [point 5] [point 6] [point 7] NOTE: Description gradient style start point or focus 1 end point or focus 2 color interval 1 color interval 2 color interval 3 color interval 4 Contains style and height x and y x and y percent and color percent and color percent and color percent and color The height, x and y values are in internal coordinates. The percent values are percentages multiplied by 100. Therefore, 90.4 percent would be 9040. The gradient color intervals allow more than one color change to occur in the gradient. There can be up to four color intervals. Each interval takes up a percentage of the total gradient distance (the distance from the start to the end point or the elliptic height). The gradient shades from fcolor to color 1 then from color 1 to color 2, and so on, up to color 4 in the distances defined by each percent. All interval percents add up to 10000 (100 percent). The fcolor attribute defines the start color and the 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 points are in the second and third points of the gradient attribute List. The object is filled starting with the fcolor at the start point and shades to the end color at the end point. Past the start and end points the color shading will cycle back and forth between the start and end colors. Version 6.2a- 26 May 2006 SL-GMS Function Reference 172 Gradient fill attribute G_FGRADIENT_STYLE_LINEAR_ACYCLIC This style is defined by a start and end point. The start and end points are in the second and third points of the gradient attribute List. This style fills the object starting with the fcolor at the start point and shades to the end color at the end point. The color before the start point will be fcolor. The color after the end point will be end color. The color shading will not cycle with this style. G_FGRADIENT_STYLE_ELLIPTIC This style is defined by a height and two focus points. The second and third points in the gradient attribute List are the two foci (focus 1 and focus 2) of an ellipse. The object will be filled starting with the fcolor at the line that connects the two foci and shade to the end color at the perpendicular distance, height, away from the line. This forms a shaded ellipse around the foci. This style does not cycle the colors (the area past the ellipse defined by the height will be filled with the end color). If the two foci points are equal, the gradient will be circular and the height parameter is equivalent to the circle's radius. The gmsQFGradient( ) function returns the gradient attribute point list from a filled object. A NULL pointer will be returned if there is no gradient attribute set on the object. The returned LinkRef should be freed with refKilAll( ). SL-GML COMMANDS name fgradient int real x y x y real int [real int[real int[real int]]] LIMITATIONS The gradient fill is unavailable for dynamics. Percent fill does not work with the gradient fill. The gradient attribute is not a modal attribute. Version 6.2a- 26 May 2006 SL-GMS Function Reference 173 GraphAxis object GraphAxis object SUMMARY create a GraphAxis object and set its attributes NAME gmsGraphAxis( ), gmsCoordLimits( ), gmsValueLimits( ), gmsMajorSpacing( ), gmsMinorSpacing( ) SYNTAX id gmsGraphAxis (name, axisline, majtick, mintick, ticklabel) char *name; id axisline; id majtick; id mintick; id ticklabel; int gmsCoordLimits (obj, pointlist) id obj; /* GraphAxis or GraphTrace */ idLinkRef pointlist; int gmsValueLimits (obj, min, max) id obj; double min; double max; int gmsMajorSpacing (obj, spacing) id obj; double spacing; Version 6.2a- 26 May 2006 SL-GMS Function Reference 174 GraphAxis object int gmsMinorSpacing (obj, spacing) id obj; double spacing; Version 6.2a- 26 May 2006 SL-GMS Function Reference 175 GraphAxis object DESCRIPTION These functions create and set the attributes of GraphAxis objects. A GraphAxis requires several objects for use as templates and some attributes to be set before a single, labeled axis can be displayed. A GraphAxis object uses axisline as the template object for the axis. The original template object is not "consumed," only its attributes are copied and used. The template Line’s Point List is also not used. The ends of an axis are defined by using the gmsCoordLimits( ) function. A GraphAxis object also requires three other template objects: two tick marks and a label (Text) object. The two tick marks are line segments defined with the point (0,0) at one end. The orientation and length of these Lines are copied when these Lines are cloned to be used as tick marks. 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( ) function erases the entire area within the axes, it is not advisable to extend tick marks into the area where traces are drawn and erased. The tick label is a Text object that is cloned and placed relative to major tick marks. It should be built relative to the major tick mark Line template. For example, if the same two-unit major tick mark in the preceding example is used, the Text object used for the tick label should have its center below the point (0,-2). The text within the Text object is replaced when the axis is displayed depending upon the major tick mark spacing. The gmsValueLimits( ) function sets the values used to label the endpoints of the axis. The minimum endpoint is always labeled, however, the maximum endpoint is labeled only if the major tick spacing is chosen appropriately. The major tick spacing is set with the gmsMajorSpacing( ) function. The major tick spacing determines where major tick marks are drawn. The maximum endpoint is labeled if the major tick spacing evenly divides the range between the maximum and the minimum established by the call to gmsValueLimits( ). The gmsMinorSpacing( ) function sets the minor tick spacing and should evenly divide the major spacing range. SEE ALSO gmsGraphTrace( ), gmsPlotData( ) The chapter entitled in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 176 GraphAxis object SL-GML COMMANDS name 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 177 GraphTrace object GraphTrace object SUMMARY create a GraphTrace object, set or query its attributes NAME gmsGraphTrace( ), gmsXValueLimits( ), gmsYValueLimits( ), gmsQMaxTraceLength( ) SYNTAX id gmsGraphTrace (name, maxpoints, traceline,tracemarker) char *name; int maxpoints; id traceline; id tracemarker; int gmsXValueLimits (obj, xmin, xmax) id obj; double xmin; double xmax; int gmsYValueLimits (obj, ymin, ymax) id obj; double ymin; double ymax; int gmsQMaxTraceLength (obj) id obj; DESCRIPTION These functions create and set the attributes of GraphTrace objects. A GraphTrace requires that two objects be used as templates and some Version 6.2a- 26 May 2006 SL-GMS Function Reference 178 GraphTrace object attributes to be set before any plots are plotted. A GraphTrace object uses the traceline and the tracemarker as the template objects. If either of these templates is nil, the GraphTrace is composed of the remaining object’s attributes. These template objects are not "consumed," only its attributes are copied and used. The template objects’ Point Lists are also not used. The maxpoints argument sets the maximum number of Points that can be plotted within the GraphTrace. If additional Points are plotted, the oldest Points are discarded. The gmsCoordLimits( ) function is used to establish the area within which Points are plotted. This function requires a Point List with the lower left and upper right corner Points of a Rectangle in World Coordinates. The gmsXValueLimits( ) and gmsYValueLimits( ) functions determine the minimum and maximum values for Points to be plotted with a GraphTrace. The range between the minimum and maximum values is scaled so that it corresponds to the region defined by the call to gmsCoordLimits( ). The gmsQMaxTraceLength( ) function returns the number of Points that may be plotted using the given GraphTrace object. SEE ALSO gmsGraphAxis( ), gmsCoordLimits( ), gmsPlotData( ) The chapters entitled The Graphical Modeling Language and SL-GMS Reference Version 6.2a- 26 May 2006 in the SL-GMS Function Reference 179 GraphTrace object SL-GML COMMANDS name 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 180 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 id gmsGrid (name, sizex, sizey, color, edgestyle, markstyle) char *name; double sizex; double sizey; int color; int edgestyle; int markstyle; int gmsGridSize (obj, sizex, sizey) id obj; /* Grid object */ double sizex; /* x spacing */ double sizey; /* y spacing */ int gmsLGridSize (objlist, sizex, sizey) idLinkRef objlist; double sizex; double sizey; int gmsGridSizeX (obj, sizex) id obj; double sizex; Version 6.2a- 26 May 2006 SL-GMS Function Reference 181 Grid object int gmsGridSizeY (obj, sizey) id obj; double sizey; int gmsLGridSizeX (objlist, sizex) idLinkRef objlist; double sizex; int gmsLGridSizeY (objlist, sizey) idLinkRef objlist; double sizey; int gmsMGridSize (sizex, sizey) double sizex; double sizey; int gmsMGridSizeX (sizex) double sizex; int gmsMGridSizeY (sizey) double sizey; double gmsQGridSizeX (obj) id obj; double gmsQGridSizeY (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 182 Grid object DESCRIPTION The gmsGrid( ) function is used to create a Grid object. The sizex and 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 argument determines the style of the Grid’s Lines. If edgestyle equals 0, the Grid is drawn with Markers rather than Lines. The name argument is optional and is the name assigned to the object when it is added to the current Model. The gmsGridSize( ) function modifies the spacing of a Grid’s elements in the x and y dimensions. The gmsLGridSize( ) function modifies, for a List of Grid objects, the spacing 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 all objects on the List. The gmsLGridSizeY( ) function changes the y Grid spacing for all objects on the List. The gmsMGridSize( ) function sets the modal spacing of Grid elements in the x and y dimensions, which applies to all objects subsequently created. 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’s x spacing. The gmsQGridSizeY( ) function queries a Grid object’s y spacing. Version 6.2a- 26 May 2006 SL-GMS Function Reference 183 Grid object DIAGNOSTICS Grids in Graphs are created using GraphAxes, not Grid objects. SL-GML COMMAND [name:] grid xspace yspace color edgestyle markerstyle Version 6.2a- 26 May 2006 SL-GMS Function Reference 184 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 id gmsGroup (name, partlist) char *name; idLinkRef partlist; int gmsEndGroup( ) idLinkRef gmsDeGroup (group, displayflag) id group; int displayflag; idLinkRef gmsLDeGroup (grouplist, displayflag) idLinkRef grouplist; int displayflag; int gmsOpenGroup (group) id group; int gmsLOpenGroup (objlist) idLinkRef objlist; Version 6.2a- 26 May 2006 SL-GMS Function Reference 185 Group object int gmsCloseGroup (group) id group; int gmsLCloseGroup (objlist) idLinkRef objlist; id gmsFillGroup (name, partlist, filledFlag, boundFlag) char *name; idLinkRef partlist; int filledFlag; int boundFlag; int gmsFillGroupFlags (group, filledFlag, boundFlag) id group; int filledFlag; int boundFlag; int gmsLFillGroupFlags (objlist, filledFlag, boundFlag) idLinkRef objlist; int filledFlag; int boundFlag; int gmsUnFillGroup (group) id group; int gmsLUnFillGroup (objlist) idLinkRef objlist; Version 6.2a- 26 May 2006 SL-GMS Function Reference 186 Group object DESCRIPTION The gmsGroup( ) function is used to create a Group object given a List of individual parts. The parts may be any Graphical Primitive (Lines, Circles, Text, Groups, and so on). The name argument is optional and is the name assigned to the object when it is added to the current Model. 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 a Group current means that subsequent parts are added to the Group until the gmsEndGroup( ) function terminates creation. At this point the Group is added to the current Model and the name assigned.1 The gmsDeGroup( ) function may be used to destroy a Group while leaving its parts intact. The remaining parts are inserted into the owning Model’s part List at the same location as that of the destroyed Group in the List of all parts. The part List is returned from this function. displayflag causes SL-GMS to mark the parts for update if set 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 given List of Groups or FillGroups. The gmsFillGroup( ) function creates the specified type of FillGroup object (if possible), putting the given List of parts in it. An optional name may be assigned within the current Model. 1. A Group can also be made current with the gmsCurrent( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 187 Group object FillGroup Types Simple 1 1 Complex 1 0 Fill Bound Description All parts are open Primitives or unbounded Groups; edge is one continuous boundary. All parts are either Primitives or bounded Groups; each Primitive or bounded subnode is a boundary: a Multi-Faced object. The gmsFillGroupFlags( ) function converts the given Group or FillGroup into a FillGroup with the specified flags. The gmsLFillGroupFlags( ) function converts the List of Groups or FillGroups into Groups with the specified flags. The gmsUnFillGroup( ) function unfills the given FillGroup. The gmsLUnFillGroup( ) function unfills the given List of FillGroups. SEE ALSO gmsCurrent( ) 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 188 Group object - redrawing Group object - redrawing SUMMARY redraw Group objects NAME gmsRepairFlag( ) SYNTAX int gmsRepairFlag(group, flag) id group; /* SL-GMS Group */ int flag; /* repair flag = G_ON/G_OFF */ DESCRIPTION The gmsRepairFlag( ) function sets the repair flag for a Group. The constants G_ON or G_OFF may be used to set the state of the flag. If the repair flag is set on a Group, and one object in the Group is redrawn, all objects in the Group are redrawn. This flag does not eliminate the need for the batcherase flag. If erasing and redrawing an object in the Group will cause an erasure hole, the batcherase flag must still be set to prevent this. SEE ALSO gmsBatchErase( ) SL-GML COMMANDS [name:] repairflag int Version 6.2a- 26 May 2006 SL-GMS Function Reference 189 Internationalization — localization files Internationalization — localization files SUMMARY initialize the localization mechanism, retrieve localization strings, generate a localization file from a Model, apply a localization file to a Model, NAME gmsL10nInit( ), gmsL10nStr( ), gmsGenerateLocFileSO( ), gmsModApplyLocFileSO( ), gmsQSRStringSO( ), gmsSRApplyLocFileSO( ), gmsStringResource( ) SYNTAX int gmsL10nInit (file_name, section_name) char *file_name; char *section_name; t_addr gmsL10nStr (key_str, default_str) char *key_str; char *default_str; int gmsGenerateLocFileSO (model, file_name,output_wchar_file, prefix) id model; id file_name; int output_wchar_file; id prefix; int gmsModApplyLocFileSO id model; id file_name; id section; Version 6.2a- 26 May 2006 (model, file_name, section) /* optional Model */ /* localization file name */ /* optional section name */ SL-GMS Function Reference 190 Internationalization — localization files int gmsQSRStringSO (string_resource, key_string, loc_string) id string_resource; id key_string; /*identifies localized string */ id loc_string; /* localized string returned here */ int gmsSRApplyLocFileSO (string_resource, file_name, section) id string_resource; id file_name; /* localization file name */ id section; /* optional section name */ id gmsStringResource () DESCRIPTION Ideally, an internationalized application can be localized for a specific locale (or language) without duplicating or recompiling any source code. These areas of a SL-GMS application typically require localization: • 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 application source code should be kept in an external text file. Only strings which are ultimately presented to users should be in the external text file. In this way, the source code will not need to be modified when the application is localized; only the text files need to be modified. The String Resource object provides a system-independent mechanism for retrieving and identifying localized strings in such text files. In SL-GMS, these text files are called localization files. In a SL-GMS application, it is possible to localize the graphical user interface by creating duplicate copies of each Model used by the Version 6.2a- 26 May 2006 SL-GMS Function Reference 191 Internationalization — localization files interface. Each copy is customized for a specific locale. However, this causes maintenance problems: if the Model is modified, all duplicates must also be modified. To avoid these problems, the localized text used by a Model is stored in a localization file. The localization file can also specify which icons are to be used in a particular locale. Applying a localization file to a Model will customize the Model for a specific locale. There are two ways to apply a localization file to a Model: • 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 existing Model. The gmsL10nInit( ) and gmsL10nStr( ) functions are high-level functions used to manage localization (L10n) within an SL-GMS application. The gmsL10nInit( ) function is used to initialize the localization mechanism. The file_name argument specifies the name of a localization file. The section_name argument specifies the section of the localization file to use. The gmsL10nStr( ) function is used to localize strings. The key_str argument specifies a key used to find an associated localized string within the section of the localization file setup using gmsL10nInit( ). If an associated localized string cannot be found, the string provided in the default_str argument is returned. The pointer returned by gmsL10nStr( ) points to a static buffer that contains the localized string. 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 using gmsMainInit( ), or gmsInitialize( ). #ifdef WINNT_JAPANESE #define SECTION_NAME "Espanol" #else #define SECTION_NAME "English" Version 6.2a- 26 May 2006 SL-GMS Function Reference 192 Internationalization — localization files #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( ). Before localization 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 file from the given Model. The file_name argument, a String object, specifies the name of the localization file. The output_wchar_file argument specifies the data type of the localization file. If output_wchar_file is equal to one, the generated localization file will contain wide-characters (Unicode). Otherwise, a multi-byte localization file is generated. Wide-character localization files can be generated only on Windows NT. The prefix argument, a String object, is used to identify objects in the Model which need to be internationalized. Objects whose names contain "prefix" will generate commands in the localization file. If prefix is NULL, the default prefix "i_" is used. The function returns 1 if a non-empty localization file is generated successfully and 0 otherwise. Version 6.2a- 26 May 2006 SL-GMS Function Reference 193 Internationalization — localization files The following program fragment generates a multi-byte localization file named "menu_ja.lc" from the given Model. The default prefix, "i_", is used 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); } ... Version 6.2a- 26 May 2006 SL-GMS Function Reference 194 Internationalization — localization files 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 file specified by file_name, a String object, and applies commands in the file to the given String Resource. Only certain commands are String Resource specific. These commands are described in detail in the table Localization File Commands used by gmsSRApplyLocFileSO( ) on page 199. The function returns 1 if the localization file is read and applied successfully. The function returns 0 if any errors are encountered. The gmsQSRStringSO( ) function retrieves a localized string from the given String Resource. The key_string argument, a String object, identifies the localized string. The function looks up the localized string corresponding to key_string and copies it to the given loc_string argument (also a String object). The function returns 1 if the localized string can be found. If the localized string cannot be found, the function returns 0, and the contents of key_string are copied to loc_string. The gmsModApplyLocFileSO( ) function reads the localization file specified by file_name, a String object, and applies commands in the file to either the given Model, or, if the Model argument is NULL, to all Top Models and External SubModels in SL-GMS. Only certain commands apply specifically to Models. These commands are described in detail in the table Localization File Commands used by gmsModApplyLocFileSO( ) on page 200. If the Model argument is not NULL, the object names in the localization file specify objects contained in the given Model. The object names do not need to contain the name of the Model as a prefix. For example, if a Text object named "yes_button" is in a Group named "group1," and the Group is in a Model named "model1," the Text object can be specified by name as "group1.yes_button." If the Model argument is NULL, the object names in the localization file specify objects contained in any Top Model or External SubModel. In this case, each object name in the localization file must contain, as a prefix, the name of the Top Model or External SubModel which contains Version 6.2a- 26 May 2006 SL-GMS Function Reference 195 Internationalization — localization files the corresponding object. For example, if a Text object named "yes_button" is in a Group named "group1," and the Group is in a Model named "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. The function returns 0 if any errors are encountered. Both the gmsSRApplyLocFileSO( ) and gmsModApplyLocFileSO( ) functions adhere to this rule: if more than one localization file is applied to an object, the commands in the last localization file applied will override any conflicting commands in previously applied localization files. For example, if an application applies to a Model a localization file containing English strings, then applies to the same Model a localization file containing Japanese strings, the Japanese strings will replace the English strings in those cases where object names are the same in both files. When using either gmsSRApplyLocFileSO( ) or gmsModApplyLocFileSO( ), the section_name argument, a String object, serves to limit which lines are read from a localization file. If the section_name argument is not NULL, only commands contained in the section identified by section_name will be executed. Sections are defined in a localization file using the SECTION command (see the tables Localization File Commands used by gmsSRApplyLocFileSO( ) on page 199, and Localization File Commands used by gmsModApplyLocFileSO( ) on page 200). Commands which are specific to Model objects are ignored when applying a localization file with gmsSRApplyLocFileSO( ). Commands which are specific to String Resource objects are ignored when applying a localization file with gmsModApplyLocFileSO( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 196 Internationalization — localization files 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 characters surrounded by double quotes ("..."). The argument can contain spaces or tabs within the double quotes. The argument cannot contain newline or double-quote characters; to represent them, escape sequences are available. Version 6.2a- 26 May 2006 SL-GMS Function Reference 197 Internationalization — localization files The following escape sequences can be used: Name Escape Sequence Literal 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 The escape \ooo consists of a backslash followed by 1, 2, or 3 octal digits, which specify the value of the character. The escape \xhh consists of a backslash, followed by x, followed by hexadecimal digits, which specify the value of the character. Wide-Character and Multi-Byte Localization Files On Windows NT platforms, both wide-character and multi-byte localization files are supported by SL-GMS. SL-GMS automatically distinguishes between wide-character and multi-byte localization files on these platforms. Version 6.2a- 26 May 2006 SL-GMS Function Reference 198 Internationalization — localization files On all other platforms, only multi-byte localization files are supported. Localization File Commands used by gmsSRApplyLocFileSO( ) 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_RESOU RCEkey_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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 199 Internationalization — localization files Localization File Commands used by gmsModApplyLocFileSO( ) Syntax SECTION section_name Purpose Delimit a section within a localization file. PRIM Replace the string object_name contained in a Text or localized_string Text Rectangle object with a localized string. Version 6.2a- 26 May 2006 Description 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. 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. SL-GMS Function Reference 200 Internationalization — localization files Localization File Commands used by gmsModApplyLocFileSO( ) (continued) Syntax Purpose Description 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_INSTAN Different locales may CEobject_name use different symbols submodel_name 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 201 Internationalization — localization files Usage of gmsSRApplyLocFileSO( ) To retrieve localized strings needed by the application source code, the application first creates an empty String Resource object: id string_resource; string_resource = gmsStringResource(); Then a localization file is applied to string_resource, which loads localized strings into string_resource. In this example, the commands in the "English" section of the localization file named "locdemo.lc" are applied 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" Version 6.2a- 26 May 2006 SL-GMS Function Reference 202 Internationalization — localization files 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-time by applying a localization file to the Model. Since gmsModApplyLocFileSO( ) consumes time while localizing a Model, the function should not be used by applications which need to improve initialization performance. For such applications, the -loc option of the gm1 script should be used instead to localize Models before run-time. It is best to call gmsModApplyLocFileSO( ) on a Model before gmsDynInit( ) has been called on that Model. If gmsDynInit( ) has already been called, and the localization file contains "RENAMED_VAR" or "MODEL_INSTANCE" commands, gmsUnlinkVarDefs( ) must be called before gmsModApplyLocFileSO( ) 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: Version 6.2a- 26 May 2006 SL-GMS Function Reference 203 Internationalization — localization files 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, the commands 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 object named "greeting" will contain the text "Hello." Version 6.2a- 26 May 2006 SL-GMS Function Reference 204 Internationalization — localization files Localization File Examples Typically, an application will use at least two separate localization files. One file will contain localized strings used by the source code. This file is always applied to a String Resource object. Other localization files will contain commands applied to Models used by the application. This is an example of a localization file containing commands applied to a 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" Version 6.2a- 26 May 2006 SL-GMS Function Reference 205 Internationalization — localization files 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 206 Internationalization — localization files SEE ALSO gmsStringC( ), gmsTStringSO( ), gmsObjFree( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 207 Internationalization — String object Internationalization — String object SUMMARY create and get a String object, copy a wide-character string or a character string into a String object NAME gmsQStringC( ), gmsQStringWC( ), gmsStringC( ), gmsStringEmpty( ), gmsStringSetC( ), gmsStringSetWC( ), gmsStringWC( ) SYNTAX int gmsQStringC (string_obj, buffer, buffer_size, needed_size) id string_obj; char *buffer; int buffer_size; int *needed_size; int gmsQStringWC (string_obj, buffer, buffer_size, needed_size) id string_obj; wchar_t *buffer; int buffer_size; int *needed_size; id gmsStringC (string) char *string; id gmsStringEmpty () Version 6.2a- 26 May 2006 SL-GMS Function Reference 208 Internationalization — String object int gmsStringSetC (string_obj, string) id string_obj; char *string; int gmsStringSetWC (string_obj, string) id string_obj; wchar_t *string; id gmsStringWC (string) wchar_t *string; DESCRIPTION The String object is designed to support internationalized applications. To avoid string data type dependencies in an application, these dependencies must be encapsulated in an abstraction which can contain either character strings or wide-character strings. Such an abstraction is provided in the form of the String object. All operations on a String object work correctly regardless of the actual data type of the string contained in the object. For example, a String object created with a character string can be queried using a wide-character buffer, and vice versa. A String object first used to store a character string can later be reused to store a wide-character string. An application does not have to keep track of the data type associated with a String object. String objects also simplify string memory management. A String object automatically reallocates its internal string buffer when necessary. Any size string can be stored in a String object. The gmsStringWC( ) and gmsStringC( ) functions create a String object 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 String object. The gmsQStringWC( ) and gmsQStringC( ) functions query the contents of a String object using a wide-character or character buffer. Version 6.2a- 26 May 2006 SL-GMS Function Reference 209 Internationalization — String object The gmsStringWC( ) function creates and returns a new String object. A copy of the given wide-character string is stored in the String object. If the given string is NULL, the String object created contains an empty string (""). The function returns NULL if a memory allocation failure occurs. A String object can be freed using gmsObjFree( ). The gmsStringSetWC( ) function stores a copy of the given wide-character string in the given String object. The character string or wide-character string previously contained in the String object is destroyed. If the given wide-character string is NULL, the String object will contain an empty string ("") after the call to gmsStringSetWC( ). The function returns 1 if it succeeds and 0 if it fails. The gmsQStringWC( ) function copies the string contained in the given String object to the given wide-character buffer. The buffer_size argument specifies the maximum number of wide-characters which can be copied to the given buffer, including the terminating wide-character. If the needed_size argument is not equal to NULL, gmsQStringWC( ) stores in the memory location referenced by needed_size an integer specifying the buffer size required to copy the entire string in the String object to the buffer. The string copied to buffer is always terminated by the null wide-character (L'\0'), even when the function returns G_OVERFLOW. If buffer is NULL, the function will still return in needed_size the buffer size required to copy the entire string in the String object. This is the number of wide-characters needed, including the terminating wide-character. This enables an application to determine the exact buffer size needed before allocating the buffer. The gmsQStringWC( ) function can be called on a String object which contains a character string. The character string is converted to wide-character as it is copied to the given buffer. Version 6.2a- 26 May 2006 SL-GMS Function Reference 210 Internationalization — String object The gmsQStringWC( ) function returns one of the values indicated in the following table: 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 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 gmsQStringWC( ) returns G_OVERFLOW, the number returned by needed_size can be used to allocate a larger buffer. After allocating a larger buffer, if buffer_size is greater than or equal to the number in needed_size, a second call to gmsQStringWC( ) will not return G_OVERFLOW. The gmsStringC( ) function creates and returns a new String object. A copy of the given character string is stored in the String object. If the given 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 character string in the given String object. The character string or wide-character string previously contained in the String object is destroyed. If the given character string is NULL, the String object will contain an empty string ("") after the call to gmsStringSetC( ). The function returns 1 if it succeeds and 0 if it fails. The gmsQStringC( ) function copies the string contained in the given String object to the given character buffer. The buffer_size argument specifies the maximum number of bytes which can be copied to the given buffer, including the termination character. If the needed_size argument is not equal to NULL, gmsQStringC( ) stores in the memory location referenced by needed_size an integer specifying the buffer size required to copy the entire string in the String object to the buffer. Version 6.2a- 26 May 2006 SL-GMS Function Reference 211 Internationalization — String object 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 buffer size required to copy the entire string in the String object. This is the number of characters needed, including the termination character. This enables an application to determine the exact buffer size needed before allocating the buffer. The gmsQStringC( ) function can be called on a String object which contains a wide-character string. The wide-character string is converted to a multi-byte string as it is copied to the given buffer. This conversion is locale-dependent and may fail. The gmsQStringC( ) function returns one of the values indicated in the following table: 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 String object. 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 One or more of the wide-characters contained in the String object could not be converted to multi-byte form. If gmsQStringC( ) returns G_OVERFLOW, the number returned by needed_size can be used to allocate a larger buffer. After allocating a larger buffer, if buffer_size is greater than or equal to the number in needed_size, a second call to gmsQStringC( ) will not return G_OVERFLOW. However, the function may return G_CONVERSION_FAILURE. Version 6.2a- 26 May 2006 SL-GMS Function Reference 212 Internationalization — String object The gmsStringEmpty( ) function creates and returns a new String object. The String object contains an empty string. An empty String object is typically used as a parameter to functions which modify a given String object as part of a query operation, such as gmsQTStringSO( ), described in Text — object on page 401. SEE ALSO gmsQTStringSO( ), gmsRenVarStrConstReplSO( ), gmsTStringSO( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 213 Line object Line object SUMMARY create a Polyline object NAME gmsLine( ) SYNTAX id gmsLine (name, pointlist) char *name; idLinkRef pointlist; DESCRIPTION The gmsLine( ) function is used to create a Polyline object, given two or more Points contained in a Point List. Point Lists are created with the refNew( ) function. The current edge attributes are applied to the object when it is created. The name argument is optional and is the name assigned to the object when it is added to the current Model. The maximum number of Points in a single Polyline object is 10,240. SEE ALSO refNew( ) SL-GML COMMANDS [name:] line x y x y ... Version 6.2a- 26 May 2006 SL-GMS Function Reference 214 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 int refAdd (list, obj) idLinkRef list; id obj; idLinkRef refAppend (list, linkref) idLinkRef list; idLinkRef linkref; id refAt (list, index) idLinkRef list; int index; idLinkRef refAtInsert (list, index, obj) idLinkRef list; int index; id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 215 LinkRef object id refAtPut (list, index, obj) idLinkRef list; int index; id obj; idLinkRef refCloAll (list) idLinkRef list; int refCount (list) idLinkRef list; int refDoAll (list, func) idLinkRef list; int (*func)( ); int refDo1All (list, func, arg1) idLinkRef list; int (*func)( ); long arg1; int refDo2All (list, func, arg1, arg2) idLinkRef list; int (*func)( ); long arg1; long arg2; int refDo3All (list, func, arg1, arg2, arg3) idLinkRef list; int (*func)( ); long arg1; long arg2; long arg3; Version 6.2a- 26 May 2006 SL-GMS Function Reference 216 LinkRef object int refDo4All (list, func, arg1, arg2, arg3, arg4) idLinkRef list; int (*func)( ); long arg1; long arg2; long arg3; long arg4; idLinkRef refDupAll (list) idLinkRef list; int refFilter (list, obj) idLinkRef list; id obj; id refFind (list, obj) idLinkRef list; id obj; id refFndName (list, name) idLinkRef list; char *name; idLinkRef refFreAll (list) idLinkRef list; int refFree (list) idLinkRef list; int refIndex (list, obj) idLinkRef list; id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 217 LinkRef object idLinkRef refKilAll (list) idLinkRef list; id refLast (list) idLinkRef list; idLinkRef refNew( ) idLinkRef refNewN (n, obj1, obj2, ...) int n; id obj1, obj2 ...; idLinkRef refNewRef (obj) id obj; idLinkRef refRemove (list, obj) idLinkRef list; id obj; idLinkRef refReplace (list, obj1, obj2) idLinkRef list; id obj1; id obj2; id refQReference(self) idLinkRef self; /* a LinkRef object */ idLinkRef refQSuccessor(self) idLinkRef self; /* a LinkRef object */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 218 LinkRef object DESCRIPTION LinkRef (Linked Reference or List) objects are used to create lists of other objects. Each LinkRef object contains a pointer to its class (LinkRef), a pointer to the next LinkRef, the successor, and a pointer to an object, the reference. LinkRef objects LinkRef successor reference LinkRef successor reference LinkRef successor reference an Object an Object an Object The refQReference( ) and refQSuccessor( ) functions are used to query 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 the reference (or object) field of a LinkRef object. The refQSuccessor( ) function returns the pointer contained in the successor field of a LinkRef object. The pointer contained in the successor field of a LinkRef object is a pointer to the next LinkRef in a linked list of LinkRef objects. Version 6.2a- 26 May 2006 SL-GMS Function Reference 219 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. void process_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 the LinkRef object. SL-GMS handles the details of list manipulation and allocation internally. Lists of objects are required as arguments to many functions. Commonly, a function requires a List of Points or objects as an argument. Lists may be created using a sequence of refNewRef( ) and refAdd( ) functions, or by using refNewN( ) to build a List with one function. The refFilter( ) function, unlike refAdd( ), adds an object to a List only if the object is not already in it. The refAtInsert( ) function inserts an object inside a List at the specified index and returns a pointer to the first link in the List. The refAtPut( ) function replaces an link in a List with the given object and returns the replaced object. The refAppend( ) function appends its second argument to its first and returns the (altered) first List. Version 6.2a- 26 May 2006 SL-GMS Function Reference 220 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 object argument in the given List, replaces it with the second object, and returns a pointer to the List. The object at a particular index in the List may be queried using refAt( ); the index of the (first) occurrence of an object is returned by refIndex( ); 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 by refLast( ). The number of objects in a List may be queried using refCount( ). Individual LinkRefs may be freed using refFree( ); entire linked Lists may be freed by using the refFreAll( ) function. These functions do not free the objects in the List. The refKilAll( ) function not only frees the LinkRefs, but also the objects they reference. A duplicate of a List may be created using refDupAll( ). This function makes a copy of every LinkRef in the List, but not the objects to which they point. The refCloAll( ) function may be used to make a copy of the List, including all objects in the List. One of the advantages of Lists is that an operation defined by a function can be performed on every member of a List. The refDo*All( ) functions handle the details. The refDo*All( ) functions are provided the number of arguments and a pointer to the Lists. NOTE: A List should only be used to contain SL-GMS objects. DIAGNOSTICS The current interface for linked Lists requires that the programmer always remember to set the List header pointer by the return value of any function that returns the List, such as refRemove( ), and so on. Version 6.2a- 26 May 2006 SL-GMS Function Reference 221 LinkRef object EXAMPLE The following sequence adds two objects to a List, then removes them and 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; Version 6.2a- 26 May 2006 SL-GMS Function Reference 222 Main — SL-GMS main functions Main — SL-GMS main functions SUMMARY invoke a default SL-GMS startup configuration NAME gmsMainInit( ), gmsMainInitStr( ), gmsMain( ), gmsMainStr( ), gmsMainLoop( ) SYNTAX int gmsMainInit (argc, argv) int argc; /* standard main( ) arguments */ char **argv; int gmsMainInitStr (argstr) char *argstr; /* string containing main( ) arguments separated by spaces */ int gmsMain(argc, argv) int argc; char **argv; int gmsMainStr(argstr) char *argstr; /* standard main( ) arguments */ /* string containing main( ) arguments separated by spaces */ int gmsMainLoop( ) int gmsMainInit (argc, argv, xt_init) int *argc; char **argv; Version 6.2a- 26 May 2006 SL-GMS Function Reference 223 Main — SL-GMS main functions int gmsRunMainLoop ( ) DESCRIPTION These functions are the primary startup functions for SL-GMS. The gmsMainInit( ) function: 1. Processes any command gmsWsProcArgs( ) line options using NOTE: The switches used by gmsWsProcArgs( ) (documented in the Installation Notes) are reserved by SL-GMS and should not be used (for application-specific purpose) by programs that call gmsMainInit( ). 2. Sets the "input mode" flag to 1 using gmsInMode( ) NOTE: Setting the "input mode" flag to 1 turns off allocation of space for the SL-GMS Message Area of the graphics window. The Message Area is used to display prompts and external echo text. The "input mode" flag is 0 by default. 3. Creates a default Workstation/Window using gmsWorkst( ) if no Workstation/Window has already been created 4. Sets traps for the Workstation/Window just created using gmsSetTraps( ) 5. Adds search paths for the following directories: SUBMODS, GRAPHS, GISMOS using gmsAddLibPath( ) 6. Calls gmsInitGismos( ) to initialize GISMO variables and functions The gmsMainInit( ) function is essentially a convenience function; the steps listed above can be performed by a user-initialization function, if desired. Version 6.2a- 26 May 2006 SL-GMS Function Reference 224 Main — SL-GMS main functions If SL-SMS is being used, gmsInitStates( ) should be called after gmsMainInit( ). As of this version, gmsMainInit( ) functionality is deliberately separate from States functionality. For non-C programming languages, or situations where the argc - argv mechanism is inconvenient or simply unavailable, the gmsMainInitStr(argstr) function can be used instead of gmsMainInit( ). argstr is of type char *, where the character string contains space-separated arguments. Quotes attempting to combine words into one argument are not accounted for. The gmsMainLoop( ) function is a "do forever" loop for processing Events. In the loop, SL-GMS waits for an Event at any Workstation/Window. There are two types of Events: Timer Events and Input Events. When an Event is received, SL-GMS wakes up and dispatches the Event to the correct Event-handler for that type of Event. Normally, after every Event is dispatched, gmsDynUpdate(nil) gmsUpdate(nil) are invoked. In some cases this updating behavior may not be appropriate. Calling gmsAutoUpdateMode(G_OFF) allows the user to control updating explicitly. Also, the relative priority of 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, the function gmsMainStr(argstr) can be used instead of gmsMain( ). argstr is of type char *, where the character string contains space-separated arguments. Quotes attempting to combine words into one argument are not accounted for. Version 6.2a- 26 May 2006 SL-GMS Function Reference 225 Main — SL-GMS main functions EXAMPLE int main (argc, argv) int argc; char **argv; { ... /* set up SL-GMS */ gmsSetup( ); ... /* call the SL-GMS main initialization routine */ gmsMainInit(argc, argv); /* initialize the Screen State Manager */ gmsInitStates( ); ... /* application-specific initialization code here... */ /* go to loop forever */ gmsMainLoop( ); return 1; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 226 Main — SL-GMS main functions 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" int gmsMainLoop( ) { int alive = 1; while (alive) { /* a wait at any Workstation/Window ends when an Event occurs at any Workstation/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; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 227 Main — SL-GMS main functions /* this update could also be performed by the user; an update after dispatching Events may not be appropriate */ if (gmsQAutoUpdateMode( )) { gmsDefu( ); gmsDynUpdate(nil); gmsUpdate(nil); } } } SEE ALSO Events — Xt and X applications on page 140 for making use of an external main loop Version 6.2a- 26 May 2006 SL-GMS Function Reference 228 Marker — custom Marker — custom SUMMARY install a user-defined function for drawing custom markers NAME gmsUserMarkerFctn( ) SYNTAX int gmsUserMarkerFctn (fptr) int (*fptr)(); DISCRIPTION The gmsUserMarkerFctn( ) function installs a user-defined marker drawing function. The fptr argument specifies the address of the marker drawing function. Once it is installed, SL-GMS calls the custom marker drawing function for marker styles greater than five. The custom marker function must expect the following arguments by platform: For 32-bit Windows: int drawMyMarkers (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 */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 229 Marker — custom For Unix/X Windows: int drawMyMarkers (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 #include "gms.h" int drawMarker(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; Version 6.2a- 26 May 2006 SL-GMS Function Reference 230 Marker — custom } } int main (argc, argv) int argc; char **argv; { .... gmsUserMarkerFctn(drawMarker); ... } Unix/X Windows Example: #include #include "gms.h" int drawMarker(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; Version 6.2a- 26 May 2006 SL-GMS Function Reference 231 Marker — custom } int main (argc, argv) int argc; char **argv; { .... gmsUserMarkerFctn(drawMarker); ... } Version 6.2a- 26 May 2006 SL-GMS Function Reference 232 Marker — object Marker — object SUMMARY create a Marker object NAME gmsMark( ) SYNTAX id gmsMark (name, pointlist) char *name; idLinkRef pointlist; DESCRIPTION The gmsMark( ) function is used to create a Marker object given a set of Points contained in a Point List. The refNew( ) function is used to create Lists. The current Marker attributes are applied to the object when it is created. The name argument is optional and is the name assigned to the object when it is added to the current Model. SEE ALSO refNew( ) SL-GML COMMAND [name:] mark x y x y ... Version 6.2a- 26 May 2006 SL-GMS Function Reference 233 Marker — size attribute Marker — size attribute SUMMARY set the Marker size attribute for objects NAME gmsMSize( ), gmsLMSize( ), gmsMMSize( ), gmsQMSize( ) SYNTAX int gmsMSize (obj, size) id obj; double size; int gmsLMSize (objlist, size) idLinkRef objlist; double size; int gmsMMSize (size) double size; double gmsQMSize (obj) id obj; Version 6.2a- 26 May 2006 /* Marker object or nil pointer for modal query */ SL-GMS Function Reference 234 Marker — size attribute DESCRIPTION This is a complete set of functions for the manipulation of the Marker size attribute supported by SL-GMS. The gmsMSize( ) function applies to individual objects, the gmsLMSize( ) function applies to Lists of objects, and the gmsMMSize( ) function applies to the modal attributes. The gmsQMSize( ) function queries a Marker object’s size. If a nil pointer is used as an argument, the modal Marker size attribute is returned. A 0 is returned when the pointer refers to a non-Marker object. The modal attribute is referred to as "current" and is applied whenever new Marker objects are created. DIAGNOSTICS No bounds checking is done for attributes. It is assumed that the device driver software, at the SL-GWS layer of SL-GMS, deals with the attributes appropriately. Marker size is not supported by all different display packages and is ignored in such cases. SL-GML COMMAND [name] msize size Version 6.2a- 26 May 2006 SL-GMS Function Reference 235 Message tracing Message tracing SUMMARY turn on message tracing NAME gmsMtrFlag( ) SYNTAX int gmsMtrFlag (level) int level; DESCRIPTION The gmsMtrFlag( ) function affects message tracing — a debugging utility. Level 0 means no message tracing, level 1 means display all top-level (object) messages, and level 2 means display all top-level and object-internal messages. Version 6.2a- 26 May 2006 SL-GMS Function Reference 236 Model — object Model — object SUMMARY create or end a new Model; set the current Model; query for the System object’s Model List; query for the Local or External SubModels List of a Model NAME gmsModelWithParts( ), gmsModel( ), gmsEndModel( ), gmsQModelList( ), gmsQLocModelList( ), gmsQExtModelList( ) SYNTAX id gmsModelWithParts (name, partlist) char *name; idLinkRef partlist; id gmsModel (name) char *name; int gmsEndModel( ) idLinkRef gmsQModelList( ) idLinkRef gmsQLocModelList(model) id model; idLinkRef gmsQExtModelList(model) id model; Version 6.2a- 26 May 2006 SL-GMS Function Reference 237 Model — object DESCRIPTION The gmsModelWithParts( ) function creates a Model with the given name 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 the argument may be freed. The gmsModel( ) function is used to create a Model with default characteristics and add it to SL-GMS with the name given. This Model becomes the current Model. If there already was a Model current, the created Model is added to the List of local SubModels for the current Model. The new Model remains current and parts are added to the Model until the gmsEndModel( ) function is called. The gmsEndModel( ) function terminates the current Model, popping up a level in the Model hierarchy. Any additional Graphical Primitives created are added to the new current Model. The gmsQModelList( ) function returns the System object’s List of Models. A pointer to the actual SL-GMS internal List (a Linked Reference List) is returned. Therefore, the List must not be modified in any 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 must not be altered by the caller of these functions. Version 6.2a- 26 May 2006 SL-GMS Function Reference 238 Model — object SEE ALSO gmsModInst( ), gmsQCurModel( ), gmsCurrent( ) SL-GML COMMANDS name: model endmodel name current Version 6.2a- 26 May 2006 SL-GMS Function Reference 239 Model — save, get, merge Model — save, get, merge SUMMARY save or get a Model in binary format; save or get a Model in SL-GML format NAME gmsCGMGet( ), gmsMSave( ), gmsMGet( ), gmsMXGet( ), gmsMMerge( ), gmsMGSave( ), gmsM2Get( ), gmsM2XGet( ), gmsM2Merge( ), gmsM2Save( ), gmsExtSubModMode( ), gmsQExtSubModMode( ) SYNTAX idLinkRef gmsCGMGet (filename) char *filename; int gmsMSave (model, filename) idModel model; char *filename; id gmsMGet (modname, filename) char *modname; char *filename; id gmsMXGet (modname, filename) char *modname; char *filename; id gmsMMerge (filename) char *filename; Version 6.2a- 26 May 2006 SL-GMS Function Reference 240 Model — save, get, merge int gmsMGSave (model, filename) idModel model; char *filename; id gmsM2Get (modname, filename) char *modname; char *filename; id gmsM2XGet (modname, filename) char *modname; char *filename; id gmsM2Merge (filename) char *filename; int gmsM2Save (model, name) id model; char *name; int gmsExtSubModMode (mode) int mode; /* 0 or 1 */ int gmsQExtSubModMode ( ) DESCRIPTION The gmsCGMGet( ) function reads a file that is in CGM format and converts it to an SL-GMS Model. The gmsMSave( ) and gmsMGet( ) functions are used to save Models to a file and to read back Models thus saved. If the gmsMGet( ) function is given a modname argument, the Model read from the file is added to the Graphical Modeling Hierarchy using the given name, otherwise it defaults to the file name. Files saved by gmsMSave( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 241 Model — save, get, merge have the extension ".m1" added by SL-GMS. Similarly, when a Model file is read with gmsMGet( ), SL-GMS adds the ".m1" extension. NOTE: An "m1" file cannot be created if the Model contains more than 2,147,483,647 (231 - 1) objects. When a Model is read in and there is no current Model, the Model becomes top-level. If a Model is current, the Model read in becomes a local SubModel of the current Model. All Models have names within SL-GMS. If the modname argument to gmsMGet( ) is null, the filename (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 to the External SubModels List of the current Model. The SubModel becomes available for instancing within the current Model. The SubModel’s name defaults to the file name without the ".m1" extension if the modname argument is null. This function is used to preload an External Model before it is actually employed and also for SubModel caching. The gmsMMerge( ) function merges the Model read from the file with the current Model. The current Model’s name becomes that of the newly-merged Model. Dynamics Initialization (gmsDynInit( )) is performed immediately on dynamic 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 used in 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’s Local SubModels List, or the System object’s Model List if no Model is current, using modname (which defaults to filename). Version 6.2a- 26 May 2006 SL-GMS Function Reference 242 Model — save, get, merge The gmsM2XGet( ) function extracts a Model from a file and adds it to the External SubModels List of the current Model. The SubModel becomes available for instancing within the current Model. The SubModel’s name defaults to the file name without the ".m2" extension if the modname argument is null. This function is used to preload an External Model before it is actually employed and also for SubModel caching. The gmsM2Merge( ) function merges the current Model with the Model in filename (the ".m2" extension is added). The Model must be current in order to merge. The gmsM2Save( ) function saves the Model specified. saved as "". The Model is The gmsExtSubModMode( ) function controls the loading of external SubModels when a Model is read from disk. When the External SubModel Mode is set to 1 (the default), external SubModels are loaded 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 user wishes to read in a Model whose SubModels may not be necessarily built. The gmsQExtSubModMode( ) function returns the current External SubModel Mode. SEE ALSO gmsDynInit( ), gmsModInst( ) SL-GML COMMANDS name save [filename] name gsave [filename] [name:] model get filename [name:] model xget filename Version 6.2a- 26 May 2006 SL-GMS Function Reference 243 Model — save, get from pseudo-files Model — save, get from pseudo-files SUMMARY Install Filer interception functions NAME gmsFilerFctn( ), gmsQFilerDataFiler( ), gmsQFilerDataAction( ), gmsQFilerDataFilename( ), gmsQFilerDataPseudoFile( ), gmsFilerDataPseudoFile( ), gmsQFilerDataSize( ), gmsFilerDataSize( ), gmsQFilerDataType( ) SYNTAX int gmsFilerFctn (filer, callback, callback_arg) int filer; int (*callback)( ); void *callback_arg; int gmsQFilerDataFiler (filer_data) id filer_data; int gmsQFilerDataAction (filer_data) id filer_data; char * gmsQFilerDataFilename (filer_data) id filer_data; void * gmsQFilerDataPseudoFile (filer_data) id filer_data; Version 6.2a- 26 May 2006 SL-GMS Function Reference 244 Model — save, get from pseudo-files int gmsFilerDataPseudoFile (filer_data, pseudo_file) id filer_data; void *pseudo_file; int gmsQFilerDataSize (filer_data) id filer_data; int gmsFilerDataSize (filer_data, size) id filer_data; int size; int gmsQFilerDataType (filer_data) id filer_data; DESCRIPTION The gmsFilerFctn( ) function installs a user-defined Filer intercept function in SL-GMS. Filer intercept functions allow the application programmer to use pseudo-files instead of real files for some stream I/O operations. A pseudo-file is a block of memory which contains data normally contained in a file. The gmsFilerFctn( ) function is used when Models cannot be and retrieved using C library I/O functions. For example, application must store Models in the form of BLOBs (Binary Objects) in a database, gmsFilerFctn( ) would be used to install intercept function which accesses the database. stored if an Large a Filer The Filer intercept function should be installed before any Models are loaded by SL-GMS. The gmsFilerFctn( ) function should be called sometime after gmsSetup( ), and before the first Models are loaded. The filer argument specifies the Filer type associated with the Filer intercept function. The following Filer type values are currently defined: G_FILER_M1 Version 6.2a- 26 May 2006 Each time SL-GMS must find, read, or write a ".m1" file, the callback function pointer will be invoked. SL-GMS Function Reference 245 Model — save, get from pseudo-files 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 an interception function to retrieve the data type associated with a FilerData: The data type associated with the G_FILER_M1 and G_FILER_M2 Filer types is G_FILER_BINARY. The data type associated with the G_FILER_LOCFILE Filer type is either G_FILER_CHAR or G_FILER_WCHAR, depending upon the localization file format (character or wide-character format). Wide-character localization files are supported on Windows NT platforms only. The callback function pointer should point to a function defined using the following template: static int filer_callback (callback_arg, filer_data) void *callback_arg; id filer_data; The callback_arg argument is a user-defined pointer previously stored using gmsFilerFctn( ). It is optional. One possible use for this would be a pointer to a user-defined structure or object which stores information used by the filer_callback( ) function. The filer_data argument is a pointer to a G_FilerData object. The object 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 246 Model — save, get from pseudo-files 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 associated with filer_data using gmsQFilerDataAction( ). The action attribute specifies the actions the callback function must perform. This attribute can have the following values: Version 6.2a- 26 May 2006 SL-GMS Function Reference 247 Model — save, get from pseudo-files G_FILER_QUERY_EXISTS: The gmsQFilerDataFilename( ) function should be used to retrieve the filename of the pseudo-file. The callback function should return 1 if the pseudo-file specified by the filename exists. The callback function should return 0 if it does not exist. G_FILER_QUERY_WRITABLE: The gmsQFilerDataFilename( ) function should be used to retrieve the filename of the pseudo-file. The callback function should return 1 if the pseudo-file specified by the filename is writable. The callback function should return 0 if it is not writable. G_FILER_OPEN_WRITE: The gmsQFilerDataFilename( ) function can be used to retrieve the filename 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 empty pseudo-file. The pseudo-file pointer should be installed in filer_data using 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 written and is now being closed. The gmsQFilerDataFilename( ) function can be used to retrieve the filename of the pseudo-file. The gmsQFilerDataPseudoFile( ) function should be used to retrieve the pseudo-file pointer contained in filer_data. This is a pointer to a pseudo-file which was previously opened for writing. The gmsQFilerDataSize( ) function can be used to retrieve the size, in bytes, of the pseudo-file. Version 6.2a- 26 May 2006 SL-GMS Function Reference 248 Model — save, get from pseudo-files The callback should perform whatever operations are necessary to save the data in the pseudo-file and free the resources (memory and such) associated with the pseudo-file. If successful, the callback function should return 1. If unsuccessful, the callback function should return 0. G_FILER_CLOSE_WRITE_FAILURE: This action value indicates that an attempt to write to the pseudo-file has failed and the data in the pseudo-file are invalid. The callback should free the resources (memory and such) associated with the pseudo-file and return 1. G_FILER_QUERY_READABLE: The gmsQFilerDataFilename( ) function should be used to retrieve the filename of the pseudo-file. The callback function should return 1 if the pseudo-file specified by the filename exists and is readable. The callback function should return 0 if either of these conditions is false. G_FILER_OPEN_READ: The gmsQFilerDataFilename( ) function can be used to retrieve the filename of the pseudo-file. The callback function should obtain a pointer to the pseudo-file specified by the filename. The pseudo-file pointer should be installed in filer_data using gmsFilerDataPseudoFile( ). The size, in bytes, of the pseudo-file must be recorded in filer_data using gmsFilerDataSize( ). If successful, the callback function should return 1. If unsuccessful, the callback function should return 0. G_FILER_CLOSE_READ: The gmsQFilerDataFilename( ) function can be used to retrieve the filename of the pseudo-file. The gmsQFilerDataPseudoFile( ) function should be used to retrieve the pseudo-file pointer contained in filer_data. This is a pointer to a pseudo-file previously opened for reading. Version 6.2a- 26 May 2006 SL-GMS Function Reference 249 Model — save, get from pseudo-files The callback should perform whatever operations are necessary to free the resources (memory and such) associated with this pseudo-file. If successful, the callback function should return 1. If unsuccessful, the callback function should return 0. If a callback function has been installed for the Filer type G_FILER_M1, the callback function will be invoked several times each time a corresponding pseudo-file must be accessed. The callback function will be invoked with the following series of action values when a pseudo-file is written: G_FILER_QUERY_EXISTS G_FILER_QUERY_WRITABLE G_FILER_OPEN_WRITE G_FILER_CLOSE_WRITE_SUCCESS G_FILER_CLOSE_WRITE_FAILURE or The callback function will be invoked with the following series of action values when a pseudo-file is read: G_FILER_QUERY_READABLE G_FILER_OPEN_READ G_FILER_CLOSE_READ EXAMPLE In this example, the application must save, find, and retrieve Models in the form of a BLOB from a database. The Filer intercept function is filer_callback( ). The callback_arg is not used in this example, so it is NULL: int filer_callback( ); gmsFilerFctn(G_FILER_M1, filer_callback, NULL); The filer_callback( ) function serves as a control center. It extracts the action associated with the G_FilerData object filer_data and branches to one of eight sub-functions, depending upon the value of action: Version 6.2a- 26 May 2006 SL-GMS Function Reference 250 Model — save, get from pseudo-files static int filer_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: Version 6.2a- 26 May 2006 SL-GMS Function Reference 251 Model — save, get from pseudo-files 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( ) to obtain the filename identifying the pseudo-file. The function determines if a BLOB corresponding to this filename exists in the database. If so, the function returns 1. If not, the function returns 0. static int query_exists (filer_data) id filer_data; { char int *filename; exists; filename = gmsQFilerDataFilename(filer_data); /* Code below determines if a BLOB corresponding to filename exists in the database. If so, the exists flag is set to 1. Else the exists flag is set to 0. */ . . . return exists; } The query_writable( ) function uses gmsQFilerDataFilename( ) to obtain the filename identifying the pseudo-file. The function determines if any BLOB corresponding to this filename in the database Version 6.2a- 26 May 2006 SL-GMS Function Reference 252 Model — save, get from pseudo-files is writable. If so, query_writable( ) returns 1. If not, query_writable( ) returns 0. static int query_writable (filer_data) id filer_data; { char int *filename; writable; filename = gmsQFilerDataFilename(filer_data); /* Code below determines if any BLOB corresponding to filename in the database is writable. If so, the writable flag is set to 1. Else the writable flag is set to 0. */ . . . return writable; } The open_write( ) function uses gmsQFilerDataSize( ) to determine the size, in bytes, of the empty pseudo-file requested. The function allocates a block of memory containing this many bytes (an empty pseudo-file). A pointer to this block is installed in filer_data using gmsFilerDataPseudoFile( ): static int open_write (filer_data) id filer_data; { int void size; *pseudo_file; size = gmsQFilerDataSize(filer_data); Version 6.2a- 26 May 2006 SL-GMS Function Reference 253 Model — save, get from pseudo-files /* allocate a block of memory containing size bytes */ pseudo_file = malloc(size); *** code continued on next page *** if (pseudo_file == NULL) return 0; /* install pseudo_file pointer in filer_data */ gmsFilerDataPseudoFile(filer_data, pseudo_file); return 1; } The close_write( ) function uses gmsQFilerDataPseudoFile( ) to retrieve the pseudo-file pointer in filer_data. This pointer is assigned to the variable pseudo_file. The data referenced by pseudo_file are copied to a BLOB in the database. The memory referenced by pseudo_file is then freed: static int close_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 the database */ . Version 6.2a- 26 May 2006 SL-GMS Function Reference 254 Model — save, get from pseudo-files . . } /* free pseudo_file */ free(pseudo_file); return 1; } The query_readable( ) function uses gmsQFilerDataFilename( ) to obtain the filename identifying the pseudo-file. The function determines if a BLOB corresponding to this filename exists in the database. If so, query_readable( ) returns 1. If not, query_readable( ) returns 0. static int query_readable (filer_data) id filer_data; { char int *filename; readable; filename = gmsQFilerDataFilename(filer_data); /* Code below determines if the BLOB corresponding to filename exists in the database. If so, readable flag is set to 1. Otherwise, readable flag is set to 0. */ . . . return readable; } The open_read( ) function uses gmsQFilerDataFilename( ) to obtain the filename identifying the pseudo-file. The function looks up the BLOB corresponding to this filename in the database. A block of memory large enough to hold the information in the BLOB is allocated and a pointer to this block is assigned to pseudo_file. The data in the Version 6.2a- 26 May 2006 SL-GMS Function Reference 255 Model — save, get from pseudo-files BLOB are copied into the memory referenced by pseudo_file. The pseudo_file pointer is installed in filer_data using gmsFilerDataPseudoFile( ), and the size of the pseudo-file is recorded in filer_data using gmsFilerDataSize( ). static int open_read (filer_data) id filer_data; { char int void *filename; size; *pseudo_file; filename = gmsQFilerDataFilename(filer_data); /* code below will look up BLOB corresponding to filename */ . . . /* code below will assign to size the number of bytes required to store the 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 BLOB to memory referenced by pseudo_file */ . . Version 6.2a- 26 May 2006 SL-GMS Function Reference 256 Model — save, get from pseudo-files . /* install pseudo_file pointer in filer_data */ gmsFilerDataPseudoFile(filer_data, pseudo_file); /* record pseudo-file size in filer_data */ gmsFilerDataSize(filer_data, size); return 1; } close_read( ) uses gmsQFilerDataPseudoFile( ) to retrieve the pseudo-file pointer in filer_data. The memory referenced by pseudo_file is then freed: static int close_read (filer_data) id filer_data; { void *pseudo_file; pseudo_file = gmsQFilerDataPseudoFile(filer_data); /* free pseudo_file */ free(pseudo_file); return 1; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 257 Model — user header string Model — user header string SUMMARY Set and query the user header string of a Model in memory. Query the user header string of a Model file on disk. The format of a user header string is similar to that of RenamedVar strings: 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 int gmsMUserHeaderStr (model, user_str) id model; char *user_str; char * gmsQMUserHeaderStr (model) id model; char * gmsMGetUserHeaderStr (filename) char *filename; Version 6.2a- 26 May 2006 SL-GMS Function Reference 258 Model — user header string DESCRIPTION The gmsMUserHeaderStr( ) function sets the user header string for a model 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 Vars strings except only string data is allowed with each label. The gmsMUserHeaderStr( ) function automatically prefixes the label for each item in the supplied string with "user_". When editing the user header string in a ".g" file directly, the "user_" prefix must be included as part of the label name for user defined items. Items defined by SL-GMS will not have this prefix. The gmsQMUserHeaderStr( ) function returns a user header string from the Model specified in memory. The "user_" prefix that gmsMUserHeaderStr( ) adds to item labels is removed by gmsQMUserHeaderStr( ). The string returned by this function must be freed by using g_strfree( ) when the program is finished with the string. The gmsMGetUserHeaderStr( ) function reads the user header string from a Model file without loading the Model in memory and returns a user header string. Use g_strfree( ) to free the string when done. The "user_" label prefix for each label is removed by this function also. EXAMPLE An example Model using the modelheader command would be as follows: mtran0 vis 1 detect 1 test: model . modelheader \ user_format :: "%d A" \ user_label :: "\t Amps " \ user_highlimit :: " 200 " \ user_highdanger :: "19\b" \ Version 6.2a- 26 May 2006 SL-GMS Function Reference 259 Model — user header string user_extent :: "20 20 100 100 " \ user_lowlimit :: "0" \ user_m :: "b1" fcolor 4 fstyle 1 finter 1 fdir 0 fpercent 100 ecolor 7 estyle 1 ewidth 1 _circ: cir2 10 10 20 10 endm SL-GML COMMANDS [name:] modelheader string Version 6.2a- 26 May 2006 SL-GMS Function Reference 260 Model Instance (ModInst) object Model Instance (ModInst) object SUMMARY create a Model Instance object, set SubModel Replicate Mode, set SubModel 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 SubModel and SubModel name, prevent unused SubModels from being automatically freed, query SubModel permanent flag NAME gmsModInst( ), gmsModInst2( ), gmsSubModReplicateMode( ), gmsModNonReplicate( ), gmsQSubModReplicateMode( ), gmsQModNonReplicate( ), gmsInsExplode( ), gmsSubModelName( ), gmsQSubModel( ), gmsQSubModelName( ), gmsModPermanent( ), gmsQModPermanent( ) SYNTAX id gmsModInst (name, modelname, point) char *name; char *modelname; idPoint point; id gmsModInst2 (name, modelname, point) char *name; char *modelname; idPoint point; int gmsSubModReplicateMode(mode) int mode; /* 0 = never replicate 1 = replicate all Instances 2 = replicate only Instances with Renamed Variables */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 261 Model Instance (ModInst) object int gmsModNonReplicate (model, action) id model; int action; /* G_ON or G_OFF */ int gmsQSubModReplicateMode( ) int gmsQModNonReplicate (model) id model; idLinkRef gmsInsExplode (inst) id inst; int gmsSubModelName (inst, modelname, m2flag) id inst; char *modelname; int m2flag; /* G_ON or G_OFF */ id gmsQSubModel(inst) id inst; /* Instance to query */ char * gmsQSubModelName(inst) id inst; /* Instance to query */ int gmsModPermanent (model, action) id model; int action; /* G_ON or G_OFF */ int gmsQModPermanent (model) id model; Version 6.2a- 26 May 2006 SL-GMS Function Reference 262 Model Instance (ModInst) object DESCRIPTION The gmsModInst( ) function is used to create a Model Instance object given the name of the Model to instance. The list of local SubModels in the current Model is searched first, followed by the List of external Models. If the named Model is found in one of these Lists, an Instance is created which references it. If the named Model is not found, an attempt is made to look in the current directory and all directories specified by the list of library paths for a Model file by that name (terminated by a ".m1" extension). If found, the Model is read and entered into the External SubModels List and an Instance is created which references it. The name argument is optional and is the name assigned to the object when it is added to the current Model. The position of the Instance is affected by the current transformation matrix. The gmsModInst2( ) function uses the "m2" filer to create a Model Instance, searching first for a ".m2" file and then for a ".m1" file in each directory in the search path. This function is complementary to the existing gmsM2Get( ), gmsM2Save( ), gmsM2Merge( ), and gmsM2XGet( ) functions. SubModels are often replicated by Model Instances which reference them. If each Model Instance does not have a unique replicate of the template SubModel, modifications to the appearance of the SubModel by one Model Instance will affect the appearance of all other Model Instances referencing that SubModel. Version 6.2a- 26 May 2006 SL-GMS Function Reference 263 Model Instance (ModInst) object 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: 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 NOTE: G_REPLICATE_ALWAYS is the default. The primary use of the gmsSubModReplicateMode( ) function is to permit loading of external SubModels using the function gmsMXGet( ), while the SubModel Replicate Mode is G_NO_REPLICATE — no SubModels pointed to by Instances in the external Models loaded this way are replicated. After loading external SubModels in this way, the SubModel Replicate Mode can be restored to G_REPLICATE_IF_RENVARS, the default, so that when top-level Models are loaded, Instances contained within will be replicated as usual. The gmsModNonReplicate( ) function sets or clears the non-replication flag on a SubModel. By default, this flag is not set on a SubModel when it is created. When the flag is not set on a SubModel, the SubModel's replication behavior is defined by the global flag set by the gmsSubModReplicateMode( ) function. When the non-replication flag is set on a SubModel, the global flag is overridden and the SubModel is not replicated by a Model Instance. Version 6.2a- 26 May 2006 SL-GMS Function Reference 264 Model Instance (ModInst) object Usually, the non-replication flag is set only on SubModels having no animation or dynamics. Since the SubModel is never modified, Model Instances referencing that SubModel do not conflict with one another. Non-replicated SubModels can be used with dynamics in limited circumstances. Further information about these limitations is provided in the SL-GMS Reference Manual. The non-replication flag must be set at run time. In order to set the non-replication flag at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ). To gain full control over the replication behavior of SubModels, the application 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 current setting of the SubModel Replicate Mode. The gmsQModNonReplicate( ) function returns the current status of the non-replication flag on a SubModel. The gmsInsExplode( ) function replaces an Instance of a SubModel with a copy of that SubModel’s part List, with the Point List transformed so that the parts remain in the same position. The List of the copied parts is added to the current Model and also returned to the calling function. A Model must be current or this function fails. The gmsSubModelName( ) function modifies the SubModel reference of the given Model Instance. The gmsSubModelName( ) function is used in applications displaying Model Instances which have SubModel references that must remain undefined until run time. Since every Model Instance must have some SubModel reference, a dummy SubModel reference is assigned to such Model Instances before run time. At run time, the application calls gmsSubModelName( ) on Version 6.2a- 26 May 2006 SL-GMS Function Reference 265 Model Instance (ModInst) object Model Instances referencing the dummy SubModel, changing their SubModel reference to the appropriate SubModel. Model Instances used in this way are sometimes referred to as "placeholders." The modelname parameter specifies the name of the SubModel. The Model Instance will reference the SubModel with this name if it can be found in memory or on disk. A description of the searching algorithm used to find the SubModel is provided in the description of the gmsModInst( ) function on page -263. If the m2flag parameter is set to G_ON, and the SubModel cannot be found in memory, gmsSubModelName( ) first attempts to read in the SubModel from a file with a ".m2" extension. If such a file cannot be found, gmsSubModelName( ) attempts to read in the SubModel from a file with a ".m1" extension. Setting the m2flag parameter to G_OFF prevents gmsSubModelName( ) from attempting to read in the SubModel from a file with a ".m2" extension. To illustrate the use of gmsSubModelName( ), suppose the top-level Model topmodel1 is loaded: id topmodel1; topmodel1 = gmsMGet("topmodel1", "topmodel1"); This top-level Model contains two placeholder Model Instances which reference the SubModel dummy. Before run time, the correct SubModel reference for these placeholders was unknown. At run time, this information is available, hence the application must find the placeholder Model Instances and correct their SubModel references. In this case, both placeholders referencing dummy will be modified to reference correct_submodel: id LinkRef parts_list; id part; char *submod_name; parts_list = gmsQPartList(topmodel1); while (parts_list) { part = refQReference(parts_list); Version 6.2a- 26 May 2006 SL-GMS Function Reference 266 Model Instance (ModInst) object 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 a Model Instance refers. The gmsQSubModelName( ) function returns the name of the SubModel to which a Model Instance refers. The gmsModPermanent( ) function is used to set or clear the permanent flag on a Model. By default, this flag is not set on a Model when it is created. The permanent flag affects only the behavior of Models which are SubModels. When the permanent flag is not set, a SubModel is freed when the last Model Instance referencing that SubModel is freed. This is done to prevent accumulation of SubModels in memory. If the permanent flag is set on a SubModel, the SubModel can be freed only by explicitly calling gmsObjFree( ). The SubModel is not automatically freed when the last Model Instance referencing that SubModel is freed. Setting the permanent flag on a SubModel may improve performance. When the last Model Instance referencing a given SubModel is freed, that SubModel is freed. If another Model Instance is loaded or created and it references the same SubModel (by name), the SubModel must be reloaded from disk. When the permanent flag is 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 instanced in several top-level Models. This can decrease the amount of time needed to load a top-level Model because the SubModel will already be in memory. The permanent flag must be set on a SubModel containing a SubModel replicate cache to prevent the SubModel and cache from being freed Version 6.2a- 26 May 2006 SL-GMS Function Reference 267 Model Instance (ModInst) object when the last Model Instance referencing that SubModel is freed. Further information about SubModel replicate caches is provided in the section Model Instance (ModInst) — caching on page 269. Currently, the status of the permanent flag on a SubModel cannot be saved in a ".m1" or ".g" file. This means that the permanent flag must be set at run time. In order to set the permanent flag at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ). Individual SubModels are pre-loaded: id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1"); Selected SubModels are then marked "permanent": gmsModPermanent(submodel1, G_ON); The gmsQModPermanent( ) function returns the current status of a Model’s permanent flag. SEE ALSO gmsModel( ), 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 268 Model Instance (ModInst) — caching Model Instance (ModInst) — caching SUMMARY create SubModel cache, query size of SubModel cache NAME gmsModCacheCapacity( ), gmsModCacheCount( ), gmsQModCacheCount( ), gmsQModCacheCapacity( ) SYNTAX int gmsModCacheCapacity (submodel, capacity) id submodel; int capacity; int gmsModCacheCount (submodel, count) id submodel; int count; int gmsQModCacheCount (submodel) id submodel; int gmsQModCacheCapacity (submodel) id submodel; DESCRIPTION The gmsModCacheCapacity( ) function either creates a SubModel cache for the given SubModel or modifies the capacity of the existing SubModel cache associated with the given SubModel. The capacity of a SubModel cache is the maximum number of SubModel replicates which can be stored in the SubModel cache. If the given capacity is 0, gmsModCacheCapacity( ) will free the cache associated with the given SubModel. If the given capacity is greater Version 6.2a- 26 May 2006 SL-GMS Function Reference 269 Model Instance (ModInst) — caching than 0, gmsModCacheCapacity( ) will create a cache for the given SubModel (if one does not exist), and adjust the cache capacity. A SubModel cache enables Model Instances to reuse SubModel replicates, instead of creating and freeing them every time a Model Instance is created or freed. An active SubModel replicate is defined as one which is currently referenced by a Model Instance. An inactive SubModel replicate is not currently referenced by a Model Instance. Only inactive SubModel replicates can be stored in a SubModel cache. Active SubModel replicates have the potential to be stored in a SubModel cache when they are made inactive. When an active SubModel replicate is made inactive, an attempt is made to store it in the appropriate SubModel cache. If this is not possible, either because the cache does not exist or the cache has reached its storage capacity, the replicate will be freed. The gmsModCacheCapacity( ) function does not create any SubModel replicates to store in a SubModel cache. SubModel replicates are automatically created when a Model Instance is created or loaded from disk and an inactive SubModel replicate cannot be found in the appropriate SubModel cache (each Model Instance requires a unique replicate). SubModel replicates can also be created by using the gmsModCacheCount( ) function. When the capacity of a SubModel cache is reduced using gmsModCacheCapacity( ), it may be necessary to free inactive SubModel replicates in the SubModel cache. For any SubModel, the number of SubModel replicates in memory may exceed the capacity of the associated SubModel cache. The SubModel cache capacity limits only the number of replicates which can be reused. The gmsModCacheCount( ) function increases the count of the SubModel cache associated with the given SubModel if the given count is greater than the current cache count and the current cache count is less than the cache capacity. The count is the sum of the number of inactive SubModel replicates stored in the cache and the number of existing active SubModel replicates which have the potential to be stored in the cache. Version 6.2a- 26 May 2006 SL-GMS Function Reference 270 Model Instance (ModInst) — caching When a SubModel cache is created, its count is 0. The count of a SubModel cache automatically increases as more SubModel replicates are created by Model Instances, until the cache count equals the cache capacity. The SubModel cache count can never exceed the cache capacity. When gmsModCacheCount( ) is used to explicitly increase the count of a SubModel cache, new inactive SubModel replicates are created and 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 gmsModCacheCount( ) does nothing. cache, The gmsQModCacheCount( ) function returns the count of the SubModel cache associated with the given SubModel. The count is the sum of the number of inactive SubModel replicates stored in the cache and the number of active SubModel replicates which have the potential to be stored in the cache. Only inactive SubModel replicates are stored in the cache. The count of a SubModel cache can never exceed the cache capacity. The gmsQModCacheCapacity( ) function returns the capacity of the SubModel cache associated with the given SubModel. The capacity of a SubModel cache is the maximum number of SubModel replicates which can be stored in the cache. A SubModel with no cache has a cache capacity of 0. EXAMPLE Using a SubModel cache can improve the performance of an application which repeatedly creates and frees several Model Instances which refer to the same SubModel. The overhead required to replicate the SubModel and free the replicates is reduced. However, the application may consume more memory, since the replicates are no longer 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( ): Version 6.2a- 26 May 2006 SL-GMS Function Reference 271 Model Instance (ModInst) — caching id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1"); A SubModel cache is automatically destroyed when the original SubModel (the template for the replicates) is freed. The gmsModPermanent( ) function must be used to prevent submodel1 from being automatically freed when the last Model Instance referencing submodel1 is freed: gmsModPermanent(submodel1, G_ON); The gmsModCacheCapacity( ) function is then called to set the capacity of the SubModel cache to a number smaller than or equal to the maximum number of replicates predicted to exist in memory. This number can be determined by computing or estimating the number of Model Instances which will be referencing submodel1 at the same time. The closer the cache capacity is to the actual number of replicates which will exist in memory, the greater the optimization. In this example, it has been determined that no more than 100 Model Instances will reference submodel1 at the same time: gmsModCacheCapacity(submodel1, 100); SubModel replication can be either batched or incremental. To batch SubModel replication, gmsModCacheCount( ) is called immediately after the gmsModCacheCapacity( ) call. This call will create 100 replicates of submodel1 and store them in the cache: gmsModCacheCount(submodel1, 100); To perform incremental SubModel replication, the application omits the gmsModCacheCount( ) call. As Model Instances referencing submodel1 are created or loaded from disk, replicates of submodel1 are created. The count of the SubModel cache will increase, but will never exceed the capacity. If the number of replicates needed is less than the capacity, the count will remain smaller than the capacity. SEE ALSO gmsModPermanent( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 272 NDC (Normalized Device Coordinates) NDC (Normalized Device Coordinates) SUMMARY create or set points with Normalized Device Coordinates; set NDC scaling factor NAME gmsNPXY( ), gmsSNPXY( ), gmsNDCScale( ) SYNTAX idPoint gmsNPXY (x, y) double x; double y; idPoint gmsSNPXY (point, x, y) idPoint point; double x; double y; int gmsNDCScale (scale) double scale; DESCRIPTION These functions are used to create and set values for Points using Normalized Device Coordinates (NDC). NDC Points are used in SL-GMS to set the Viewport limits associated with View objects. The Viewport specifies the region of a device screen on which the View is to be drawn. In order to achieve device independence, these coordinates are normalized, that is, specified in the range (0.0,0.0) to (1.0,1.0). These NDC values are adjusted internally to the particular coordinate system for the device, usually pixels. Version 6.2a- 26 May 2006 SL-GMS Function Reference 273 NDC (Normalized Device Coordinates) The gmsNPXY( ) function is used only to create Points to be used as arguments to the gmsPort( ) function, which sets the Viewport for a particular View object. All NDC points created by SL-GML commands are created using the gmsNPXY( ) function. Once a Point is created, its x and y values can be set using gmsSNPXY( ), rather than creating another Point. Points created using these functions may be freed using the pntFree( ) function. The gmsNDCScale( ) function sets the NDC scaling factor. DIAGNOSTICS Presently, the internal representation for NDC coordinates is as integers. The internal representation for NDC coordinates cannot be set by SL-GMS users. SEE ALSO gmsPort( ), pnt*( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 274 Object — name Object — name SUMMARY Set, return an object’s name, or remove an object’s name NAME gmsObjNameStr( ), gmsQObjNameStr( ) SYNTAX int gmsObjNameStr (obj, str) id obj; char *str; char * gmsQObjNameStr (obj) id obj; DESCRIPTION The gmsObjNameStr( ) function sets an object’s name to the given string. If the string is a null string, the name is removed from the object. The gmsQObjNameStr( ) function returns an object’s name for the given object. A pointer to the real (not a copy) name of the object is returned. If a nil pointer is given, the null string is returned. If no name is found, a null string is returned. SEE ALSO gmsFindByName( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 275 Object — owner Object — owner SUMMARY functions to query an object’s owner List NAME gmsQOwner( ), gmsQOwnerList( ), gmsQOwnerView( ), gmsQOwnerModel( ), gmsQOwnerState( ) SYNTAX id gmsQOwner (obj) id obj; idLinkRef gmsQOwnerList (obj) id obj; id gmsQOwnerView (obj) id obj; id gmsQOwnerModel (obj) id obj; id gmsQOwnerState (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 276 Object — owner DESCRIPTION The 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 the object. The gmsQOwnerModel( ) function returns the first Model that owns the object. The gmsQOwnerState( ) function returns the State that contains the Model that owns the specified object. The object can be a Model itself. The specified object may be nested to an unlimited number of levels within a SubModel. If the Model containing the object has not been attached to a State using gmsStAddModelName( ), the function returns 0. If a Model is referred to by multiple States, the lowest-level State that refers to the Model is returned. Version 6.2a- 26 May 2006 SL-GMS Function Reference 277 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 particular GraphTrace NAME gmsQPartList( ), gmsQNumParts( ), gmsQNumTraces( ), gmsQTraceNum( ) gmsQPartNum( ), SYNTAX idLinkRef gmsQPartList (obj) id obj; int gmsQNumParts (obj) id obj; id gmsQPartNum (obj, n) id obj; int n; int gmsQNumTraces (model) id model; id gmsQTraceNum (model, tracenum) id model; int tracenum; Version 6.2a- 26 May 2006 SL-GMS Function Reference 278 Object — parts DESCRIPTION The gmsQPartList( ) function returns an object’s part List. This function operates on Models, Model Instances, or Group objects, all of which 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, it returns a List of the parts in a SubModel. If there are dynamic descriptions in the SubModel, or the SubModel Replicate Mode is set to G_ON, each Model instanced is a unique copy of the SubModel with parts that can be modified independently of other Model Instances. EXAMPLE The short program that follows shows gmsQPartList( ) descending through the part List of a Model and all of the subparts of Groups and Model Instances. #include "gms.h" main( ) { id model; gmsSetup( ); model = gmsMGet("test", "test"); loop_over_parts(model); gmsClose( ); } int loop_over_parts (object) id object; { idLinkRef parts, ptr, subparts; id part; (program continued on next page) Version 6.2a- 26 May 2006 SL-GMS Function Reference 279 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( ) function must be recursive because some parts, such as Groups and Model Instances, have part Lists as well. The gmsQNumParts( ) function returns the number of parts in a part List. The gmsQPartNum( ) function returns the part at the given index into the object’s part List. These functions operate on the same type of objects as gmsQPartList( ). The gmsQNumTraces( ) function returns the number of GraphTrace objects in a Model. The gmsQTraceNum( ) function returns a pointer to a particular GraphTrace. DIAGNOSTICS The part List returned is the actual part List from the object. Care should be taken not to inadvertently modify or destroy this List. The object that owns the parts may be corrupted. SEE ALSO gmsObjIsClass( ), gmsDump( ), refQSuccessor( ), refQReference( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 280 Performance optimization Performance optimization SUMMARY set the time_level flag NAME gmsTimeLevel( ) SYNTAX int gmsTimeLevel (level) int level; DESCRIPTION The gmsTimeLevel( ) function sets the time_level flag. This flag is 0 by default. Setting the flag to 1 displays the time duration spent during each system update. (System updating involves preparing objects for display.) The message time: total time for gmsRedCode( ) indicates the amount of time spent clearing flags and updating. To obtain more detailed reports, the level is set to 2. These times give some indication of system performance and vary with Views containing Models with more or less complexity. SEE ALSO The chapter entitled in the SL-GMS Reference SL-GML COMMANDS time etime Version 6.2a- 26 May 2006 SL-GMS Function Reference 281 Pie object Pie object SUMMARY create a Pie object NAME gmsPie( ), gmsPie2( ), gmsFPie( ), gmsFPie2( ) SYNTAX id gmsPie (name, center, radius, start, length) char *name idPoint center; double radius; double start; double length; id gmsPie2 (name, points) char *name; idLinkRef points; id gmsFPie (name, center, radius, start, length) char *name idPoint center; double radius; double start; double length; id gmsFPie2 (name, points) char *name; idLinkRef points; Version 6.2a- 26 May 2006 SL-GMS Function Reference 282 Pie object DESCRIPTION The gmsPie( ) function is used to create a Pie object given a center Point, radius, start angle, and arc length. The Pie object is created with the current attributes. The radius is in World Coordinates and is multiplied by the World Coordinate Scale factor. Angles and arc length are in degrees and sectors are always drawn counterclockwise. The gmsPie2( ) function creates a Pie object given a center Point and two Points which are on the radius. The Points must be passed in a Point List. The second Point on the arc (the third in the List) will be adjusted to be on the radius if it is not already. The gmsFPie( ) and gmsFPie2( ) functions are used in the same manner as their counterparts without the "F", but the Pie objects produced are filled. The name argument is optional and is the name that is assigned to the object when it is added to the current Model. The current edge attributes are applied to the object when it is created. SEE ALSO gmsCWFlag( ) 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 283 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 int gmsPlotData (obj, xdata, ydata) id obj; double xdata; double ydata; int gmsPlotDataX (obj, xdata) id obj; double xdata; int gmsPlotDataY (obj, ydata) id obj; double ydata; int gmsPlotClear (obj) id obj; int gmsPlotReset (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 284 Plotted Points int gmsPlotShiftX (obj, shiftval) id obj; double shiftval; int gmsPlotShiftY (obj, shiftval) id obj; double shiftval; DESCRIPTION These functions plot, clear, reset, or shift plotted Points of GraphTrace objects. The gmsPlotData( ) function plots a single Point of a GraphTrace object using the template Line or Marker style and attributes. The position of the plotted Point is determined by where the x 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 region defined by the coordlimits. The gmsPlotDataX( ) and gmsPlotDataY( ) functions receive the coordinates to plot one at a time, but do nothing until both an x and a y coordinate are received. The x coordinate must be sent before the y coordinate. The gmsPlotClear( ) function clears the region defined by the coordlimits for the GraphTrace. This action erases everything within this region, including other GraphTraces, tick marks, and other graphical objects. The gmsPlotReset( ) function erases the GraphTrace and clears its Point List. The gmsPlotShiftX( ) and gmsPlotShiftY( ) functions add the shiftval to all the x or y coordinates currently in the GraphTrace object’s Point List. 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 or negative y shift values). These actions are useful when implementing trend Graphs. Version 6.2a- 26 May 2006 SL-GMS Function Reference 285 Plotted Points SEE ALSO gmsGraphAxis( ), gmsXValueLimits( ) gmsCoordLimits( ), gmsGraphTrace( ), The chapter entitled in the SL-GMS Reference SL-GML COMMANDS name 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 286 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 idLinkRef gmsLQPointList (objlist) idLinkRef objlist; idLinkRef gmsLQXPointList (objlist) idLinkRef objlist; idLinkRef gmsQPartPointList (topobj, subobj) id topobj; id subobj; idLinkRef gmsQPointList (obj) id obj; idLinkRef gmsQXPointList (obj) id obj; int gmsLPFndPt (ptlist, point) idLinkRef ptlist; idPoint point; Version 6.2a- 26 May 2006 SL-GMS Function Reference 287 Point Lists DESCRIPTION The gmsLQPointList( ) function returns a Point List containing Points of all objects in the List. Any transformation matrix attached to an object is applied to the Points before they are added to the returned Point List. The gmsQPartPointList( ) function returns a List of the sub-object’s Points relative to the given top object. The top object could be a Model Instance or a Group with its own transformation matrix that affects the sub-objects. This function applies the top object’s transformations (and the sub-object’s transformations) to the sub-object’s Points before returning the Point List. The gmsQPointList( ) function returns a pointer to an object’s Point List, which is a linked List of Point objects. The Point List, or a Point in the List, may be used to create other objects that are connected to the object, or by other functions that require Point Lists. The gmsLPFndPt( ) function may also be used to find the Point closest to a Point in the Point List. The extended Point List contains additional Points beyond those used to define Circle or Rectangle objects. These Points are the center of the 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 Point Lists. It is the programmer’s responsibility to free the LinkRef object returned by these functions when finished using the Point List by using refKilAll( ). The gmsLPFndPt( ) function returns an index into the given Point List to a Point that is closest to the given Point. If two Points in the Point List are exactly equidistant to the given Point, the index to the first Point found is returned. If no Points are found, -1 is returned (bad Point or Point List arguments). EXAMPLE id rect = gmsRect(nil, pointA, pointB); idLinkRef ptlist = gmsQPointList(rect); Version 6.2a- 26 May 2006 SL-GMS Function Reference 288 Point Lists gmsDump (ptlist); refKilAll (ptlist); ptlist = 0; SEE ALSO refKilAll( ) SL-GML COMMANDS name points name xpoints Version 6.2a- 26 May 2006 SL-GMS Function Reference 289 Point Lists — replace Point Lists — replace SUMMARY replace an object’s Point List; apply objects’ transformations on the Point List argument, then replace the sub-object’s Point List; reverse order of a Point List NAME gmsPoints( ), gmsLPoints( ), gmsPartRpPs( ), gmsRvrsPts( ) SYNTAX int gmsPoints (obj, points) id obj; idLinkRef points; int gmsLPoints (objlist, points) idLinkRef objlist; idLinkRef points; int gmsPartRpPs (topobj, subobj, points) id topobj; id subobj; idLinkRef points; idLinkRef gmsRvrsPts (points) idLinkRef points; Version 6.2a- 26 May 2006 SL-GMS Function Reference 290 Point Lists — replace DESCRIPTION The gmsPoints( ) function replaces an object’s Point List with the Point List specified in the points argument. The Point List must contain the correct number of Points to define the object, that is, two Points for a Rectangle, at least two Points for a Polyline, and so on. Essentially, the gmsPoints( ) function allows the user to move and/or transform an object without creating a transformation object or recreating the object. The gmsLPoints( ) function performs the gmsPoints( ) functionality upon each object in the List specified as the first argument. The gmsPartRpPs( ) function is used to change the Point List of an object that is a sub-object. Sub-objects are affected by the transformation applied to their top objects. For example, a transformation applied to a Group applies to the Points of the sub-objects in the Group, and the sub-objects may also have individual transformation matrices. The gmsPartRpPs( ) function takes into account all the transformations matrices, starting at the top object and ending at the sub-object, to the Points in the Point List before replacing the sub-object’s Point List. Thus, an untransformed Point List is modified correctly before replacing a 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 Point List is returned. SEE ALSO gmsGroup( ), gmsQPointList( ) The chapter entitled Object Attributes in the SL-GMS Quick Reference for the number of Points to define an object Version 6.2a- 26 May 2006 SL-GMS Function Reference 291 Point object Point object SUMMARY functions and object definition for Point class NAME pntNew( ), pntNewXY( ), pntSetXY( ), pntFree( ), pntClone( ), pntX( ), pntY( ) SYNTAX idPoint pntNew( ); idPoint pntNewXY (x, y) coordVar x, y; int pntSetXY (point, x, y) idPoint point; coordVar x, y; int pntFree (point) idPoint point; idPoint pntClone (point) idPoint point; coordVar pntX (point) idPoint point; coordVar pntY (point) idPoint point; Version 6.2a- 26 May 2006 SL-GMS Function Reference 292 Point object DESCRIPTION This section describes the Point class, an object containing a pointer to the class of the object (Point), and x and y coordinates. The type coordVar 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 using the pntSetXY( ) function. The World Coordinate Scale Factor is not used when Points are made with the pnt*( ) functions. It is usually preferable to use the higher level point-creation routines, such as gmsWPXY( ), which automatically converts World Coordinate values to the correct internal representation (by multiplying them by the World Coordinate 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 finished with a Point object, for example, after using it in a function call, it can be freed (returned to the "pool") with the pntFree( ) function call. As shown in the example below, the pointer to any object should always be set to null immediately after freeing the object. The pntX( ) function returns the integer x coordinate of the Point passed to it, and the pntY( ) function returns the integer y coordinate of the Point passed to it. Version 6.2a- 26 May 2006 SL-GMS Function Reference 293 Point object EXAMPLE The two Point creation functions below create identical Point objects. In general it is preferable to use the gmsWP*( ) functions since they automatically convert World Coordinate values to Internal Coordinates. In the example below, the gmsWValue( ) function is used to convert WC 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 “zero the pointer” */ pointA = 0; /* create an identical Point using the gmsWPXY( ) function */ pointA = gmsWPXY(10.0, 20.0); A second Point can be created with the identical coordinates with the pntclone( ) function: idPoint pointB; pointB = pntClone(pointA); Now there are two Point objects with the same coordinates. A Point object can be re-used by resetting its coordinates with the pntSetXY( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 294 Point object SEE ALSO SL-GMF uses four functions for creating Point objects. The gmsNPXY( ) function is used solely for creating arguments used with the gmsPort( ) function. The pntNew( ) function creates Points with integer arguments that are not scaled. The gmsWPoint( ) function creates a World Coordinate System Point object with the coordinates set to the origin (0,0). The gmsWPXY( ) function also creates a World Coordinate 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 a pointer to itself. The pnt*( ) functions should be used for manipulating or freeing Point objects. The gmsWP*( ) functions are a convenience provided for scaling the coordinates choosen. SL-GMSDraw, and SL-GML use the gmsWPXY( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 295 Polygon object Polygon object SUMMARY create a Polygon object NAME gmsPolygon( ), gmsFPolygon( ) SYNTAX id gmsPolygon (name, points) char *name; idLinkRef points; id gmsFPolygon (name, points) char *name; idLinkRef points; DESCRIPTION The gmsPolygon( ) function creates a Polygon object by connecting the given List of Points with Lines. The refNew( ) function is used to create Lists of objects. The first and last Points in the List are connected by a Line, thus the function always creates Closed Polygons. The Polygon object created possesses the current attributes. The gmsFPolygon( ) function creates Filled Polygons in the same manner. The name argument is optional and is the name assigned to the object when it is added to the current Model. The current edge attributes are applied to the object when it is created. Version 6.2a- 26 May 2006 SL-GMS Function Reference 296 Polygon object SL-GML COMMANDS [name:] poly x y x y ... [name:] fpoly x y x y ... SEE ALSO refNew( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 297 PostScript PostScript SUMMARY create PostScript files and set PostScript parameters NAME gmsPsSetParams( ), gmsPsWsProcArgs( ), gmsPsWsProcArgsStr( ), gmsPsPolyMaxPoints( ), gmsPsViewWrite( ), gmsPsLViewWrite( ) SYNTAX int gmsPsSetParams(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*/ int gmsPsWsProcArgs(argc, argv) int argc; /* main( ) argument count */ char *argv[]; /* main( ) arguments */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 298 PostScript int gmsPsWsProcArgsStr(argstr) char *argstr; /* string containing main( ) arguments separated by spaces*/ int gmsPsPolyMaxPoints (max_points) int max_points; /* 2 <= max_points <= GMS_MAX_POINTS */ int gmsPsViewWrite(workst, view, name); id workst; /* id of a PostScript Workstation */ id view; /* id of a View object */ char *name; /* name of PostScript output file */ int gmsPsLViewWrite(workst, viewlist, name); id workst; /* id of a PostScript Workstation */ id viewlist; /* id of a View List */ char *name; /* name of PostScript output file */ DESCRIPTION The gmsPsSetParams( ) function sets the PostScript Workstation parameters. The parameters for the gmsPsSetParams( ) function and their default values in SL-GMS are as follows: ps_dcmax_x Maximum x value in Device Coordinates Default value: 7200 ps_dcmax_y Maximum y value in Device Coordinates Default value: dcmax_x * 3/4. ps_off_x x offset from 0 in Device Coordinates Default value: 0 ps_off_y y offset from 0 in Device Coordinates Default value: 0 Version 6.2a- 26 May 2006 SL-GMS Function Reference 299 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 as a fudge for clipping. Default value: 2 ps_flags options are described in the table 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 the ps_flags: Bit options for "psflags" bit 0x1 0x2 0x4 0x10 0x20 0x40 0x100 0x200 0x400 0x1000 Description supply header for FrameMaker omit clipping output several views to one file use portrait mode add initgraphics to output file do not include view in bounding box add thin black border line at max x and y use solid lines for line width < 1.0 reverse black/white add extra fudge factor to clip rectangles For example, to set the ps_flags to add a black border and to output multiple views: int ps_flags = 0; ps_flags |= 0x4; ps_flags |= 0x100; Version 6.2a- 26 May 2006 SL-GMS Function Reference 300 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 set x offset -py set y offset -ps set scaling factor to n/100 where n is percent -pr 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 supply as comment in PostScript file -pf supply heading for FrameMaker -pf set the ps_flags option fields; N is an integer representing any one of the option bits listed under "ps_flags" of gmsPsSetParams( ) -pp set coordinate range of one pixel -pw set maximum dc x coordinate -ph 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 301 PostScript The default is landscape orientation, offset and scaled to fit page size 8.5 x 11". The same arguments1 can be given when printing a file from SL-GMSDraw using the PostScript option of the System Pull-Down Menu or from SL-Draw using the Print option of the System Pull-Down Menu. The SL-GMS® Reference describes the process used to produce a PostScript file from SL-GMSDraw. The SL-GMS®Draw User’s Guide describes the process used to produce a PostScript file from SL-GMS Draw. The gmsPsWsProcArgs( ) function should be called before opening the PostScript Workstation. For non-C programming languages, or situations where the arc-argv mechanism is inconvenient or simply unavailable, the gmsPsWsProcArgsStr(argstr) function can be used instead of gmsPsWsProcArgs( ). argstr is of type char *, where the character string contains space-separated arguments. Quotes attempting to combine words into one argument are not accounted for. For example, the following two calls result in the same print output to a PostScript file with -op, -c, and -s options. gmsPsWsProcArgsStr("-pop -pctest_print -ps50") is the same as gmsPsWsProcArgs(argc, argv) with: argc = 3 argv[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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 302 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 inform SL-GMS that a printer’s upper limit for the number of points in a polyline is 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 using gmsPsPolyMaxPoints( ), the call must be made before gmsPsViewWrite( ), or gmsPsLViewWrite( ) is called. The gmsPsViewWrite( ) function writes a View to a PostScript file while the gmsPsLViewWrite( ) function outputs a list of Views to a single PostScript file. For the gmsPsLViewWrite( ) function the first argument, workst, is the id of a PostScript Workstation. The second argument, view, is the View to be output; viewlist is the List of Views to be output. The third Version 6.2a- 26 May 2006 SL-GMS Function Reference 303 PostScript argument, name, is an ASCII string which is used as the output file name. The size of the PostScript image is determined by the size of the Viewport. A Viewport size of (0.0, 0.0) (1.0, 0.75) renders a PostScript image that fits on a 8.5 x 11 inch page (in landscape orientation). If a different size Viewport is used, it should be changed to (0.0, 0.0) (1.0, 0.75) using gmsPortXY( ), before calling the gmsPsViewWrite( ) or gmsPsLViewWrite( ) functions. It should be noted that image size is also affected by the scaling parameter, which is included in the description of gmsPsWsProcArgs( ). NOTE: In version 4.0, rotation is performed around the Point (0,0), so it may be necessary to move the PostScript image after it has been rotated. If name does not contain a dot, SL-GMS appends ".ps" to the name of the file. If the name parameter is null, the file name ".ps" is used, where is a sequentially increasing integer. NOTE: In version 4.0 the workst argument is ignored; it is reserved for later use when multiple PostScript Workstations may be provided. For now, 0 must be used for the workst argument. To be able to use the gmsPsLViewWrite( ) function successfully, the user must set the 0x4 bit of ps_flags using gmsPsSetParams( ) or passing the option -pa or -pf0x4 to gmsPsWsProcArgs( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 304 PostScript For example, the following code fragment could be used to print a PostScript 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 ALSO gmsPortXY( ), gmsQEvWorkst( ), gmsQGismoEvent( ) Print and Postscript in the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 305 Projects Projects SUMMARY initialize, get, save, or merge a Project NAME gmsProject( ), gmsPGet( ), gmsPSave( ), gmsPMerge( ) SYNTAX int gmsProject( ) int gmsPGet (name) char *name; int gmsPSave (name) char *name; int gmsPMerge (name) char *name; DESCRIPTION While the gmsProject( ) function is automatically invoked when starting SL-GML, it is not required for use of other SL-GMS functions. Anytime it is desired to start an application "from scratch," the gmsProject( ) function clears out all Models and Views and resets all modal attributes and transformations to their defaults. The gmsPGet( ) function is used to get a Project which had been saved using the gmsPSave( ) function. Saving a Project creates a file with a ".p1" extension, and includes the status of the entire system, including modal attribute settings and modal transformations, all Views, and all Models. The Workstation/Window information is not saved in a Version 6.2a- 26 May 2006 SL-GMS Function Reference 306 Projects Project, and calling Workstation/Window. gmsPGet( ) does not close the current The gmsPMerge( ) function is used to read a Project from a file and merge its Models and Views with the existing Project. Modal attributes and transformations are replaced by those of the merged Project. SL-GML COMMANDS project project get name project save name project merge name Version 6.2a- 26 May 2006 SL-GMS Function Reference 307 Query user Query user SUMMARY query for a string, or a yes/no response from user NAME gmsAskLine( ), gmsQuery( ) SYNTAX int gmsAskLine (prompt, namebuff, buffsize) char *prompt; char *namebuff; int buffsize; int gmsQuery (prompt) char *prompt; DESCRIPTION These two functions query the SL-GMS user for a response. The gmsAskLine( ) function copies the user’s response into the area pointed to by namebuf. If prompt is nil, the string Enter: is used as a prompt, otherwise the null-terminated string pointed to by prompt is used. The application program supplies the buffer namebuf. 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 by prompt is used. When using SL-SMS, the preferred method of text entry is through use of either the TEXTENTRY ARRAY or TEXTENTRY VAR GISMOs. Version 6.2a- 26 May 2006 SL-GMS Function Reference 308 Query user SEE ALSO gmsStTextEditObj( ), gmsWsTextEditObj( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 309 Radius set and get Radius set and get SUMMARY set or get the radius of some objects NAME gmsRadius( ), gmsLRadius( ), gmsQRadius( ) SYNTAX int gmsRadius (obj, radius) id obj; double radius; int gmsLRadius (objlist, radius) idLinkRef objlist; double radius; double gmsQRadius (obj) id obj; DESCRIPTION The gmsRadius( ) function sets the radius for objects that are defined by specifying a center and radius. Circles, Sectors, and Pies have radii. Changing the radius does not affect the center. The gmsLRadius( ) function changes the radius for a List of objects and gmsQRadius( ) returns the radius of an object. SL-GML COMMAND name radius real Version 6.2a- 26 May 2006 SL-GMS Function Reference 310 Raster image of objects — save and restore 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 int gmsPopOn (view, object, saveObj, inMode) id view; id object; int saveObj; int inMode; /* ignored */ int gmsPopOff (view, object, saveFlag) id view; id object; int saveFlag; int gmsPopReset ( ) DESCRIPTION The gmsPopOn( ) function makes an object visible while arranging to redisplay any objects obscured by this action. The gmsPopOff( ) function makes a popped-on object invisible and restores the image saved when the object was popped on. When an object is popped on, its extent is calculated and saved in an internal table. Popping off the object involves redrawing this extent in the View given as an argument to gmsPopOff( ). The View given as an argument must contain both the object to be made visible and the Version 6.2a- 26 May 2006 SL-GMS Function Reference 311 Raster image of objects — save and restore objects that will be obscured when the object is made visible. the object to be made visible must be invisible. Initially, The gmsPopOn( ) function has two additional arguments: saveObj and inMode. The saveObj argument, when set to 1, saves a raster image of the popped-on object. The raster image is used to redraw the popped-on object on platforms where this action is appropriate. Since not all platforms can save raster images or display these saved images faster than it would take to redraw the object, the saveObj flag is not normally set to 1. The inMode argument is currently ignored. The saveFlag argument to gmsPopOff( ), when set to 1, preserves the information about the popped-off object in the internal table. The default behavior is to release this information, the object’s extent, and possibly its raster image when the object is popped off. Setting the saveFlag to 1 expedites the popping back on of this object. The current limit to the number of objects that can be saved is 64. The gmsPopReset( ) function releases the information kept in the internal table about popped-on objects. Popon/popoff Modes in SL-GMS When a popup object (e.g., Menu or Dialog Box) is erased, the graphical data that was covered by it must somehow be restored. Restoration of graphical data is accomplished by drawing and erasing the object in a Popon/popoff Mode. SL-GMS has two Popon/Popoff Modes: Mode Type Description Raster Popon/popoff saves a raster image of the area to Mode be covered by an object; to erase an object the raster image is redrawn Clip Popon/popoff constructs a clipping rectangle Mode 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 312 Raster image of objects — save and restore NOTE: The Popon/popoff Mode Workstation option, G_WS_POP_RASTER, should be used if a popup object's extent overlaps more than one View. The screen redraws incorrectly if Clip Popon/popoff Mode, G_WS_POP_CLIP, is used. The effects of the Raster and Clip Popon/popoff Modes can be seen in the Dialog on-line example. The on-line example is run with -pr for Raster Popon/popoff Mode, or -pc or Clip Popon/popoff Mode. The "Timer" and "Exit" Dialog Boxes are drawn and erased in the specified mode. Version 6.2a- 26 May 2006 SL-GMS Function Reference 313 Raster image of View — save, restore, create 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; int gmsVuRRest (view, workst, raster, freeFlag) id view; id workst; short *raster; int freeFlag; int gmsVuRFile (view, workst, filename) id view; id workst; char *filename; DESCRIPTION These functions are useful for manipulating the raster which is "under" a View object. The limits of the Viewport determine the size and number 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 work area so that it can be restored later. The pointer to the pixels returned by this function is passed to the gmsVuRRest( ) function in order to put Version 6.2a- 26 May 2006 SL-GMS Function Reference 314 Raster image of View — save, restore, create them back. The freeFlag argument to the gmsVuRRest( ) function tells 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 a machine-dependent manner. The filename has the ".xwd" extension appended in an X Window platform, and the ".bmp" extension in a Win32 platform. 1 SEE ALSO gmsView( ), gmsWind( ), gmsBitmap( ) SL-GML COMMAND vfile 1. Win32 refers to a platform with a 32-bit architecture running Microsoft Windows NT or Windows 95. Version 6.2a- 26 May 2006 SL-GMS Function Reference 315 Raster Operation Mode attribute Raster Operation Mode attribute SUMMARY set the Raster Operation Mode attribute NAME gmsRastOp( ), gmsLRastOp( ), gmsMRastOp( ) SYNTAX int gmsRastOp (obj, rastop) id obj; int rastop; int gmsLRastOp (objlist, rastop) idLinkRef objlist; int rastop; int gmsMRastOp (rastop) int rastop; Version 6.2a- 26 May 2006 SL-GMS Function Reference 316 Raster Operation Mode attribute DESCRIPTION The gmsRastOp( ) function is used to set the Raster Operation Mode on SL-GMS Primitive objects. Raster Operation Mode is an attribute that applies to Bitmap objects. The following truth table depicts the meaning of the 16 possible values for Raster Operation Modes. Raster Operation Modes Source Destin Set 0 AND S & ~D Source ~S & D Destin. XOR OR NOR ~XOR ~D S | ~D ~S ~S | D NAND Set 1 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1 1 1 1 0 1 0 0 0 0 1 1 1 1 0 0 0 0 1 1 1 1 1 0 0 0 1 1 0 0 1 1 0 0 1 1 0 0 1 1 1 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 0 1 Raster Operation Mode Number 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 Some of the 16 possible values are not used, such as set to 1 or set to 0. All values are platform-dependent. For example, a particular platform has only three modes: overwrite (Source only (3)), AND (1), and XOR (6). The Workstation object may map other Raster Operation Modes to one of these three functional values. In raster operations, the erase color is 0 so anytime a Bitmap is ANDed to a region of a View containing the erase color, the Bitmap is also erased in those regions. Version 6.2a- 26 May 2006 SL-GMS Function Reference 317 Raster Operation Mode attribute The gmsLRastOp( ) function sets the Raster Operation Mode on a List of objects. The Raster Operation Mode attributes are the same as for the gmsRastOp( ) function. The gmsMRastOp( ) function sets the modal Raster Operation Mode, affecting subsequently created Graphical Primitives. SEE ALSO gmsBitmap( ) SL-GML COMMANDS name rastop rastmode Version 6.2a- 26 May 2006 SL-GMS Function Reference 318 Rectangle object Rectangle object SUMMARY create a Rectangle object NAME gmsRect( ), gmsRRect( ), gmsFRect( ), gmsRFRect( ), gmsFTRect( ), gmsRFTRect( ) SYNTAX id gmsRect (name, points) char *name; idLinkRef points; id gmsRRect (name, points) char *name; idLinkRef points; id gmsFRect (name, points) char *name; idLinkRef points; id gmsRFRect (name, points) char *name; idLinkRef points; id gmsFTRect (name, points, text) char *name; idLinkRef points; char *text; Version 6.2a- 26 May 2006 SL-GMS Function Reference 319 Rectangle object id gmsRFTRect (name, points, text) char *name; idLinkRef points; char *text; DESCRIPTION The gmsRect( ) function is used to create a Rectangle object given two Points contained in a Point List. The gmsRRect( ) function is identical except the second Point in the List is a relative offset from the first Point. The current edge attributes are applied to the object when it is created. The gmsFRect( ) and gmsRFRect( ) functions are identical to their counterparts without the "F", but Filled Rectangles are created. The gmsFTRect( ) and gmsRFTRect( ) functions create Filled Rectangles that contain Text. The Text is passed to these functions via the third argument, which is a simple C string (a pointer to character). All current Text attributes apply to the text portion of the object. The name argument is optional and is the name that is assigned to the object when it is added to the current Model. EXAMPLE The following code fragment demonstrates the creation of a Rectangle object. /* declare variables */ idPoint pointA, pointB; id LinkRef corners; id rect; /* create Points for Rectangle corners*/ pointA = gmsWPXY(5., 0.); pointB = gmsWPXY(95., 70.); /* add Points to List */ corners = refNewRef(pointA); refAdd(corners, pointB); Version 6.2a- 26 May 2006 SL-GMS Function Reference 320 Rectangle object /* create Rectangle named "frame" */ rect = gmsRect("frame", corners); /* display the Rectangle */ gmsUpdate(nil); Creating Graphical Primitive objects requires other objects as arguments. First, two Point objects are created, using the World Coordinate Point-creation function, gmsWPXY( ). Next, these Points are added to a Linked List object, which is passed as an argument to the gmsRect( ) function. The current Model now contains a single part: the Rectangle object. The gmsUpdate( ) function causes the Rectangle to be displayed. The corresponding SL-GML commands that perform the same operations as the program fragment above are: gml ready> frame: rect 5 0 95 70 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" Version 6.2a- 26 May 2006 SL-GMS Function Reference 321 Reference Point Reference Point SUMMARY change an object’s or List of objects’ Reference Point; return an object’s Reference Point NAME gmsRefPoint( ), gmsRefPointX( ), gmsRefPointY( ), gmsLRefPoint( ), gmsLRefPointX( ), gmsLRefPointY( ), gmsQRefPoint( ), gmsQRefPointX( ), gmsQRefPointY( ), gmsQDefRefPt( ) SYNTAX int gmsRefPoint (obj, point) id obj; idPoint point; int gmsRefPointX (obj, rpx) id obj; int rpx; int gmsRefPointY (obj, rpy) id obj; int rpy; int gmsLRefPoint (objlist, point) idLinkRef objlist; idPoint point; int gmsLRefPointX (objlist, rpx) idLinkRef objlist; int rpx; Version 6.2a- 26 May 2006 SL-GMS Function Reference 322 Reference Point int gmsLRefPointY (objlist, rpy) idLinkRef objlist; int rpy; idPoint gmsQRefPoint (obj) id obj; int gmsQRefPointX (obj) id obj; int gmsQRefPointY (obj) id obj; idPoint gmsQDefRefPt (obj) id obj; DESCRIPTION These functions set an object’s or a List of objects’ Reference Points, or return the Reference Point. The Reference Point is used during object transformations, such as scaling and rotating. Setting the Reference Point to nil clears the current Reference Point, so that the default Point is used. The user should always free the Point given as an argument in setting the Reference Point after use. The default Reference Point for an object is the center of that object’s extent. The current Reference Point can be returned by gmsQRefPoint( ), and the default Reference Point with gmsQDefRefPt( ). The returned Point should be freed with pntFree( ). The gmsQRefPointX( ) function returns the x Internal Coordinate for the current Reference Point, while the gmsQRefPointY( ) function returns the y Internal Coordinate for the current Reference Point. Functions that take integer coordinates as arguments must first convert World Coordinate arguments (double values) into internal integer representation using the gmsWValue( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 323 Reference Point EXAMPLE The gmsRefPointX( ) function requires a World Coordinate: gmsRefPointX(obj, gmsWValue(10.0)); EXAMPLE To retrieve a valid Reference Point for an object: ref_point = gmsQRefPoint(obj); if (!ref_point) ref_point = gmsQDefRefPt(obj); SEE ALSO gmsRRotZ( ), gmsARotZ( ), gmsRScale( ), gmsAScale( ), gmsWValue( ), gmsWCoordX( ) SL-GML COMMAND name refpoint Version 6.2a- 26 May 2006 SL-GMS Function Reference 324 Relative move Relative move SUMMARY apply a relative move transformation NAME gmsRMove2( ), gmsLRMove2( ), gmsMRMove2( ), gmsRMoveX( ), gmsLRMoveX( ), gmsMRMoveX( ), gmsRMoveY( ), gmsLRMoveY( ), gmsMRMoveY( ), gmsCRMv2( ) SYNTAX int gmsRMove2 (obj, point) id obj; idPoint point; int gmsLRMove2 (objlist, point) idLinkRef objlist; idPoint point; int gmsMRMove2 (point) idPoint point; int gmsRMoveX (obj, mx) id obj; int mx; int gmsLRMoveX (objlist, mx) idLinkRef objlist; int mx; Version 6.2a- 26 May 2006 SL-GMS Function Reference 325 Relative move int gmsMRMoveX (mx) int mx; int gmsRMoveY (obj, my) id obj; int my; int gmsLRMoveY (objlist, my) idLinkRef objlist; int my; int gmsMRMoveY (my) int my; int gmsCRMv2 (point) idPoint point; DESCRIPTION These functions define a relative move transformation. The transformation matrix is combined with any existing matrix. The gmsRMove2( ) function operates on an individual object, while the gmsLRMove2( ) 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 if SL-GMS is in Immediate Update Mode. The point argument contains the distance that the objects are to be translated. 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 x coordinate is set to 0. The gmsCRMv2( ) function applies to the creation of future Clones or Instances. The gmsMRMove2( ) function sets a modal offset transformation which applies to all objects subsequently created. Version 6.2a- 26 May 2006 SL-GMS Function Reference 326 Relative move Functions that take integer coordinates as arguments must first convert World Coordinate arguments (double values) into internal integer representation using the gmsWValue( ) function. EXAMPLE gmsRMoveY(obj, gmsWValue(10.0)); SL-GML COMMANDS name offset x y name rmove x y name rmovex x name rmovey y moffset x y Version 6.2a- 26 May 2006 SL-GMS Function Reference 327 Relative rotation Relative rotation SUMMARY apply a relative Z-axis rotation transformation NAME gmsRRotZ( ), gmsLRRotZ( ), gmsCRRotz( ), gmsMRRotZ( ) SYNTAX int gmsRRotZ (obj, angle) id obj; double angle; int gmsLRRotZ (objlist, angle) idLinkRef objlist; double angle; int gmsCRRotz (point, angle) idPoint point; double angle; int gmsMRRotZ (point, angle) idPoint point; double angle; DESCRIPTION These functions define a relative Z-axis rotation transformation. The transformation matrix is combined with any existing matrix. The gmsRRotZ( ) function operates on an individual object, while the gmsLRRotZ( ) 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 occur automatically only if SL-GMS is in Immediate Update Mode. Version 6.2a- 26 May 2006 SL-GMS Function Reference 328 Relative rotation Individual objects or Lists of objects are rotated around the reference point set with gmsRefPoint( ). The point argument used with gmsMRRotZ( ) is the center of rotation and must be a Point object. The rotation angle is a double argument specified as degrees to rotate counterclockwise. The gmsCRRotZ( ) function applies to the creation of future Clones or Instances. The gmsMRRotZ( ) function sets a modal rotation transformation which applies to all objects subsequently created. SL-GML COMMANDS name rrotz angle mrotz x y angle Version 6.2a- 26 May 2006 SL-GMS Function Reference 329 Relative scale Relative scale SUMMARY apply a relative 2D scale transformation NAME gmsRScale( ), gmsLRScale( ), gmsMRScale( ), gmsRScaleX( ), gmsLRScaleX( ), gmsMRScaleX( ), gmsRScaleY( ), gmsLRScaleY( ), gmsMRScaleY( ), gmsCRSca2( ) SYNTAX int gmsRScale (obj, sxy) id obj; double sxy; int gmsLRScale (objlist, sxy) idLinkRef objlist; double sxy; int gmsMRScale (point, sx, sy) idPoint point; double sx; double sy; int gmsRScaleX (obj, sx) id obj double sx; int gmsLRScaleX (objlist, sx) idLinkRef objlist; double sx; Version 6.2a- 26 May 2006 SL-GMS Function Reference 330 Relative scale int gmsMRScaleX (point, sx) idPoint point; double sx; int gmsRScaleY (obj, sy) id obj; double sy; int gmsLRScaleY (objlist, sy) idLinkRef objlist; double sy; int gmsMRScaleY (point, sy) idPoint point; double sy; int gmsCRSca2 (point, sx, sy) idPoint point; double sx; double sy; DESCRIPTION These functions define a relative 2D scale transformation. The transformation matrix is combined with any existing matrix. The gmsRScale( ) function operates on an individual object, while the gmsLRScale( ) 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 occur only if SL-GMS is in Immediate Update Mode. Objects, or Lists of objects, are scaled around the Reference Point set by the gmsRefPoint( ) function. The point argument is the center of scaling and must be a pointer to a Point object. The x and y scale factors must be double arguments. If gmsRScaleX( ) is used, the y Version 6.2a- 26 May 2006 SL-GMS Function Reference 331 Relative scale scale factor is set to 1.0. to 1.0. For gmsRScaleY( ), the x scale factor is set Functions that take integer coordinates as arguments must first convert World Coordinate arguments (double values) into internal integer representation using the gmsWValue( ) function. The gmsMRScale( ) function sets a modal scale transformation which applies to all objects subsequently created. The gmsCRSca2( ) function applies to the creation of future Clones or Instances. SL-GML COMMANDS name scale x y sx sy name rscale sx sy name rscalex sx name rscaley sy mscale x y sx sy Version 6.2a- 26 May 2006 SL-GMS Function Reference 332 Relative transformation Relative transformation SUMMARY apply relative transformation to an object NAME gmsRTran( ), gmsLRTran( ), gmsCRTran( ), gmsMRTran( ) SYNTAX int gmsRTran (obj, tran) id obj; idMatrix tran; int gmsLRTran (objlist, tran) idLinkRef objlist; idMatrix tran; int gmsCRTran (tran) idMatrix tran; int gmsMRTran (tran) idMatrix tran; Version 6.2a- 26 May 2006 SL-GMS Function Reference 333 Relative transformation DESCRIPTION These functions apply a relative transformation matrix to an object or List of objects. The transformation matrix is combined with any existing matrix. The gmsATran( ) function sets the transformation absolutely. The gmsRTran( ) function operates on an individual object, while the gmsLRTran( ) 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 occur only if SL-GMS is in Immediate Update Mode, otherwise the transformation is apparent the next time the display is updated. The gmsCRTran( ) function applies to the creation of future Clones or Instances. The gmsMRTran( ) function sets the modal transformation that applies to all objects subsequently created. These four functions require a 2D transformation Matrix object as an argument (idMatrix). SEE ALSO gmsATran( ), gmsXTran( ) SL-GML COMMAND [name] tran d0 d1 d2 d3 d4 d5 Version 6.2a- 26 May 2006 SL-GMS Function Reference 334 Reset transformation Reset transformation SUMMARY reset transformation on an object NAME gmsTran0( ), gmsLTran0( ), gmsCTr0( ), gmsMTran0( ) SYNTAX int gmsTran0 (obj) id obj; int gmsLTran0 (objlist) idLinkRef objlist; int gmsCTr0( ) int gmsMTran0( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 335 Reset transformation DESCRIPTION These functions reset transformations that have been applied to objects. The gmsTran0( ) function operates on an individual object, while the gmsLTran0( ) 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 occur only if SL-GMS is in Immediate Update Mode. The gmsCTr0( ) function applies to the creation of future Clones or Instances. The gmsMTran0( ) function sets a modal transformation which applies to all objects subsequently created. SL-GML COMMANDS [name] tran0 mtran0 Version 6.2a- 26 May 2006 SL-GMS Function Reference 336 Sector object Sector object SUMMARY create a Sector object NAME gmsSect( ), gmsSec2( ), gmsSec3( ), gmsFSec( ), gmsFSec2( ), gmsFSec3( ) SYNTAX id gmsSect (name, center, radius, start, length) char *name; idPoint center; double radius; double start; double length; id gmsSec2 (name, points) char *name; idLinkRef points; id gmsSec3 (name, points) char *name; idLinkRef points; id gmsFSect (name, center, radius, start, length) char *name; idPoint center; double radius; double start; double length; Version 6.2a- 26 May 2006 SL-GMS Function Reference 337 Sector object id gmsFSec2 (name, points) char *name; idLinkRef points; id gmsFSec3 (name, points) char *name; idLinkRef points; DESCRIPTION The gmsSec( ) function is used to create a Sector object given a center Point, radius, start angle, and arc length. The Sector object is created with the current attributes. The radius argument should be given in World Coordinates and is multiplied by the World Coordinate Scale Factor. Angles (and the arc) are given in degrees, and arcs are drawn in a counterclockwise direction. The gmsSec2( ) function creates a Sector object given a center Point and two Points which are on the radius. The Points must be passed in a Point List. The second Point on the arc (the third in the List) will be adjusted 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 with the gmsWPXY( ) function. The Points must not be collinear, otherwise a Sector cannot be created. Although the Sector created contains Points which are passed to the function, the Sector object is represented as a center Point and two end Points which are determined from the three Points given. The gmsFSec( ), gmsFSec2( ), and gmsSec3( ) functions are used in the same manner as their counterparts without the "F", but the Sectors produced are filled. The name argument is optional and is the name that is assigned to the object when it is added to the current Model. The current edge attributes are applied to the object when it is created. Version 6.2a- 26 May 2006 SL-GMS Function Reference 338 Sector object SEE ALSO gmsCWFlag( ) 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 339 Sectors, Pies, Splines — miscellaneous Sectors, Pies, Splines — miscellaneous SUMMARY change the arc length or starting angle for Sectors and Pies; set the clockwise flag on Sectors, Pies, or Splines NAME gmsArcLength( ), gmsLArcLength( ), gmsQArcLength( ), gmsStartAngle( ), gmsLStartAngle( ), gmsQStartAngle( ), gmsCWFlag( ) SYNTAX int gmsArcLength (obj, arclength) id obj; double arclength; int gmsLArcLength (objlist, arclength) idLinkRef objlist; double arclength; double gmsQArcLength (obj) id obj; int gmsStartAngle (obj, startangle) id obj; double startangle; int gmsLStartAngle (objlist, startangle) idLinkRef objlist; double startangle; Version 6.2a- 26 May 2006 SL-GMS Function Reference 340 Sectors, Pies, Splines — miscellaneous double gmsQStartAngle (obj) id obj; int gmsCWFlag (obj, flag) id obj; int flag; DESCRIPTION The gmsArcLength( ) and gmsStartAngle( ) functions change the arc length and starting angle for Sector and Pie objects. Both arc length and starting angle are measured in degrees, starting with 0 degrees on the positive x axis, and moving counterclockwise with positive angles. The gmsLArcLength( ) and gmsLStartAngle( ) functions change the arc length and starting angle for a List of Sector and Pie objects. The gmsQArcLength( ) and gmsQStartAngle( ) functions query the arc length or start angle for Sector or Pie objects. The number of degrees 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 clockwise direction. SL-GML COMMANDS name startangle real name arclength real Version 6.2a- 26 May 2006 SL-GMS Function Reference 341 Set transformation Set transformation SUMMARY set the transformation for an object NAME gmsATran( ), gmsLATran( ), gmsCATran( ), gmsMATran( ), gmsTran( ) SYNTAX int gmsATran (obj, tran) id obj; idMatrix tran; int gmsLATran (objlist, tran) idLinkRef objlist; idMatrix tran; int gmsCATran (tran) idMatrix tran; int gmsMATran (tran) idMatrix tran; int gmsTran (object, tran) id object; idMatrix tran; DESCRIPTION These functions set an absolute transformation matrix for an object or List of objects. The transformation matrix replaces any existing matrix. Version 6.2a- 26 May 2006 SL-GMS Function Reference 342 Set transformation The gmsRTran( ) function combines the given transformation matrix with any existing transformation matrix. The gmsATran( ) function operates on an individual object, while the gmsLATran( ) 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 transformations occur only if SL-GMS is in Immediate Update Mode, otherwise the transformation is apparent the next time the display is updated. The gmsCATran( ) function applies to the creation of future Clones or Instances. The gmsMATran( ) function sets the modal transformation that applies to all objects subsequently created. These four functions require a 2D transformation Matrix object as an argument (idMatrix). The gmsTran( ) function transformation matrix. transforms the object by the given SEE ALSO gmsRTran( ) SL-GML COMMAND [name] tran d0 d1 d2 d3 d4 d5 Version 6.2a- 26 May 2006 SL-GMS Function Reference 343 Setup, quit, close SL-GMS Setup, quit, close SL-GMS SUMMARY setup, quit, and close the SL-GMS system NAME gmsSetup( ), gmsQuit( ), gmsClose( ), gmsExit( ), gmsYesFlag( ) SYNTAX int gmsSetup( ) int gmsQuit( ) int gmsClose( ) int gmsExit( ) int gmsYesFlag (flag) int flag; DESCRIPTION These functions operate at the outermost level of SL-GMS. The gmsSetup( ) function must be executed before any other SL-GMS function can be used. An implicit gmsProject( ) function is performed by gmsSetup( ) to initialize all modal attributes to their default values. By default, SL-GMS starts with a World Coordinate Scale Factor of 0x10000. The setting of 0x10000 may be changed with the gmsWCScale( ) function. The gmsSetup( ) function is called by gmsMainInit( ). The gmsQuit( ) function is called by the SL-GML interpreter when the quit command is entered. The gmsClose( ) function is called by Version 6.2a- 26 May 2006 SL-GMS Function Reference 344 Setup, quit, close SL-GMS gmsQuit( ) and provides a graceful closing but does not query the user first, as does gmsQuit( ). The gmsExit( ) function causes SL-GMS to close all Workstation/Windows and terminate execution without querying the user. The program is terminated with the exit( ) system command. The gmsYesFlag( ) function sets the query flag that SL-GMS checks when 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 existing Models and quits. When the flag is set to 1, the answer is always assumed to be yes. This flag is set by using the -y command-line option when invoking SL-DRAW2, SL-DRAW, or SL-GML. SEE ALSO gmsWCScale( ), gmsProject( ) SL-GML COMMANDS project coordscale real quit Version 6.2a- 26 May 2006 SL-GMS Function Reference 345 SL-GMS Installation Directory — query SL-GMS Installation Directory — query SUMMARY query the SL-GMS installation directory NAME gmsQGmsHome( ) SYNTAX char * gmsQGmsHome( ) DESCRIPTION The gmsQGmsHome( ) function returns the directory where SL-GMS is installed as contained in the GMS_HOME environment variable (Unix and 32-bit Windows), or the Registry (32-bit Windows only). Version 6.2a- 26 May 2006 SL-GMS Function Reference 346 SL-GMS Libraries — version, configuration, date SL-GMS Libraries — version, configuration, date SUMMARY query the SL-GMS version number, version date, and configuration number; compare a SL-GMS version number with the one in the SL-GMS Libraries being used. NAME gmsQVersion( ), gmsQReleaseDate( ), gmsQConfig( ), gmsCompareVersion( ) SYNTAX char * gmsQVersion( ) char * gmsQReleaseDate( ) char * gmsQConfig( ) int gmsCompareVersion (version) char *version; Version 6.2a- 26 May 2006 SL-GMS Function Reference 347 SL-GMS Libraries — version, configuration, date DESCRIPTION The gmsQVersion( ), gmsQReleaseDate( ), and gmsQConfig( ) functions take no arguments and return a character string containing the appropriate information. The strings returned from these functions are in the following form: gmsQVersion( ) 5.3a gmsQReleaseDate( ) 28 February 1995 gmsQConfig( ) 53a1_250228 The gmsCompareVersion( ) function allows applications to compare an SL-GMS version number with the version in the SL-GMS libraries being used with the application to determine if the SL-GMS libraries are of an identical, lower, or higher version number than the specified version number. The specified version number is passed in as a string. The gmsCompareVersion( ) function returns 1 if the SL-GMS libraries are a higher version than the specified version number, it returns -1 if they are a lower version, and it returns 0 if they are the identical version. NOTE: The specified version number need not be a complete SL-GMS version number for the comparison to work; however, if a shorter string than a complete SL-GMS version number is specified, the return value will reflect the comparison up to the number of characters in the specified SL-GMS version number. Version 6.2a- 26 May 2006 SL-GMS Function Reference 348 SL-GMS Libraries — version, configuration, date EXAMPLE The following table gives the return values from gmsCompareVersion( ) for various specified SL-GMS version numbers when used with SL-GMS libraries of SL-GMS version number "5.3a": Specified SL-GMS Version Number Version 6.2a- 26 May 2006 Return Value 4 1 5 1 5. 1 5.3 1 5.3a 0 5.3b -1 5.4 -1 6 -1 6. -1 SL-GMS Function Reference 349 Spline object Spline object SUMMARY create a Spline or Closed Spline object; create a List of Spline or Closed Spline objects NAME gmsSpline( ), gmsCSpline( ), gmsLMkSpline( ) SYNTAX id gmsSpline (name, points) char *name; idLinkRef points; id gmsCSpline (name, points) char *name; idLinkRef points; idLinkRef gmsLMkSpline (objlist) idLinkRef objlist; DESCRIPTION The gmsSpline( ) function creates a curved line (a Spline object) which takes its shape from the given Point List. In SL-GMS, Spline objects consist of a series of Bezier splines, each with two control Points. The gmsCSpline( ) function creates a Closed Spline from the given Point List, connecting the first and last Points if necessary. A Spline or Closed Spline is guaranteed to pass through all given Points. The name argument is optional and is the name assigned to the object when it is added to the current Model. The current edge attributes are applied to the object when it is created. The stress attribute applies only to Splines or Closed Splines and affects whether the curve is sharply or flatly curved to fit the Points. Version 6.2a- 26 May 2006 SL-GMS Function Reference 350 Spline object The gmsLMkSpline( ) function creates Spline or Closed Spline objects from a List of Polyline or Closed Polyline objects. Polylines and Closed Polylines may be mixed on the List; these objects are freed after their Point Lists have been used to create the new Spline or Closed Spline object. A List of the new objects is returned and each object is added to the current Model. SEE ALSO gmsStress( ), gmsCWFlag( ) SL-GML COMMANDS [name:] spline x y x y ... [name:] cspline x y x y ... Version 6.2a- 26 May 2006 SL-GMS Function Reference 351 State — attributes State — attributes SUMMARY set a State Instance’s attribute flags NAME gmsStClearFlag( ), gmsStFreeFlag( ), gmsStGismoFlag( ), gmsStPopFlag( ), gmsStVisFlag( ), gmsStDatFlag( ), gmsStD1Flag( ), gmsStAutoDeactFlag( ), gmsStUpdFlag( ) SYNTAX int gmsStClearFlag (state, clearflag) id state; /* State Instance */ int clearflag; /* clearflag = G_ON/G_OFF */ int gmsStFreeFlag (state, freeflag) id state; /* State Instance */ int freeflag; /* freeflag = G_ON/G_OFF */ int gmsStGismoFlag (state, gismoflag) id state; /* State Instance */ int gismoflag; /* gismoflag = G_ON/G_OFF */ int gmsStPopFlag (state, popflag) id state; /* State Instance */ int popflag; /* popflag = G_ON/G_OFF */ int gmsStVisFlag (state, visflag) id state; /* State Instance */ int visflag; /* visflag = G_ON/G_OFF */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 352 State — attributes int gmsStDatFlag (state, datflag) id state; /* State Instance */ int datflag; /* datflag = G_ON/G_OFF */ int gmsStD1Flag (state, d1flag) id state; /* State Instance */ int d1flag; /* d1flag = G_ON/G_OFF */ int gmsStAutoDeactFlag (state, autodeactflag) id state; /* State Instance */ int autodeactflag;/* autodeactflag = G_ON/G_OFF */ int gmsStUpdFlag (state, updflag) id state; /* State Instance */ int updflag; /* updflag = G_ON/G_OFF */ DESCRIPTION The gmsStClearFlag( ) function sets the state’s clearflag to G_ON or G_OFF. If the clearflag is set to G_ON, clearing of the State Instance’s View occurs before displaying a Model. The function returns 1 for success, 0 for failure. The SL-GMS default for clearflag is G_ON. The gmsStFreeFlag( ) function turns the state’s freeflag to G_ON or G_OFF. If the freeflag is set to G_ON, the State Instance is freed when 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_ON or G_OFF. If the gismoflag is set to G_ON and an input Event is received, this function causes SL-SMS to search the Models associated with the State Instance to determine if an object was selected and if it has input dynamics (i.e., if it is a GISMO). If it is a GISMO, the appropriate GISMO Action Function is called and no more processing is done on the Event. The SL-GMS default for gismoflag is G_ON. Version 6.2a- 26 May 2006 SL-GMS Function Reference 353 State — attributes If the gismoflag is set to G_OFF, Events are passed directly to the appropriate Event-handler. The function returns 1 for success, 0 for failure. The gmsStPopFlag( ) function turns the state’s popflag to G_ON or G_OFF. If the popflag is set to G_ON, SL-SMS uses gmsPopOn( ) to save a raster image when the State Instance is activated and gmsPopOff( ) to restore a raster image when the State Instance is deactivated. If the popflag is set to G_OFF, the entire View previously obscured is redrawn upon activation. The function returns 1 for success, 0 for failure. The SL-GMS default for popflag is G_OFF. The gmsStVisFlag( ) function turns the state’s visflag to G_ON or G_OFF. If the visflag is set to G_ON, SL-SMS leaves the State Instance’s Superstate’s Models visible 1 when the State Instance is activated. If the visflag is set to G_OFF, the Superstate’s Models are made invisible upon activation. The function returns 1 for success, 0 for failure. The SL-GMS default for visflag is G_OFF. The gmsStDatFlag( ) function turns the state’s datflag to G_ON or G_OFF. If the datflag is set to G_ON, SL-SMS opens a Datasource file (".dat" file) when the State is activated. The function returns 1 for success, 0 for failure. The SL-GMS default for datflag is G_OFF. The gmsStD1Flag( ) function turns the state’s d1flag to G_ON or G_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 for success, 0 for failure. The SL-GMS default for d1flag is G_OFF. As of this release, this function is not yet implemented. The gmsStAutoDeactFlag( ) function turns the state’s autodeactflag to G_ON or G_OFF. The autodeactflag controls the default behavior of the right mouse button. If the autodeactflag is set to G_ON, clicking the right mouse button (button 3) causes the State Instance to be deactivated. Automatic deactivation upon right mouse button click occurs even if an independent Event-handler was defined. The function returns 1 for success, 0 for failure. The SL-GMS default for autodeactflag is G_ON. The gmsStUpdFlag( ) function turns the state’s updflag to G_ON or G_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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 354 State — attributes the State’s update method each time a timer Event is received. The function returns 1 for success, 0 for failure. The SL-GMS default for updflag is G_ON. The gmsStUpdFlag( ) function has limited effect. Although it properly controls whether update messages are sent to a State and all of its Substates, any changes in variables elsewhere in an SL-GMS application cause the Models in the State to have their dynamics updated. The way to prevent the Models from having their dynamics updated is by not calling gmsVarChanged( ) on the driving variables, or by making the Model invisible. SEE ALSO The chapter entitled The State Management System in the SL-GMS Reference Manual Version 6.2a- 26 May 2006 SL-GMS Function Reference 355 State — class State — class SUMMARY create, install, and add methods to a State class NAME gmsStateClass( ), gmsClassAddMethod( ), gmsStClassInstall( ) SYNTAX id gmsStateClass (name, size) char *name; /* name of the State class */ int size; /* size of the State class */ int gmsClassAddMethod (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 */ int gmsStClassInstall (class) id class; /* State class created with gmsStateClass( ) */ DESCRIPTION The gmsStateClass( ) function creates a new State class named name, giving it a default set of attributes. The function returns a pointer to the new State class object created. If size is 0, a new generic State class is created. Version 6.2a- 26 May 2006 SL-GMS Function Reference 356 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. Valid codes for fctntype are G_INTEGER and G_POINTER. argtypes is not used and should be passed with a 0. The gmsStClassInstall( ) function installs a State class created with the gmsStateClass( ) function, connecting it to other SL-SMS objects and making it available for instancing. The function returns 1 for success, 0 for failure. NOTE: In SL-GMS version 5.x, checking the argument types is not implemented. EXAMPLE Below is a sample code fragment which uses gmsClassAddMethod( ) to add the loc_press method to a customized State: static int loc_press (state, event) id state; id event; { printf("... in state: %s (%d,%d)\n", gmsQStName(state), pntX(gmsQEvPoint(event)), pntY(gmsQEvPoint(event))); return 1; } ... int custom_state_initialize ( ) { static id stclass = 0; /* should only initialize once! */ if (stclass) return 0; Version 6.2a- 26 May 2006 SL-GMS Function Reference 357 State — class /* create custom State class object */ stclass = gmsStateClass("CustomState", sizeof(struct CLASS)); *** code continued on next page *** /* add method(s) for handling Events to this State class */ gmsClassAddMethod(stclass, "loc_press", loc_press, G_INTEGER, 0); /* install State class */ gmsStClassInstall(stclass); return 1; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 358 State — initialization State — initialization SUMMARY initialize States NAME gmsInitStates( ), gmsInitStatesOnWs( ), gmsStLocMotionEnable( ) SYNTAX int gmsInitStates( ) int gmsInitStatesOnWs (workst) id workst; int gmsStLocMotionEnable (state, flag) id state; /* State Instance*/ int flag; /* -1 (ON), 0 (OFF), or mask */ DESCRIPTION The Screen State Manager component of SL-SMS, explained in The chapter entitled The State Management System of the SL-GMS Reference Manual, is a module provided to manage a hierarchy of screen States. Use of the Screen State Manager module is optional, but its use practically eliminates the coding necessary to coordinate mapping and unmapping of dynamic screens, to handle Events, and to activate Datasources. The functions described in this section are used for initialization of the Screen State Manager and the enabling of a State’s Locator motion Events. Version 6.2a- 26 May 2006 SL-GMS Function Reference 359 State — initialization 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 applications (the predefined States currently provided are screen, datscreen, and popup); and 3. establish several predefined GISMO functions that can operate on screen States (such as gms_screen_state_invoke( ), for example). When gmsInitStates( ) is called, SL-SMS internally sets up Event-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( ) State method). When using the SL-SMS Event-handling mechanism (i.e., when gmsInitStates( ) is called) gmsWsEventFctn( ) should not be called by the application program, since doing so interferes with SL-SMS’ Event-handling capability. NOTE: SL does not recommend the explicit setup of State callback functions via gmsWsEventFctn( ); rather, the automatic setup provided by the gmsInitStates( ) function should be utilized. The gmsInitStatesOnWs( ) function is called whenever a new Workstation is created after the call to gmsInitStates( ). The gmsInitStatesOnWs( ) function sets up a set of 18 Event-handlers for the new Workstation. NOTE: The gmsInitStatesOnWs( ) function also sets the timer period to 0. Therefore, a call to gmsTimerPeriod( ) must be done after a gmsInitStatesOnWs( ) call for timer periods greater than 0. The gmsStLocMotionEnable( ) function enables Locator motion Events for the Workstation of the specified State. Full generation of Version 6.2a- 26 May 2006 SL-GMS Function Reference 360 State — initialization Locator motion Events is enabled by using a flag value of -1, and disabled with a value of 0. Alternatively, the user can use a mask containing the Event modifiers that must be true in order to report an Event. For example, the default flag value used by SL-GMS is G_LOC_BUTTON_LEFT, which means that Locator motion Events are enabled only when a LOC_PRESS Event is received from the left mouse button, and disabled upon LOC_RELEASE. The default behavior eliminates motion Events while moving the mouse without the button held down. The valid values for the flag argument are provided in the following table. Value 0 mask -1 Description Locator motion Events disabled Locator motion Events enabled when all modifiers in mask are on Locator motion Events always enabled The section MODIFIER KEY CODES in the "gmscodes.h" file in the lib directory, contains a complete list of modifier codes. The gmsStLocMotionEnable( ) function must be called after a State is activated. EXAMPLE gmsStLocMotionEnable(state, G_LOC_BUTTON_MIDDLE|G_CONTROL KEY); In the example above, Locator motion Events are enabled when the middle mouse button and the keyboard control key are depressed simultaneously. By default, Locator motion Events were enabled with the mask G_LOC_BUTTON_LEFT. SEE ALSO gmsWsEventFctn( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 361 State — initialization gmsbasic on-line example Version 6.2a- 26 May 2006 SL-GMS Function Reference 362 State — Instance State — Instance SUMMARY create, activate, and modify State Instances NAME gmsStateInst( ), gmsStActivate( ), gmsStDeactivate( ), gmsStWorkstName( ), gmsStViewName( ), gmsStAddModelName( ), gmsStClrModelNames( ), gmsStTextEditObj( ), gmsStTextEditObjName( ) SYNTAX id gmsStateInst (instname, classname) char *instname; /* name of State Instance to be created */ char *classname;/* name of State class */ int gmsStActivate (state, superstate) id state; /* State Instance */ id superstate; /* other State Instance */ int gmsStDeactivate (state) id state; /* State Instance */ int gmsStWorkstName (state, name) id state; /* State Instance */ char *name; /* name of a Workstation */ int gmsStViewName (state, name) id state; /* State Instance */ char *name; /* name of a View */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 363 State — Instance int gmsStAddModelName (state, name) id state; /* State Instance */ char *name; /* name of a Model */ int gmsStClrModelNames (state) id state; /* State Instance */ int gmsStTextEditObj (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 */ int gmsStTextEditObjName(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 = G_MULTI_EVENT/G_ONE_SHOT/ G_ONE_SHOT_CLEAR */ DESCRIPTION The gmsStateInst( ) function creates an Instance of a State Class. After an Instance is created, it may be activated by calling gmsStActivate( ). If no classname variable is supplied, an Instance Version 6.2a- 26 May 2006 SL-GMS Function Reference 364 State — Instance of the generic State Class is created. If no instname variable is supplied, the name "*" is given to the Instance. Creating State Instances can use a State Class exemplar. The exemplar is a single predefined State Instance which is associated with the State class. Creation of State Instances of that class is done by cloning the State class exemplar. Cloning the exemplar provides a mechanism whereby default attributes may be established for a State Class and assigned automatically whenever an Instance of that class is created. The exemplar State Instance is usually defined during the initialize( ) function for a particular State class. This is done by simply calling the gmsStateInst( ) function and assigning instame to be the same as classname. The exemplar does not have to be defined; it is optional. Nor is the exemplar ever activated; it is simply used as a template for storing default attributes. Each time a subsequent gmsStateInst( ) function call is made to create an Instance of the State class, it first looks to see if the exemplar can be found. If so, the new State Instance is created by cloning the exemplar; if not, a simple Instance is created with the standard default attributes. The process of cloning the exemplar to create a new State Instance involves creating a simple Instance and then copying all the standard State 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 copied to the new Instance by providing a copyfrom method. The method is invoked during the cloning process to permit the class to copy other State fields. This method is defined as follows: static int copy_from (state1, state2) idCLASS state1, state2; { state1->customfield = state2->customfield; Version 6.2a- 26 May 2006 SL-GMS Function Reference 365 State — Instance return 1; } Any necessary information may be copied from the exemplar in this manner in a custom copyfrom method. The gmsStActivate( ) function attaches the State Instance, state, to another State Instance, superstate, by adding it to superstate’s List of SubStates. The function installs the State Instance in the tree of State Instances. 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. The Top State can use this tree_changed method to provide an update to the application of the changes in the tree of active SL-SMS States. The function returns 1 for success, 0 for failure. However, when a custom activate method has been written for a State, gmsStActivate( ) returns 0 if the custom activate method returns -1, and returns 1 if the custom activate method returns any other value. When a State is activated with gmsStActivate( ), SL-SMS automatically calls gmsM2Get( ) and gmsDynInit( ) for each Model in the State’s Models List that is not already in memory. The last Model in the List is made the current Model in the Graphical Modeling Hierarchy. Then all Models associated with the State are made visible. The gmsStDeactivate( ) function removes state from the State tree. If the State Instance’s freeflag is set to G_ON, the function causes the State Instance to be freed. If the state State Instance has any SubStates, they also are deactivated. In addition, a "tree_changed" message is sent to the Top State of an application. The Top State can use this tree_changed method to provide an update to the application of the changes in the tree of active SL-SMS States. The gmsStWorkstName( ) function associates a Workstation/Window (window-manager window) with a State Instance. The Workstation/Window may be created before or after this call, using gmsWorkst( ). The gmsWorkst( ) function creates a named Workstation/Window object. Only one Workstation/Window may be associated with a given State Instance. Version 6.2a- 26 May 2006 SL-GMS Function Reference 366 State — Instance The gmsStViewName( ) function associates a View with a State Instance. The View is created and named using the gmsView( ) function. Only one View may be associated with a given State Instance. Calling gmsStViewName( ) and passing a NULL or empty string for the View name will clear the State’s internal View pointer. This should only be done after freeing the View: gmsObjFree(gmsQStView(state)); gmsStViewName(state, NULL); The gmsStAddModelName( ) function adds a Model to the List of Models maintained by a State Instance. The Model need not be loaded (using the gmsMGet( ) function) — if necessary it is loaded when the State Instance is activated. An unlimited number of Models may be added to the State Instance’s Model List by simply repeating the call to gmsStAddModelName( ). When a Model is added to a State with a call to gmsStAddModelName( ), any Substate of that State automatically refers to the Model in its SuperState. The Model should not be added to the Substate with another call to gmsStAddModelName( ). The gmsStClrModelNames( ) function clears state’s entire List of Models. This function does not free the Models; it only removes them from the State’s Model List. The gmsStTextEditObj( ) function associates a TextEdit object with state. The TextEdit object is automatically activated at the same time the State Instance is activated, and remains active when the State Instance is suspended (unless pre-empted by the TextEdit object of another State Instance, in which case it is restored as the active TextEdit object upon reactivation). When a State Instance is deactivated, the TextEdit object is forgotten, therefore, the gmsStTextEditObj( ) function is normally called in the State’s activate method to reset the object when the State is activated. To retain the TextEdit object, the gmsStTextEditObjName( ) function is used. Version 6.2a- 26 May 2006 SL-GMS Function Reference 367 State — Instance The gmsStTextEditObjName( ) function stores the name of a TextEdit object in a State Instance. The object name is not lost when the State is deactivated. When the State is activated, SL-SMS finds the object named textobjname 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, in which case it is restored as the active TextEdit object upon reactivation). The valid values for dispatch_mode for the gmsStTextEditObj( ) and the gmsStTextEditObjName( ) functions are as follows: 1. G_MULTI_EVENT — after a promptstring and initstring; redisplay 2. G_ONE_SHOT — after a do not redisplay promptstring and initstring (i.e., leave text that has been entered); 3. G_ONE_SHOT_CLEAR — after a do not redisplay promptstring and clear initstring (i.e., clear text that has been entered). NOTE: The application program must create the desired Workstation/Window, create a View in it, and associate a State Instance with that View. SEE ALSO gmsWsTextEditObj( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 368 State — mark and reset State — mark and reset SUMMARY mark and reset State stack NAME gmsStMark( ), gmsStReset( ), gmsStResetToMark( ), gmsStResetToTop( ) SYNTAX int gmsStMark (state, flag) id state; /* State Instance*/ int flag; /* flag = G_ON/G_OFF */ int gmsStReset (state) id state; /* State Instance*/ int gmsStResetToMark (state) id state; /* State Instance*/ int gmsStResetToTop( ) DESCRIPTION The gmsStMark( ) function marks the given State Instance so that a gmsStResetToMark( ) can be done. The function returns 1 for success, 0 for failure. The gmsStReset( ) function deactivates all of state’s SubStates. function returns 1 for success, 0 for failure. The The gmsStResetToMark( ) function deactivates state and all SuperStates up to the last State Instance marked with the gmsStMark( ) function. The marked State Instance is not deactivated. Version 6.2a- 26 May 2006 SL-GMS Function Reference 369 State — mark and reset 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 Instances except for the top-level State Instance. The function returns 1 for success, 0 for failure. Version 6.2a- 26 May 2006 SL-GMS Function Reference 370 State — messaging State — messaging SUMMARY send a message to a State Instance NAME gmsStStrMsg( ), gmsStPStrMsg( ), gmsStStrMsg1( ), gmsStPStrMsg1( ), gmsStStrMsg2( ), gmsStPStrMsg2( ), gmsStStrMsgNI( ), gmsStStrMsgNI1( ), gmsStStrMsgNI2( ) SYNTAX int gmsStStrMsg (state, msgstr) id state; /* State Instance */ char *msgstr; /* message string */ void * gmsStPStrMsg (state, msgstr) id state; /* State Instance */ char *msgstr; /* message string */ int gmsStStrMsg1 (state, id state; char *msgstr; long arg1; msgstr, arg1) /* State Instance */ /* message string */ /* method argument */ void * gmsStPStrMsg1 (state, msgstr, arg1) id state; /* State Instance */ char *msgstr; /* message string */ long arg1; /* method argument */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 371 State — messaging int gmsStStrMsg2 (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 */ int gmsStStrMsgNI (state, msgstr) id state; /* State Instance */ char *msgstr; /* message string */ int gmsStStrMsgNI1 (state, msgstr, arg1) id state; /* State Instance */ char *msgstr; /* message string */ long arg1; /* method argument */ int gmsStStrMsgNI2 (state, msgstr, arg1, arg2) id state; /* State Instance */ char *msgstr; /* message string */ long arg1, arg2;/* method arguments */ DESCRIPTION The gmsStStrMsg( ) function sends a message to a State Instance to invoke the method specified by the string, msgstr (i.e., the function registered with the state’s class via a call to gmsClassAddMethod( ) ). If the State Instance does not recognize the message, it attempts to find a "notrecognized" method. 1 If the "notrecognized" method is found, it is invoked by passing it the state instance id and the name of the method. Otherwise, the search is continued up the State tree. The search for a method continues until a State containing the specified 1. "notrecognized" methods are discussed in the SL-GMS® Reference. Version 6.2a- 26 May 2006 SL-GMS Function Reference 372 State — messaging method is found, a "notrecognized" method is found, or the top state is encountered. The function return value is whatever the invoked method 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 this function 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 invoked will be passed one argument. The function returns 1 for success, 0 for failure. The gmsStPStrMsg1( ) function sends a message to a State Instance, similar to the gmsStStrMsg( ) function. The difference is that the method invoked will be passed one argument and this function returns the 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 invoked will be passed two arguments. The function returns 1 for success, 0 for failure. The gmsStPStrMsg2( ) function sends a message to a State Instance, similar to the gmsStStrMsg( ) function. The difference is that the method invoked will be passed two arguments and this function returns the pointer value returned by the message. The gmsStStrMsgNI( ) function sends a message to a State Instance. If the State Instance does not recognize the message, it is not inherited from the SuperState. No attempt is made to look for a "notrecognized" method or to traverse the state’s tree hierarchy. No arguments are passed with the message. The function returns 1 for success, 0 for failure. The gmsStStrMsgNI1( ) function sends a message to a State Instance, similar to the gmsStStrMsgNI( ) function, except that one argument is passed with the message. The function returns 1 for success, 0 for failure. The gmsStStrMsgNI2( ) function sends a message to a State Instance, similar to the gmsStStrMsgNI( ) function, except that two arguments Version 6.2a- 26 May 2006 SL-GMS Function Reference 373 State — messaging are passed with the message. The function returns 1 for success, 0 for failure. SEE ALSO The appendix entitled SL-GMS System Organization in the SL-GMS Advanced Tutorial Version 6.2a- 26 May 2006 SL-GMS Function Reference 374 State — miscellaneous State — miscellaneous SUMMARY manipulate State classes and Instances NAME gmsSt30Flag( ), gmsStM2Flag( ), gmsStClassFindByName( ), gmsStDebugFlag( ), gmsStEventFctn( ), gmsStFindByName( ), gmsStWasFreed( ) SYNTAX int gmsSt30Flag (state, flag) id state; /* State Instance*/ int flag; /* flag = G_ON/G_OFF */ int gmsStM2Flag (state, flag) id state; /* State Instance*/ int flag; /* G_ON = search for ".m2" then ".m1" G_OFF = search for ".m1" then ".m2" */ id gmsStClassFindByName (name) char *name; /* name of a State Class */ int gmsStDebugFlag (debugflag) int debugflag; /* debug flag = 1, 2, 3 */ int gmsStEventFctn (fctn) int (*fctn)( ); /* Event-handler */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 375 State — miscellaneous id gmsStFindByName (instname) char *instname; /* name of a State Instance */ int gmsStWasFreed (freedmodel) id freedmodel; DESCRIPTION The gmsSt30Flag( ) function sets the version 3.0 compatibility flag to G_ON or G_OFF. The version 3.0 compatibility flag provides backward compatibility. With gmsSt30Flag( ) set to G_ON, the State Instance is not passed as the first argument to State methods, as in SL-GMS versions 3.0 and above. The function returns 1 for success, 0 for failure. The gmsStM2Flag( ) function may be used to change ".m2"/".m1" Model search order. Under SL-SMS, ".m2" Models are searched for first in a directory and then ".m1" Models are searched for. The gmsStClassFindByName( ) function returns a pointer to a State class given its name. The gmsStDebugFlag( ) function, a debugging utility, provides various levels of internal SL-SMS message tracing by setting the state_debug flag. The flag set to 0 turns tracing off. If the flag is greater than or equal to 1, the SL-SMS functions gmsStActivate( ), gmsStDeactivate( ), gmsStReset( ), gmsStResetToMark( ), gmsStResetToTop( ) are traced. Tracing of these functions can be helpful since they affect the Screen Management Hierarchy. If the flag is greater than or equal to 2, in addition to the information described above, string messages sent to States are printed. The state_debug flag set to 3 includes Level 1 and 2 information and adds Event tracing. The gmsStEventFctn( ) function establishes an Event-handler that intercepts all Events before they reach the State Event-handlers established via gmsInitStates( ). This function receives an Event before any of the Event-handler functions. The Event-handler function pointed to by fctn must take a single argument, id event, and return an int. A return value of 0 indicates the Event was absorbed by the callback. A return value of 1 tells the Screen State Manager to continue processing the Event in the usual manner. Version 6.2a- 26 May 2006 SL-GMS Function Reference 376 State — miscellaneous The gmsStFindByName( ) function returns a pointer to a State Instance given its name. The gmsStWasFreed( ) function informs all State Instances that a Model was freed (using the gmsObjFree( ) function). This function should be called whenever a Model managed by a State Instance is freed so that the address of the Model is cleared in the State Instance’s Model List. Upon activation or reactivation, SL-SMS reloads the Model. If SL-SMS is not informed about the freed Model by using this function, SL-SMS tries to display the Model (using an old address) upon activation or reactivation of the State Instance, resulting in an error. The function returns 1 for success, 0 for failure. SEE ALSO gmsInitStatesOnWs( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 377 State — query State — query SUMMARY query a State for its name, Model, View, Workstation/Window, and so on; query all active States NAME gmsQAllStates( ), gmsQStClassName( ), gmsQStCurState( ), gmsQStEvState( ), gmsQStIsActive( ), gmsQStModel( ), gmsQStModelList( ), gmsQStModelName( ), gmsQStName( ), gmsQStStrMsgState( ), gmsQStSubStates( ), gmsQStSuperState( ), gmsQStTextEditObj( ), gmsQStTopState( ), gmsQStView( ), gmsQStViewName( ), gmsQStWorkst( ), gmsQStWorkstName( ) SYNTAX idLinkRef gmsQAllStates( ) char * gmsQStClassName (state) id state; /* State Instance */ id gmsQStCurState( ) id gmsQStEvState( ) int gmsQStIsActive (state) id state; /* State Instance */ id gmsQStModel (state) id state; Version 6.2a- 26 May 2006 /* State Instance */ SL-GMS Function Reference 378 State — query idLinkRef gmsQStModelList (state) id state; /* State Instance */ char * gmsQStModelName (state) id state; /* State Instance */ char * gmsQStName (state) id state; /* State Instance */ id gmsQStStrMsgState( ) idLinkRef gmsQStSubStates (state) id state; /* State Instance */ id gmsQStSuperState (state) id state; /* State Instance */ id gmsQStTextEditObj (state) id state; /* State Instance */ id gmsQStTopState( ) id gmsQStView (state) id state; /* State Instance */ char * gmsQStViewName (state) id state; /* State Instance */ id gmsQStWorkst (state) id state; /* State Instance */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 379 State — query char * gmsQStWorkstName (state) id state; /* State Instance */ DESCRIPTION The gmsQAllStates( ) function allocates and returns a linked list of all active State objects. The list must be freed using refFreAll( ). The gmsQStClassName( ) function returns a string containing the class name of the class identified. The gmsQStCurState( ) function returns a pointer to the current State Instance (i.e., the most recently activated State Instance). When this State is deactivated, the current State is the SuperState. The gmsQStEvState( ) function returns a pointer to the last State Instance that received an Event. After this State is deactivated, the event State is 0. The gmsQStIsActive( ) function takes a pointer to a State Instance and determines whether it is active or not; a 1 is returned if the State Instance is active (i.e., has SuperStates or is the top-level State Instance) and a 0 if the State Instance is inactive. The gmsQStModel( ) function returns a pointer to the first Model in this State Instance’s Model List. The gmsQStModelList( ) function returns a pointer to State Instance’s Model List. The gmsQStModelName( ) function returns a string containing the name of the first Model in State Instance’s Model List. The gmsQStName( ) function returns a string containing the name of this State Instance. The gmsQStStrMsgState( ) function returns a pointer to the last State Instance that was sent a message. The gmsQStSubStates( ) function returns a pointer to this State Instance’s List of SubStates. This function returns a linked List of State Instances. The gmsQStSuperState( ) function returns a pointer to this State Instance’s SuperState. Version 6.2a- 26 May 2006 SL-GMS Function Reference 380 State — query The gmsQStTextEditObj( ) function returns a pointer to state’s TextEdit object. The gmsQStTopState( ) function returns a pointer to the top-level State Instance. The gmsQStView( ) function returns a pointer to this State Instance’s View. The gmsQStViewName( ) function returns a string containing the name of this State Instance’s View. The gmsQStWorkst( ) function returns a pointer to this State Instance’s Workstation/Window. The gmsQStWorkstName( ) function returns a string containing the name of State Instance’s Workstation/Window. Version 6.2a- 26 May 2006 SL-GMS Function Reference 381 State — variables State — variables SUMMARY initialize Variable References to a State, and, used with dynamic descriptions, make their scope local to a State NAME gmsStVarDefine( ), gmsStVarDefineChanged( ), gmsStVarChanged( ), gmsStVarDefChanged( ), gmsStFreeAllVarDefs( ), gmsStFindVarDefByNameAll( ), gmsStFindVarDefByAddrAll( ), gmsStFindVarDefAll( ), gmsStVarInitFctn( ) SYNTAX id gmsStVarDefine(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 */ id gmsStVarDefineChanged( 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 */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 382 State — variables int gmsStVarChanged (state, id state; /* char *varname; /* void *varaddr; /* varname, varaddr) State Instance */ name of variable */ address of variable */ int gmsStVarDefChanged (state, vardef) id state; /* State Instance */ id vardef; /* Variable Definition object */ int gmsStFreeAllVarDefs (state) id state; /* State Instance */ id gmsStFindVarDefByNameAll (state, varname) id state; /* State Instance */ char *varname; /* name of variable */ id gmsStFindVarDefByAddrAll (state, varaddr) id state; /* State Instance */ void *varaddr; /* address of variable */ id gmsStFindVarDefAll (state, varname, varaddr) id state; /* State Instance */ char *varname; /* name of variable */ void *varaddr; /* address of variable */ int gmsStVarInitFctn(function) id (*function)( ); DESCRIPTION The gmsStVarDefine( ) function defines variables as local to a State Instance. This function is often used to scope variable definitions on a Model-by-Model basis. Defining variables as local to a State rather than defining them as global with gmsVarDefine( ) can increase Version 6.2a- 26 May 2006 SL-GMS Function Reference 383 State — variables performance in applications which have a large number of variables defined. Variables defined in this manner are local in scope — two Models in different States can have identical variable names which are actually 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 the name and type attributes to which this variable refers by calling gmsStVarDefine( ) again. Then gmsDynInit( ) must be called to re-establish the links between the Variable Definition object and the Variable Reference objects which reference it. EXAMPLE The base of an array (i.e., the address of the Variable Definition object defining the array) is defined with the the following call : /* define array to start at "base1" */ gmsStVarDefine(gr_1,"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 Definition object. One method is to use gmsStVarDefine( ), in which case the following call is made: /* define array to start at "base2" */ gmsStVarDefine(gr_1,"y_array", &y_array[base2], G_DOUBLE | G_ARRAY, 100, 1); The Variable Definition object created using gmsStVarDefine( ), may also be given a new address by calling gmsStVarDefAddress( ). The count and size attributes can also be changed by calling gmsStVarDefCount( ) and gmsStVarDefSize( ). The gmsStVarDefineChanged( ) function defines a variable and marks it as changed. This function is the equivalent of calling both gmsStVarDefine( ) and gmsStVarChanged( ) for a variable. The gmsStVarChanged( ) function informs SL-GMS that an application variable which has been defined as local to a State has changed. The Version 6.2a- 26 May 2006 SL-GMS Function Reference 384 State — variables variable name or address passed to this function is the same as those used when defining the variable with gmsStVarDefine( ). The gmsStVarDefChanged( ) function takes a Variable Definition object as an argument and informs SL-GMS that an application variable has changed. The Variable Definition object is created for a local variable when the gmsStVarDefine( ) function is called. The gmsStFreeAllVarDefs( ) function frees all variables that have been defined for a State Instance. The gmsStFindVarDefByNameAll( ), gmsStFindVarDefByAddrAll( ), and gmsStFindVarDefAll( ) functions search for application variables by their name, address, or both. The local State tables of the State Instance passed to these functions are looked through first, then any SuperState’s tables are searched. Finally the global variable tables are searched for a matching variable, and the Variable Definition object is returned. The gmsStVarInitFctn( ) function sets up a callback function, which is called every time a variable reference is encountered during the gmsDynInit( ) function execution. The callback is defined by the user as follows: id stvarinit(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 new argument passed in is the State which is doing the execution of gmsDynInit( ). The second new argument is the SL-GMS Primitive being dyninited. SEE ALSO Dynamics — Variable Definition Table attached to Models on page -96 Dynamics — query and set Variable Definition attributes on page -90 State — variables on page -382 Version 6.2a- 26 May 2006 SL-GMS Function Reference 385 State — variables, set and query attributes State — variables, set and query attributes SUMMARY set and query individual attributes on an existing Variable Definition object NAME gmsStVarDefAddress( ), gmsQStVarDefAddress( ), gmsStVarDefCount( ), gmsQStVarDefCount( ), gmsStVarDefSize( ), gmsQStVarDefSize( ) SYNTAX int gmsStVarDefAddress (state, vardef, address) id state; id vardef; void *address; void * gmsQStVarDefAddress (state, vardef) id state; id vardef; int gmsStVarDefCount (state, vardef, count) id state; id vardef; int count; int gmsQStVarDefCount (state, vardef) id state; id vardef; Version 6.2a- 26 May 2006 SL-GMS Function Reference 386 State — variables, set and query attributes int gmsStVarDefSize (state, vardef, size) id state; id vardef; int size; int gmsQStVarDefSize (state, vardef) id state; id vardef; DESCRIPTION A Variable Definition object is created using gmsStVarDefine( ). A Variable Definition object’s address, size, and count attributes may be accessed individually. The gmsStVarDefAddress( ) function sets the address of an existing Variable Definition object. The gmsStVarDefCount( ) function sets the number of data elements, and gmsStVarDefSize( ) sets the size of each data element of an existing Variable Definition object. The gmsQStVarDefAddress( ), gmsQStVarDefCount( ), and gmsQStVarDefSize( ) functions are used to query individual attributes on an existing Variable Definition object. They are passed the id of the Variable Definition object. The gmsQStVarDefAddress( ) function returns the address. The gmsQStVarDefCount( ) function returns the number of data elements in the Variable Definition object. The gmsQStVarDefSize( ) function returns the size of each data element. NOTE: A Variable Definition object’s name and type attributes cannot be changed in this way. To specify a new Variable Definition name or type, a new Variable Definition object must be created using gmsStVarDefine( ). The gmsDynInit( ) function must then be called to re-establish the links between the Variable Definition object and the Variable Reference objects which reference it. Version 6.2a- 26 May 2006 SL-GMS Function Reference 387 State — variables, set and query attributes SEE ALSO gmsVarDefine( ), gmsVarDefineNoTable( ), gmsStVarDefine( ), gmsDynInit( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 388 Stress attribute Stress attribute SUMMARY set the stress attribute NAME gmsStress( ), gmsLStress( ), gmsMStress( ), gmsQStress( ) SYNTAX int gmsStress (obj, stress) id obj; double stress; int gmsLStress (objlist, stress) idLinkRef objlist; double stress; int gmsMStress (stress) double stress; double gmsQStress (obj) id obj; DESCRIPTION The gmsStress( ) function sets the stress attribute on Spline and Closed Spline objects. The gmsStress( ) function must be greater than 0 and is typically less than 1. Stress affects how sharply a Spline is curved. The default stress is 0.5. Values near 0 produce flattened curves and values near 1 create sharp curves. The gmsLStress( ) function sets the stress attribute on a List of objects. Version 6.2a- 26 May 2006 SL-GMS Function Reference 389 Stress attribute The gmsMStress( ) function sets the modal stress attribute, affecting subsequently created Splines and Closed Splines. The gmsQStress( ) function returns the stress attribute of an object, or the modal stress attribute, if a nil pointer is used. SEE ALSO gmsSpline( ), gmsCSpline( ) SL-GML COMMAND [name] stress double Version 6.2a- 26 May 2006 SL-GMS Function Reference 390 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 int gmsEStyle (obj, index) id obj; int index; int gmsMStyle (obj, index) id obj; int index; int gmsFStyle (obj, index) id obj; int index; int gmsFInter (obj, index) id obj; int index; int gmsLEStyle (objlist, index) idLinkRef objlist; int index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 391 Style attribute int gmsLMStyle (objlist, index) idLinkRef objlist; int index; int gmsLFStyle (objlist, index) idLinkRef objlist; int index; int gmsLFInter (objlist, index) idLinkRef objlist; int index; int gmsMEStyle (index) int index; int gmsMMStyle (index) int index; int gmsMFStyle (index) int index; int gmsMFInter (index) int index; int gmsQEStyle (obj) id obj; int gmsQMStyle (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 392 Style attribute int gmsQFStyle (obj) id obj; int gmsQFInter (obj) id obj; DESCRIPTION This is a complete set of functions for the manipulation of the different style attributes supported by SL-GMS. The first group of functions applies to individual objects, the second group to Lists of objects, the third to the modal attributes, and the fourth queries for style attribute settings. The character following the "gms", "gmsL", or "gmsM" in the name indicates whether the attribute applies to Edges ("E"), Lists of objects ("L"), Markers ("M"), or filled objects ("F"). Styles of filled objects and Edges are platform-dependent. The query functions return an integer that is an index for the style attribute of an object. The query functions return 0 if the user queries an object that does not have the particular style attribute. If a nil pointer is used as an argument to a query function, the current modal style attribute is returned. The modal attributes are referred to as the "current" width and are applied whenever new Graphical Primitive objects are created. DIAGNOSTICS No bounds checking is done for attributes. It is assumed that the device-driver software, at the SL-GWS layer of SL-GMS, deals with the attributes appropriately. SL-GML COMMANDS [name] lstyle index [name] estyle index [name] mstyle index [name] fstyle index [name] finter index Version 6.2a- 26 May 2006 SL-GMS Function Reference 393 SubModel List SubModel List SUMMARY move SubModels between the current Model’s Local and External SubModels List NAME gmsMExtToLoc( ), gmsMLocToExt( ) SYNTAX int gmsMExtToLoc (model) id model; int gmsMLocToExt (model) id model; DESCRIPTION These functions move SubModels between the current Model’s Local and External SubModel Lists. Local SubModels are included with the current Model when the current Model is saved or retrieved. External SubModels exist as a Model file (with ".m1" extension), and are read from disk when they are used in a Model. Any Model that is saved can be used as an external SubModel. If a Model used as an external SubModel is modified and saved, it appears modified in any Model which includes it as an external SubModel. If an external SubModel cannot be found when a Model is added to the Graphical Modeling Hierarchy, the Instances referencing the SubModel are freed. The gmsMExtToLoc( ) function moves a Model from the External SubModels List in the current Model to the Local SubModels List in the current Model. It may remove the external Model from the system-wide List of external Models, which is used to determine whether an external Model has already been read and added to the Graphical Modeling Version 6.2a- 26 May 2006 SL-GMS Function Reference 394 SubModel List Hierarchy (if this is the only reference to the external Model). A copy of the new local SubModel always becomes part of the current Model. The gmsMLocToExt( ) function moves a Model from the Local SubModels List in the current Model to the External SubModels List. Although external SubModels are based upon Model files, this function does not create a file copy of the Model. The gmsMSave( ) function must be used explicitly to create the Model file for the new external SubModel. SEE ALSO gmsMSave( ), gmsModInst( ), gmsModel( ), gmsCurModel( ), gmsMGet( ), gmsMXGet( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 395 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 int gmsBColor (obj, color) id obj; int color; int gmsTFont (obj, index) id obj; int index; int gmsTPrec (obj, index) id obj; int index; int gmsTPath (obj, index) id obj; int index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 396 Text — attributes int gmsTHeight (obj, height) id obj; double height; int gmsTAlign (obj, alx, aly) id obj; int alx; int aly; int gmsTSize (obj, sx, sy) id obj; int sx; int sy; int gmsTStr (obj, string) id obj; char *string; int gmsLTFont (objlist, index) idLinkRef objlist; int index; int gmsLTPrec (objlist, index) idLinkRef objlist; int index; int gmsLTPath (objlist, index) idLinkRef objlist; int index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 397 Text — attributes int gmsLTHeight (objlist, height) idLinkRef objlist; double height; int gmsLTAlign (objlist, alx, aly) idLinkRef objlist; int alx; int aly; int gmsLTSize (objlist, sx, sy) idLinkRef objlist; int sx; int sy; int gmsLBColor (list, color) idLinkRef list; int color; int gmsLTStr (objlist, string) idLinkRef objlist; char *string; int gmsMTFont (index) int index; int gmsMTPrec (index) int index; int gmsMTPath (index) int index; Version 6.2a- 26 May 2006 SL-GMS Function Reference 398 Text — attributes int gmsMTHeight (height) double height; int gmsMTAlign (alx, aly) int alx; int aly; int gmsMTSize (sx, sy) int sx; int sy; int gmsMBColor (color) int color; int gmsTPrec0RotFlag(flag) int flag; DESCRIPTION This is a complete set of functions for the manipulation of the different Text attributes supported by SL-GMS. The first group of functions applies to individual objects, the second group to Lists of objects, and the 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 and their corresponding SL-GML commands in the SL-GMS® Reference . The gmsBColor( ) function sets the Text background color for the given Text object. If no object is supplied, this function sets the modal Text background color. The modal attributes are referred to as "current" and are applied whenever new Text objects are created. The Text height is always multiplied by the World Coordinate Scale Factor. Version 6.2a- 26 May 2006 SL-GMS Function Reference 399 Text — attributes The gmsTPrec0RotFlag( ) function sets the flag that enables and disables rotation of precision 0 text (32-bit Windows only). The values G_ON and G_OFF are used to enable and disable text rotation. Turning the flag on only enables text rotation, it does not cause currently displayed text to be redisplayed. Text rotation is off by default. DIAGNOSTICS No bounds checking is done for attributes. It is assumed that the device-driver software, at the SL-GWS layer of SL-GMS, deals with the attributes appropriately. SEE ALSO gmsWCScale( ), gmsText( ), gmsTColor( ) SL-GML COMMANDS [name] font index [name] path index [name] prec index [name] height real Version 6.2a- 26 May 2006 SL-GMS Function Reference 400 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 id gmsText (name, string, point) char *name; char *string; idPoint point; int gmsTRepl (obj, string) id obj; char *string; int gmsLTStr (objlist, string) idLinkRef objlist; char *string; int gmsQTStringC (obj, buffer, buffer_size, needed_size) id obj; char *buffer; int buffer_size; int *needed_size; Version 6.2a- 26 May 2006 SL-GMS Function Reference 401 Text — object int gmsQTStringSO (obj, string_obj) id obj; id string_obj; int gmsQTStringWC (obj, buffer, buffer_size, needed_size) id obj; wchar_t *buffer; int buffer_size; int *needed_size; int gmsTStringC (obj, string) id obj; char *string; int gmsTStringSO (obj, string_obj) id obj; id string_obj; int gmsTStringWC (obj, string) id obj; wchar_t *string; DESCRIPTION The gmsText( ) function is used to create a Text object given the Text string and a position for the Text. The current Text attributes are applied to the object when it is created. The name argument is optional and is the name assigned to the object when it is added to the current Model. The gmsTRepl( ) function is used to change the string of Text that is stored in the object. If SL-GMS is in Immediate Update Mode, the Text is erased and redisplayed with the new string. The gmsLTStr( ) function replaces the Text in a List of Text objects with the new string. Version 6.2a- 26 May 2006 SL-GMS Function Reference 402 Text — object Because it is often desirable to use wide-character strings in an internationalized application, the gmsTStringWC( ) and gmsQTStringWC( ) functions are provided, which modify and query the text in Text and Text Rectangle objects using wide-character strings. The gmsTStringC( ) and gmsQTStringC( ) functions, which use character strings, are provided for consistency. To avoid string data type dependencies in an application, these dependencies must be encapsulated in an abstraction which can contain either character strings or wide-character strings. Such an abstraction in provided in the form of the String object. The gmsTStringSO( ) and gmsQTStringSO( ) functions modify and query the text in Text and Text Rectangle objects using String objects. The gmsTStringWC( ) function replaces the string contained in the given Text or Text Rectangle object with a copy of the given wide-character string. If the given wide-character string is NULL, the Text or Text Rectangle object will contain an empty string (L"") after the call to gmsTStringWC( ). The function returns 1 if it succeeds and 0 if it fails. The gmsQTStringWC( ) function copies the string contained in the given Text or Text Rectangle object to the given wide-character buffer. The buffer_size argument specifies the maximum number of wide-characters which can be copied to the given buffer, including the terminating wide-character. If the needed_size argument is not equal to NULL, gmsQTStringWC( ) stores in the memory location referenced by needed_size an integer specifying the buffer size required to copy the entire string in the Text or Text Rectangle to the buffer. This is the number of wide-characters needed, including the terminating wide-character. The string copied to buffer is always terminated by the null wide-character (L'\0'), even when the function returns G_OVERFLOW. If buffer is NULL, the function will still return in needed_size the buffer size required to copy the entire string in the Text or Text Rectangle. This enables an application to determine the exact buffer size needed before allocating the buffer. Version 6.2a- 26 May 2006 SL-GMS Function Reference 403 Text — object The gmsQTStringWC( ) function returns one of the values indicated in the following table: 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 Text or Text Rectangle. If buffer was not NULL, buffer_size wide-characters were copied. G_INVALID_INPU T One of the parameters to the function was invalid. If gmsQTStringWC( ) returns G_OVERFLOW, the number returned by needed_size can be used to allocate a larger buffer. After allocating a larger buffer, if buffer_size is greater than or equal to the number in needed_size, a second call to gmsQTStringWC( ) will not return G_OVERFLOW. The gmsTStringC( ) function replaces the string contained in the given Text or Text Rectangle object with a copy of the given character string. If the given character string is NULL, the Text or Text Rectangle object will contain an empty string ("") after the call to gmsTStringC( ). The function returns 1 if it succeeds and 0 if it fails. The gmsQTStringC( ) function copies the string contained in the given Text or Text Rectangle object to the given character buffer. The buffer_size argument specifies the maximum number of characters which can be copied to the given buffer, including the termination character. If the needed_size argument is not equal to NULL, gmsQTStringC( ) stores in the memory location referenced by needed_size an integer specifying the buffer size required to copy the entire string in the Text or Text Rectangle to the buffer. This is the number of characters needed, including the termination character. Version 6.2a- 26 May 2006 SL-GMS Function Reference 404 Text — object 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 buffer size required to copy the entire string in the Text or Text Rectangle. This enables an application to determine the exact buffer size needed before allocating the buffer. The gmsQTStringC( ) function returns one of the values indicated in the following table: 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 Text or Text Rectangle. 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 string in the given object was converted to multi-byte form. If gmsQTStringC( ) returns G_OVERFLOW, the number returned by needed_size can be used to allocate a larger buffer. After allocating a larger buffer, if buffer_size is greater than or equal to the number in needed_size, a second call to gmsQTStringC( ) will not return G_OVERFLOW. However, the function may return G_CONVERSION_FAILURE. The gmsTStringSO( ) function replaces the string contained in the given Text or Text Rectangle object with a copy of the string contained in the given String object. The String object can contain either a Version 6.2a- 26 May 2006 SL-GMS Function Reference 405 Text — object character string or a wide-character string. The function returns 1 if it succeeds and 0 if it fails. The gmsQTStrSO( ) function copies the string contained in the given Text or Text Rectangle object to the given String object. If the buffer in the given String object is not large enough to contain the entire string, it is freed and a larger one is allocated. The String object itself is not reallocated. The function returns 1 if it succeeds and 0 if it fails. SEE ALSO Internationalization — String object on page -208 gmsTFont( ) SL-GML COMMANDS [name:] text "string" x y name stext "string" Version 6.2a- 26 May 2006 SL-GMS Function Reference 406 Text — query attributes Text — query attributes SUMMARY query Text attributes NAME gmsQTFont( ), gmsQTPrec( ), gmsQTPrec0RotFlag( ), gmsQTPath( ), gmsQTSizeX( ), gmsQTSizeY( ), gmsQBColor( ), gmsQTHeight( ), gmsQTAlignX( ), gmsQTAlignY( ) SYNTAX int gmsQTFont (obj) id obj; int gmsQTPrec (obj) id obj; int gmsQTPrec0RotFlag( ) int gmsQTPath (obj) id obj; int gmsQTSizeX (obj) id obj; int gmsQTSizeY (obj) id obj; int gmsQBColor (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 407 Text — query attributes double gmsQTHeight (obj) id obj; int gmsQTAlignX (obj) id obj; int gmsQTAlignY (obj) id obj; DESCRIPTION This 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 text rotation flag for precision 0 text (32-bit Windows only). Version 6.2a- 26 May 2006 SL-GMS Function Reference 408 Text Rectangle — constraint attribute Text Rectangle — constraint attribute SUMMARY Set,or query, the Text Rectangle constraint attribute. The Text Rectangle constraint attribute controls how text behaves when it overflows the bounds of the Text Rectangle. NAME gmsTRectTextConstraint( ), gmsLTRectTextConstraint( ), gmsMTRectTextConstraint( ), gmsQTRectTextConstraint( ) SYNTAX int gmsTRectTextConstraint(trect, constraint) id trect; unsigned int constraint; int gmsLTRectTextConstraint(objlist, constraint) idLinkRef objlist; unsigned int constraint; int gmsMTRectTextConstraint(constraint) unsigned int constraint; unsigned int gmsQTRectTextConstraint(trect) id trect; DESCRIPTION This set of functions sets or queries the text constraint attribute for Text Rectangle objects. The text constraint attribute may be any one of the values described below. Version 6.2a- 26 May 2006 SL-GMS Function Reference 409 Text Rectangle — constraint attribute G_TCONSTRAINT_NONE This value is the default and allows a Text Rectangle's text to display outside (overflow) the Rectangle portion of the object. G_TCONSTRAINT_CLIP This value causes a Text Rectangle's text to be clipped to the Rectangle boundary. G_TCONSTRAINT_FIT_WIDTH This value causes a Text Rectangle's text to fit inside the width of the Rectangle boundary. This is accomplished by changing the position of individual characters in the text. The characters may overlap each other to stay inside the boundary. If the width of a single character overflows the boundary, the characters will overlap each other and the text will overflow the text rectangle (it will not be clipped). This mode does not modify font size, just character positioning. This mode is used to compensate for the non-linear scaling of 32-bit Windows TrueType fonts. 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 Text Rectangle boundary smaller for fitting or clipping the text. The Text Rectangle boundary is the same as the Text Rectangle's edge if the value of the edge width is 1. The gmsTRectTextConstraint( ) function sets the text constraint attribute on a single Text Rectangle object. The gmsLTRectTextConstraint( ) function sets the text constraint attribute for all Text Rectangle objects in a list. The gmsMTRectTextConstraint( ) function sets the modal text constraint attribute. The gmsQTRectTextConstraint( ) function returns the text constraint attribute of a given Text Rectangle object. SL-GML COMMANDS tconstraint index [name] tconstraint index Version 6.2a- 26 May 2006 SL-GMS Function Reference 410 Traps — signal handling Traps — signal handling SUMMARY modify the default signal-handling behavior of SL-GMS NAME gmsSetTraps( ), gmsTrapSignalMode( ), gmsQTrapSignalMode( ), gmsXKillTimer( ), gmsCrashHandlerFctn( ) SYNTAX int gmsSetTraps (workst) id workst; int gmsTrapSignalMode (mode) int mode; /* "trap signal" 0 - do not catch any signals 1 - catch signals and execute the "crash handler" */ int gmsQTrapSignalMode ( ) int gmsXKillTimer ( ) int gmsCrashHandlerFctn (fctn) int (*fctn)( ); /* "crash handler" function */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 411 Traps — signal handling DESCRIPTION The gmsSetTraps( ) function is called only once in an application program, and is called automatically by gmsMainInit( ). It can be called in an application without gmsMainInit( ) after creation of the first Workstation/Window. It is this first Workstation/Window that is passed to gmsSetTraps( ). The gmsSetTraps( ) function installs handlers for interrupt signals along with bus errors, segmentation violations, and bad system calls. If an application uses gmsSetTraps( ), SL-GMS calls its own interrupt handlers. Applications which have their own interrupt handlers use system-specific signal calls. For example, on UNIX 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: Default SL-GMS Behavior for Signals Signal SIGINT SIGQUIT SIGSEGV SIGBUS SIGILL SIGSYS Description print a and return to program essentially ignoring the signal print the message "... SL-GMS killed" and exit the program without creating a "core" file 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 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 Workstation Applications that use the X-Windows Workstation (non-toolkit, Xlib only) must take special care when disabling automatic SL-GMS signal handling. Version 6.2a- 26 May 2006 SL-GMS Function Reference 412 Traps — signal handling In order to provide timer events, SL-GMS starts a subprocess, gmstimer. If the application terminates abnormally, this subprocess is killed as part of the normal signal handling cleanup. If an application disables SL-GMS signal handling by calling gmsTrapSignalMode(0); the gmstimer subprocess must be killed by the application's signal-handling code. The gmsXKillTimer( ) function is provided for this purpose: int gmsXKillTimer ( )/* kill "gmstimer" process */ In addition, the gmsCrashHandlerFctn( ) function is provided to set up a "crash handler" function which is called before exiting. The crash handler function may attempt some kind of error recovery, before exiting. For example, SL-DRAW uses this to try to save the working Model before exiting (if the crash is non-fatal, i.e., it has not corrupted memory). The "crash handler" function must take a single argument which is the trapnum that caused the crash. A sample "crash handler" function is shown on the following page from SL-DRAW, attempting to save the working Model before exiting. static int dr_crash_handler (trapnum) int trapnum; { char *s; printf("... SL-DRAW crashing ... attempting to save work model.\n"); /* attempt to save the work Model */ gmsMSave(m_work, "DRAWCRASH"); Version 6.2a- 26 May 2006 SL-GMS Function Reference 413 Traps — signal handling /* 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 414 Update Update SUMMARY perform partial update or complete redraw of a View; set Immediate Update Mode or Deferred Update Mode NAME gmsUpdate( ), gmsUpdateExtents( ), gmsRedraw( ), gmsRedrawNoErase( ), gmsImmu( ), gmsDefu( ), gmsNoUpdImmu( ), gmsUpdateDisplayOnly( ), gmsUpdateEraseOnly( ) SYNTAX int gmsUpdate (view) id view; int gmsUpdateExtents (view) id view; int gmsRedraw (view) id view; int gmsRedrawNoErase (view) id view; int gmsImmu( ) int gmsDefu( ) int gmsNoUpdImmu( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 415 Update int gmsUpdateDisplayOnly (view) id view; int gmsUpdateEraseOnly (view) id view; DESCRIPTION The update functions control the way in which the SL-GMS system or specified Views are erased and redrawn. Updating involves the calculation of object extents (used for clipping objects), erasing objects if they are marked for erase, drawing objects if they are marked for display, and then clearing the update flags on objects. In these functions, if a nil pointer is given where a View is expected, the function is applied to all Views in the Graphical Modeling Hierarchy. The gmsUpdate( ) function causes visible objects that are internally marked for erase or display to be erased, if necessary, and drawn on active Workstation/Windows. This function is used to update only those objects that have been changed in a way that requires them to be redrawn. Objects are automatically marked internally for erase or display when they are created, freed, transformed, or their attributes are changed. The gmsUpdateExtents( ) function does a "true" update by recalculating (updating) the extents of objects marked for update in the given View without redrawing anything. The gmsRedraw( ) function is used to redraw all objects in a View regardless of whether they have changed (been marked for erase or display). The gmsRedrawNoErase( ) function redraws a View on a Workstation/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 the gmsImmu( ) function or into Deferred Update Mode with the gmsDefu( ) function. If in Immediate Update Mode, any change to an object results internally in the immediate issue of a gmsUpdate( ) function call. Calling gmsImmu( ) implicitly forces a gmsUpdate( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 416 Update call. In Deferred Update Mode, no update occurs until explicitly called for by gmsUpdate( ) in an application program. Deferred Update Mode is the SL-GMS default. The gmsNoUpdImmu( ) function is used to put SL-GMS into Immediate Update Mode, without actually triggering an update. The gmsUpdateDisplayOnly( ) function updates a View by displaying objects marked for display on all Workstation/Windows. If no View is given, all Views are updated. The gmsUpdateEraseOnly( ) function updates a View by erasing objects marked for erase on all Workstation/Windows. If no View is given, all Views are updated. SEE ALSO gmsClear( ), gmsClip( ) SL-GML COMMANDS [name] update [name] clear [name] redraw immu defu Version 6.2a- 26 May 2006 SL-GMS Function Reference 417 User-defined functions User-defined functions SUMMARY add or remove a user-defined function that may be used in dynamic descriptions NAME gmsAddUserFctn( ), gmsRemUserFctn( ) SYNTAX int gmsAddUserFctn (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 */ int gmsRemUserFctn (name, addr) char *name; /* function name */ void (*addr)( );/* function address */ DESCRIPTION Functions from a user’s application can appear in expressions and as the argument to the dynamic action call. The key to using user-defined functions is identifying them to SL-GMS. SL-GMS maintains an internal table of user-defined functions, along with the necessary information for handling arguments and return values. The gmsAddUserFctn( ) function performs the setup of the internal table. The return code is 1 when the user-defined function is added to the table. If unable to add the user-defined function to the table, 0 is returned. There is no limit to the number of entries allowed in the internal table. Version 6.2a- 26 May 2006 SL-GMS Function Reference 418 User-defined functions The function name, name, is the string as used in dynamic descriptions. It can be any string that begins with a letter, provided that the string does not conflict with the name of SL-GMS dynamic actions (listed in the table Dynamic Actions in the chapter Dynamics Referenceof the SL-GMS Quick Reference) or other variables in the application. A conflict with a reserved dynamic action name prevents the gmsAddUserFctn( ) call from succeeding, for example, defining a function named rotate would not be successful. The address of the function, addr, is obtained by declaring the function earlier in the program and using the name of the function in the gmsAddUserFctn( ) call. The user function return type, rtype, is taken from the table of type codes defined in the description of the gmsVarDefine( ) function on page 110. The argument count, argcnt, specifies the number of calling arguments and the argument types are set in an array, argtypes. For example, if there are two calling arguments, both of type integer, the argcount would be 2 and the array would have two elements, all G_INTEGER. EXAMPLE The 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 gmsAddUserFctn( ) function is used. be used to SL-GMS, the #include “gmscodes.h” ... double MyFunc( ); static int argtypes[] = { G_INTEGER, G_INTEGER}; if (!gmsAddUserFctn("MyFunc", MyFunc, G_DOUBLE, 2, argtypes)) fprintf(stderr,"Unable to add function to internal table.\n"); The "gmscodes.h" file is distributed in the lib directory. Version 6.2a- 26 May 2006 SL-GMS Function Reference 419 User-defined functions An SL-GMS-internal function, userfctns_initialize( ), is called automatically by gmsSetup( ) to allow users to install their application functions as part of SL-GMS and callable from DynProps. The userfctns_initialize( ) function is available to users as a convenience so that the main( ) routine of an application does not have to be changed whenever the user wishes to add, delete, or change user-defined functions. To utilize userfctns_initialize( ), a "userfctns.c" module is created by the user and contains the user’s own userfctns_initialize( ) function. Inside this function, all of 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 int user_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 */ int userfctns_initialize ( ) { Version 6.2a- 26 May 2006 SL-GMS Function Reference 420 User-defined functions gmsAddUserFctn("user_test", user_test, G_INTEGER, 2, args_int_doub); return 1; } The "userfctns.c" module is recompiled to produce "userfctns.o" and then relinked with SL-DRAW2, SL-DRAW, and/or SL-GML. The gmsRemUserFctn( ) function allows users to delete user-defined functions from the SL-GMS internal table of user-defined functions. Either the name of the function to be removed, its address, or both can be passed to gmsRemUserFctn( ). A return value of 1 indicates that the function has been deleted and all memory associated with it has been freed. A return value of 0 indicates that the deletion was unsuccessful. After the user functions have been removed, no Models should be active that have these functions used in DynProps. SEE ALSO gmsVarDefine( ) The chapter entitled Dynamicsin the SL-GMS Reference Version 6.2a- 26 May 2006 SL-GMS Function Reference 421 UserData and UserWord UserData and UserWord SUMMARY set or query the UserData or UserWord associated with an object NAME gmsUserData( ), gmsLUserData( ), gmsQUserData( ), gmsUserWord( ), gmsQUserWord( ) SYNTAX int gmsUserData (obj, string) id obj; char * string; int gmsLUserData (objlist, string) idLinkRef objlist; char *string; char * gmsQUserData (obj) id obj; int gmsUserWord (obj, word) id obj; long word; long gmsQUserWord (obj) id obj; Version 6.2a- 26 May 2006 SL-GMS Function Reference 422 UserData and UserWord DESCRIPTION The gmsUserData( ) function sets the UserData string associated with an object. UserData is intended as a method under the application’s control for adding arbitrary information to Graphical Primitive objects. The only restriction for UserData is that it must be a C string. The maximum length of a UserData string is 16,384 characters. The gmsLUserData( ) function sets the UserData string for all objects on a List of objects. The gmsQUserData( ) function returns the UserData string associated with a Graphical Primitive object, or null if there is no string. The gmsUserWord( ) function sets an object’s UserWord. The UserWord is an integer that is associated with an object for arbitrary use 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 423 View — miscellaneous View — miscellaneous SUMMARY set or clear the locator capture mode for a View; return the locator capture mode for a View; delay redraw NAME gmsVuLocCaptureMode( ), gmsQVuLocCaptureMode( ), gmsVuRedrawOnNextUpdate( ) SYNTAX int gmsVuLocCaptureMode (view, mode) idG_VIEW view; int mode; int gmsQVuLocCaptureMode (view)mode for view */ idG_VIEW view; int gmsVuRedrawOnNextUpdate(view) id view;/* GMS view */ DESCRIPTION The gmsVuLocCaptureMode( ) function sets or clears the locator capture mode for a View. When the argument mode is set to 1, locator capture is enabled on the View. When the argument mode is set to 0, locator capture is disabled on the View. By default, locator capture is disabled on View objects. Locator capture mode causes locator press-drag-release interactions to be grouped together and delivered to a single View, even if the locator is moved outside of the window before the button is released. Version 6.2a- 26 May 2006 SL-GMS Function Reference 424 View — miscellaneous When locator capture mode is set and a locator press event occurs in the View, all subsequent locator events are delivered to the View until a locator release event occurs. The loc_motion and loc_release events are delivered to the View even if the locator is outside of the window in which the loc_press event occurred. The gmsQVuLocCaptureMode( ) function returns the locator capture mode for a View. The gmsVuRedrawOnNextUpdate( ) function will notify a View that all of 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 delayed redraw to be forced. One example where the gmsVuRedrawOnNextUpdate( ) function might be used is if gmsWindXY( ) is called and extra processing is done after the gmsWindXY( ) call. After the extra processing, gmsUpdate( ) is called. The function gmsWindXY( ) requires a redraw, but this isn't guaranteed to be done unless gmsRedraw( ) is called because calling gmsUpdate( ) doesn't guarantee a redraw. However, calling gmsRedraw( ) could cause two redraws instead of one because the gmsUpdate( ) call could redraw. This type of situation is solved by calling gmsVuRedrawOnNextUpdate( ) instead of gmsRedraw( ). In this case the next gmsUpdate( ) call is guaranteed to do a redraw. SEE ALSO gmsUpdate( ), gmsWindXY( ), gmsRedraw( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 425 View — object View — object SUMMARY create or end a new View; set current View; set View priority; return View dimensions; enable/disable segments; set Workstation/Window number; set Clip Mode and Resolution Check Mode NAME gmsView( ), gmsEndView( ), gmsVuPri( ), gmsVuList( ), gmsVuDim( ), gmsWsNum( ), gmsClip( ), gmsWsSoftClip( ), gmsResChk( ), gmsVuWorkst( ) SYNTAX id gmsView (name, modlist) char *name; idLinkRef modlist; int gmsEndView( ) int gmsVuPri (view1, view2) id view1; id view2; idLinkRef gmsVuList( ) int gmsVuDim (view, p1, p2) id view; idPoint p1; idPoint p2; Version 6.2a- 26 May 2006 SL-GMS Function Reference 426 View — object int gmsWsNum (view, number) id view; int number; int gmsClip (view, clipflag) id view; int clipflag; int gmsWsSoftClip(ws, action) id ws; int action; /* G_ON or G_OFF */ int gmsResChk (view, resflag) id view; int resflag; int gmsVuWorkst (view, workst) id view; id workst; DESCRIPTION The gmsView( ) function is used to create a View with default characteristics and add it to the Graphical Modeling Hierarchy with the name given. This function may be called with a List of Models which are to go into the View as it is created. The created View becomes the current View. The gmsEndView( ) function terminates the current View, leaving SL-GMS with no current View. Any additional Models created (while no Model is current) forces a new default View to be created. The gmsVuPri( ) function sets View priority. The View specified by view1 receives higher priority than view2. Higher priority Views are displayed after, and on top of lower priority Views. Thus, in the case of overlapping Views, the highest priority View is specified by a LocEvent Version 6.2a- 26 May 2006 SL-GMS Function Reference 427 View — object input Event (such as selecting a View with a mouse or passing a LocEvent to gmsFindObject( )). The gmsVuList( ) function returns the current List of Views in the priority order in which they are displayed. A pointer to the actual View List maintained internally by SL-GMS is returned, so this List should never be modified directly. The gmsVuList( ) function is for reference only. The gmsVuDim( ) function sets the two Points in the argument list to the x and y dimensions of the given View. This action is useful after zooming has changed the size of the View. The gmsWsNum( ) function is used to change the Workstation/Window number for the given View object or the default View. The default Workstation/Window number for a View object is 0. Each Workstation/Window object is added to the System object’s List of Workstation/Windows after it is created. The first Workstation/Window object created has the index of 0, which is identical to Workstation/Window number 0. Therefore, by default, all Views are associated (and are displayed in) Workstation/Window number 0. If another Workstation/Window object is added, the Workstation/Window number of a View object is changed to associate the View with the new Workstation/Window. The second Workstation/Window added has Workstation/Window number 1, the third, number 2, and so on. Many Views may be associated with the same Workstation/Window, but only one Workstation/Window may be associated 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: Mode 1 2 Description always clip automatic, or smart, clipping 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 the clip function. If the object is either entirely outside or inside the View, Version 6.2a- 26 May 2006 SL-GMS Function Reference 428 View — object there is no need to clip; only when the object straddles the View does clipping become necessary. The gmsWsSoftClip( ) function toggles software clipping flags on a workstation. If the software clipping flag is set to G_ON, the workstation will clip all line coordinates to the rectangle defined by the pixel coordinates (-16521, -16490) and (16255, 16277). Currently, this functionality works on X workstations and causes only lines to be clipped. Although a slight performance decrease occurs when software clipping is used, it can prevent display anomalies which happen when SL-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 for display. id workst; workst=gmsQStWorkst(gmsStFindByName(“zoompan_state”)) ; gmsWsSoftClip(workst, G_ON); The gmsResChk( ) function sets the Resolution Check Mode for the View. If set to 0, there is no check performed. If set to 1, the extent of an object is checked prior to drawing, and a single Point or a small box is drawn if the extent is .3% of the View. Setting the mode to 1 somewhat speeds up the drawing. Both automatic clipping and resolution check introduce the overhead associated with carrying around an extent for each object. If neither is set, no extents need be calculated. If the gmsFindObject( ) function is called, however, the View specified by the locator argument causes extents to be calculated for all objects in that View. The gmsVuWorkst( ) function sets a Workstation/Window id for a View. SEE ALSO gmsWind( ), gmsZoom( ), gmsFindObject( ), gmsWorkst( ), gmsQCurView( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 429 View — object SL-GML COMMANDS [name:] view [modlist] endview name current name segments name clip int name reschk int Version 6.2a- 26 May 2006 SL-GMS Function Reference 430 View — WC-window and Viewport View — WC-window and Viewport SUMMARY set the WC-window and Viewport limits for a View NAME gmsWind( ), gmsPort( ), gmsWVXY( ), gmsWinPts( ), gmsWindXY( ), gmsPortXY( ) SYNTAX int gmsWind (view, p1, p2) id view; idPoint p1; /* World Coordinate Points */ idPoint p2; int gmsPort (view, p1, p2) id view; idPoint p1; /* Normalized Device Coordinates */ idPoint p2; int gmsWVXY (view, x1, y1, x2, y2) id view; double x1; /* World Coordinates */ double y1; double x2; double y2; int gmsWinPts (view, p1, p2) id view; idPoint p1; /* World Coordinate Points */ idPoint p2; Version 6.2a- 26 May 2006 SL-GMS Function Reference 431 View — WC-window and Viewport int gmsWindXY (view, x1, y1, x2, y2) id view; double x1; /* World Coordinates */ double y1; double x2; double y2; int gmsPortXY (view, x1, y1, x2, y2) id view; double x1; /* Normalized Device Coordinates */ double y1; double x2; double y2; DESCRIPTION These functions make changes to View objects. The gmsWind( ) and gmsPort( ) functions change the current or designated View’s WC-window and Viewport values. If the view argument is nil, these functions apply to the current View, otherwise they apply to the View given. The point arguments must be pointers to Point objects. The gmsWind( ) function arguments are created by the gmsWPXY( ) function since they are in World Coordinates. Only Points and objects that are within the limits of the WC-window are displayed in the View. The gmsWind( ) and gmsWVXY( ) functions set the WC-window using the parameters given for Points, and automatically recalculate the Viewport. The Viewport is automatically calculated as (0.0, 0.0), (1.0, aspect) where: y2 – y1 aspect = ------------------x2 – x1 Version 6.2a- 26 May 2006 SL-GMS Function Reference 432 View — WC-window and Viewport and (x1, y1), (x2, y2) are in World Coordinates. ratio is a 3:4 ratio of height to width. The standard aspect The gmsWVXY( ) function converts the given coordinates to Point objects before calling gmsWind( ), and frees the Point objects before returning. The gmsWinPts( ) function creates a WC-window without changing the Viewport (unlike gmsWind( ), which does change the Viewport). The gmsWindXY( ) function converts the coordinate arguments to Point objects before calling gmsWinPts( ), and frees the Point objects before returning. The gmsWinPts( ) function creates a View if nil is passed as an argument for the View. The Points for the gmsPort( ) function should be created by the gmsNPXY( ) function, as they must be in Normalized Device Coordinates. These Viewport coordinates select the portion of the idealized device surface in which the WC-window for the View is displayed. The gmsPortXY( ) function converts the coordinate arguments to Normalized Device Coordinate Points before calling gmsPort( ), and frees the Point objects before returning. SEE ALSO gmsView( ), 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 433 View — zoom and pan View — zoom and pan SUMMARY zoom or pan a View and reset zoom and pan status NAME gmsZoom( ), gmsZmIn( ), gmsZmOut( ), gmsPan( ), gmsZpr( ), gmsZps( ) SYNTAX int gmsZoom (view, p1, p2) id view; idPoint p1; idPoint p2; int gmsZmIn (view) id view; int gmsZmOut (view) id view; int gmsPan (view, point) id view; idPoint point; int gmsZpr (view) id view; int gmsZps (view) id view; Version 6.2a- 26 May 2006 SL-GMS Function Reference 434 View — zoom and pan DESCRIPTION These functions make changes to View objects. The four functions, gmsZoom( ), gmsZmIn( ), gmsZmOut( ), and gmsPan( ) make temporary changes to the WC-window. The gmsZpr( ) function resets the View after any of the four temporary change functions are used. The gmsZps( ) function is used to make the temporary WC-window change permanent by applying the zoom or pan directly to the View’s WC-window coordinates. By default, the gmsZmIn( ) and gmsZmOut( ) functions use the factors 1.618 and 0.618 (the golden mean) to calculate the new WC-window limits. SEE ALSO gmsView( ), gmsWind( ) SL-GML COMMANDS [name] zoom x y x y [name] zoomin [name] zoomout [name] pan x y [name] zpr [name] zps Version 6.2a- 26 May 2006 SL-GMS Function Reference 435 Visibility and detectability attributes Visibility and detectability attributes SUMMARY set the visibility and detectability attributes NAME gmsVis( ), gmsLVis( ), gmsMVis( ), gmsDetect( ), gmsLDetect( ), gmsMDetect( ), gmsQDetect( ), gmsQVis( ) SYNTAX int gmsVis (obj, visflag) id obj; int visflag; int gmsLVis (objlist, visflag) idLinkRef objlist; int visflag; int gmsMVis (visflag) int visflag; int gmsDetect (obj, detflag) id obj; int detflag; int gmsLDetect (objlist, detflag) idLinkRef objlist; int detflag; int gmsMDetect (detflag) int detflag; Version 6.2a- 26 May 2006 SL-GMS Function Reference 436 Visibility and detectability attributes int gmsQDetect (obj) id obj; int gmsQVis (obj) id obj; DESCRIPTION The gmsVis( ) function is used to set the visibility on SL-GMS Graphical Primitive objects or Views. The possible values are: Value 0 1 2 3 Description invisible visible highlighted visible, force redraw Setting the visibility to 3 also sets the display flag on the object, which forces 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. visibility attributes are the same as for the gmsVis( ) function. The gmsMVis( ) function sets newly-created Graphical Primitives. the modal visibility, The affecting The gmsDetect( ) function is used to set the detectability of Graphical Primitive objects or Views.. If set to 0, the object is not detectable; if set to1, it is detectable. Non-detectable objects can be retrieved with the 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 all subsequently-created Graphical Primitive objects. The query functions return the visibility or detectability of a Graphical Primitive object. The gmsQDetect( ) function also returns the modal Version 6.2a- 26 May 2006 SL-GMS Function Reference 437 Visibility and detectability attributes 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. DIAGNOSTICS The gmsVis( ) function does not yet support visflag = 2. the function in hardware does not exist. Support for SEE ALSO gmsFindByName( ) SL-GML COMMANDS name vis visflag name detect detflag Version 6.2a- 26 May 2006 SL-GMS Function Reference 438 Workstation/Window — attribute changes 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 int gmsWinBannerName (workst, name) id workst; /* Workstation/Window */ char *name; /* Window banner name */ int gmsWinClear (workst) id workst; /* Workstation/Window */ int gmsWinDestroy (workst) id workst; /* Workstation/Window */ int gmsWindowDestructionFctn (cb_fctn) int (*cb_fctn)();/* callback function */ int gmsWinExt (workst, lower_left, top_right) id workst; /* Workstation/Window */ idPoint lower_left/* corner of Window extent */ idPoint top_right;/* corner of Window extent */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 439 Workstation/Window — attribute changes int gmsWsWind (workst, p1, p2) id workst; /* Workstation/Window */ idPoint p1; /* NDC Point */ idPoint p2; /* NDC Point */ int gmsWsWindXY (workst, id workst; double x1; double y1; double x2; double y2; x1, y1, x2, y2) /* Workstation/Window */ /* NDC Point */ /* NDC Point */ /* NDC Point */ /* NDC Point */ int gmsWsPort (workst, lower_left, upper_right) id workst; /* Workstation/Window */ idPoint lower_left; /* DC Point */ idPoint upper_right; /* DC Point */ int gmsWsPortXY (workst, id workst; double x1; double y1; double x2; double y2; x1, y1, x2, y2) /* Workstation/Window */ /* DC Point */ /* DC Point */ /* DC Point */ /* DC Point */ int gmsWinFlags (workst, id workst; int bit; int onoff; bit, onoff) /* Workstation/Window */ /* flag bit to be set */ /* onoff = G_ON or G_OFF */ int gmsWinIconName (workst, name) id workst; /* Workstation/Window */ char *name; /* icon name */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 440 Workstation/Window — attribute changes int gmsWinMap (workst, raiseflag) id workst; /* Workstation/Window */ int raiseflag; /* raiseflag = G_ON/G_OFF */ int gmsWinPop (workst) id workst; /* Workstation/Window */ int gmsWinPush (workst) id workst; /* Workstation/Window */ int gmsWinSetFocus (workst, window) id workst; /* Workstation/Window */ id window; /* X window widget handle */ int gmsWinUnmap (workst) id workst; /* Workstation/Window */ DESCRIPTION The gmsWinBannerName( ) function stores name in the Workstation/Window’s banner name field and displays the name in the Workstation/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 the changed Workstation/Window; the gmsWsClose( ) function should be used instead. The gmsWindowDestructionFctn( ) function will register a window destruction callback function, cb_fctn( ), with SL-GMS. The callback function will be called for externally created windows at the point where SL-GMS normally destroys its own window associated with a workstation. The application is free to destroy or not destroy the Version 6.2a- 26 May 2006 SL-GMS Function Reference 441 Workstation/Window — attribute changes window/widget, perhaps reusing it for another call to gmsWorkst( ). However, the workstation parameter passed to cb_fctn( ) should not be referenced again. For Windows NT applications, cb_fctn( ) would be declared as follows. int cb_fctn (workst, window) id workst; HWND window; { /* function body */ } For X Windows applications, cb_fctn( ) would be declared as follows. int cb_fctn (workst, display, window) id workst; Display *display; Window window; { /* function body */ } Xt applications may need to use the macro XtWidget(window) to find the widget associated with workst. The gmsWinExt( ) function sets the Workstation/Window extent (size) in Device Coordinates (usually pixels). The two idPoint arguments represent the lower left and top right corners of the Workstation/Window. This function returns 1 for success, 0 for failure. The Workstation/Window is resized immediately when this function is called. The workst argument of the gmsWinExt( ) function can be either an existing Workstation/Window object or a Workstation/Window class retrieved by the gmsQDefaultWs( ) function. If a Workstation/Window class is passed, then the attributes of the Exemplar object are set (which sets the attributes of all subsequent Workstation/Windows opened). Version 6.2a- 26 May 2006 SL-GMS Function Reference 442 Workstation/Window — attribute changes NOTE: The gmsWinExt( ) function supersedes the obsolete gmsWinDims( ) function. The gmsWsWind( ) function sets the Workstation/Window Virtual-window using Normalized Device Coordinate Points. The gmsWsWindXY( ) function sets the Virtual-window for the Workstation/Window using the given Normalized Device Coordinates. The gmsWsPort( ) function modifies the Port using Point objects containing Device Coordinates (pixel coordinates). The gmsWsPortXY( ) function modifies the Port using the given Device Coordinates (pixel coordinates). The gmsWinFlags( ) function turns a Workstation/Window’s bit flags to G_ON or OFF. The bits are: gmsWinFlags( ) — Valid Codes for "bit" Argument Code Description G_WIN_CONCAVE_FILL Use SL concave-fill algorithm (SGI-IRISGL only) G_WIN_DESTROYED Window has been destroyed G_WIN_DBUFF_ERASE Erase Update Double Buffer Mode G_WIN_DBUFF_CLEAR Clear Redraw Double Buffer Mode G_WIN_FULL_SCREEN Adjust Window size to use full screen G_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/banner G_WIN_NOPASTE Disable middle mouse button for control of cut and paste communication G_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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 443 Workstation/Window — attribute changes The gmsWinIconName( ) function stores name in the Workstation/Window’s icon name field; this name is displayed in the window-manager window’s icon when the window-manager window is iconized. The gmsWinMap( ) function maps the Workstation/Window (makes it visible). If raiseflag is set to G_ON, the function brings it to the top of the Workstation/Window stack. For the SGI-IRISGL version, this is equivalent to gmsWinPop( ). For Windows workstations the gmsWinMap( ) function behaves as follows: Version 6.2a- 26 May 2006 SL-GMS Function Reference 444 Workstation/Window — attribute changes : 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 action call gmsWinMap(ws, G_OFF) result Workstation/Window position restored; the window that had focus retains it Case 5 before Workstation/Window minimized (visible or invisible) action call gmsWinMap(ws, G_OFF) Version 6.2a- 26 May 2006 SL-GMS Function Reference 445 Workstation/Window — attribute changes result Workstation/Window moved next to top of z-order; the window that had focus is made top and retains focus The gmsWinPop( ) function raises the Workstation/Window to the top of the Workstation/Window stack. The gmsWinPush( ) function lowers the Workstation/Window to the bottom of the Workstation/Window stack. For Windows workstations the function behaves as follows: 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 gmsWinSetFocus( ) function sets the keyboard input focus to the specified Workstation/Window. If window is nil, the Workstation/Window’s default Window is used. For the SGI-IRISGL version, this function changes the Workstation/Window to the "current drawing Window." Version 6.2a- 26 May 2006 SL-GMS Function Reference 446 Workstation/Window — attribute changes 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 447 Workstation/Window — background color Workstation/Window — background color SUMMARY set and query the window background color for a workstation NAME gmsQWsBackgroundColor( ), gmsWsBackgroundColor( ) SYNTAX int gmsQWsBackgroundColor(workst, color, platform_flag) id workst; /* Workstation/Window */ int *color; /* return color */ int *platform_flag;/* return flag indicating platform color */ int gmsWsBackgroundColor(workst, index, type) id workst; /* Workstation/Window */ int color; /* SL-GMS color index or platform color */ int type; /* background color type to */ use DESCRIPTION The gmsWsBackgroundColor( ) function is used to set the Window background color for the indicated Workstation. It also sets the default Model background color. Three different types can be used to specify the background color: index, color, and system (type codes G_BKGR_TYPE_INDEX, G_BKGR_TYPE_COLOR, and G_BKGR_TYPE_SYSTEM). G_BKGR_TYPE_INDEX sets the background color to the specified SL-GMS color index. G_BKGR_TYPE_COLOR sets the background color to a platform-specific color (i.e., a COLORREF or Pixel). G_BKGR_TYPE_SYSTEM sets the background color to the window manager-defined Window background color (not supported Version 6.2a- 26 May 2006 SL-GMS Function Reference 448 Workstation/Window — background color under X Windows). For the system type, the color parameter is ignored, however, it is recommended that G_TCOLOR_NULL be used. A return value of 1 indicates success and 0 indicates failure. If G_BKGR_TYPE_SYSTEM is used under X Windows, a failure code of 0 will be returned. The gmsQWsBackgroundColor( ) function will return the current background color for the indicated Workstation in the color variable. If the returned color is a platform-specific representation, a 1 is returned in the platform_flag. Otherwise, the returned color is an SL-GMS color index and a 0 is returned in platform_flag. The color will be a platform-specific color only if the background color was set with a platform-specific color. This will happen if a Window is created with a background color (on Windows NT) and passed in to gmsWorkst( ) or a platform-specific color is passed to gmsWsBackgroundColor( ). A return value of 1 indicates success and 0 indicates failure. NOTE: The private global variable g_backgrcolor, used to control the background color, has been removed. The new background color functions provide the necessary access to a workstation’s background color. The Window/Model will not be redrawn automatically after the background color is changed. The background color will follow the definition of the color index to which 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 is blue. If the color for index 4 is then changed to pink, the background color will change to pink also. However, the pink background will not automatically display. Some action must be taken to force the screen to redraw. For Windows NT only, the background color for a Workstation/Window may also be set by creating a window manager Window outside of SL-GMS. The color of the background brush stored in the window class will determine the background color for SL-GMS. SL-GMS gets the background brush when the Window is passed to gmsWorkst( ). Only a solid brush will work; any other type of brush will cause SL-GMS to use the default background color. Version 6.2a- 26 May 2006 SL-GMS Function Reference 449 Workstation/Window — background color On X Windows, if a Window is passed in to gmsWorkst( ), SL-GMS does not determine the background color from it. Because of this, the value obtained from gmsQWsBackgroundColor( ) is undetermined unless the background color is set by calling gmsWsBackgroundColor( ). If a Workstation/Window is created by SL-GMS (not passed in), and the function gmsWsBackgroundColor( ) is not called, the background color is set to the SL-GMS color index 0. Version 6.2a- 26 May 2006 SL-GMS Function Reference 450 Workstation/Window — bitplanes Workstation/Window — bitplanes SUMMARY implement bitplane masking NAME gmsWsBitplaneMask( ), gmsWsColDef( ), gmsQWsBitplaneMask( ) SYNTAX int gmsWsBitplaneMask (workst, mask, color0) id workst; /* Workstation/Window */ int mask; /* bitplane writemask */ int gmsWsColDef (workst, id workst; int index; double red; double green; double blue; int mask; index, red, green, blue, mask) /* Workstation/Window */ /* color index */ /* red color component*/ /* green color component */ /* blue color component */ /* bitplane writemask */ int gmsQWsBitplaneMask (workst) id workst; /* Workstation/Window */ DESCRIPTION Bitplane masking is a feature that is used to load a Model into a View that is associated with a set of protected bitplanes and a set of colors. Bitplane masking also provides transparency for color index 0 in each set of bitplanes. Situations in which bitplane masking is useful include: Version 6.2a- 26 May 2006 SL-GMS Function Reference 451 Workstation/Window — bitplanes 1. Objects move over a complex background such as a map. Bitplane masking increases performance because the map is not redrawn each time an object moves over it. 2. A set of Models that must appear to be transparent when stacked on top of each other. If an object that is filled with a pattern has background areas of color index 0, the background areas of the fill pattern allow portions of underlying objects to show through the holes in the fill pattern. Version 6.2a- 26 May 2006 SL-GMS Function Reference 452 Workstation/Window — bitplanes 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 software double-buffering. When a background object of color 0 is grouped with another object that moves, the background object will be invisible if the Group is loaded into a set of bitplanes. Bitplane masking is activated with the G_WS_PLANE_MASKING Workstation option. The gmsWsBitplaneMask( ) function sets the Workstation/Window’s writemask. Setting the bitplane writemask provides the capability of drawing objects in specified bitplanes. The gmsWsColDef( ) function sets a Workstation/Window color map entry for the given index, with the given bitplane writemask, mask. A 0 mask 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-IRISGL writemask call, and is saved as the "current bitplane mask." For convenience, a writemask of 0 is construed as 0xffffff, that is, no writemask. 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 Version 6.2a- 26 May 2006 SL-GMS Function Reference 453 Workstation/Window — bitplanes bitplane writemask for which the color is being set. index is the color index. The color index is adjusted according to the bitplane mask. If the index is a number not in the mask, it is adjusted to be a range within 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 vary according to the color in the lower bitplanes. The gmsQWsBitplaneMask( ) Workstation/Window’s writemask. function returns the EXAMPLE workst_options = G_WS_PLANE_MASKING; gmsWsDefaultOpts(workst_options); Then, the "colordef.dat" file is modified to define the desired groups of bitplanes and their associated colors. The writemask is defined in the fifth field of a "colordef.dat" line as an integer in either binary or hexadecimal form. The writemask must contain exactly one consecutive string of 1-bits, for example "11100000." Note that the number 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. "transparent" for all but "back" bitplanes. Color 0 is "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 2 0.0 0.0 Version 6.2a- 26 May 2006 0.0 0.6 0.0 1.0 00000011 0x3 black map lines blue background SL-GMS Function Reference 454 Workstation/Window — bitplanes colors for middle three planes (could have maximum of 7 colors + 1 for transparency) for the satellite 1 2 3 4 5 6 1 0 0 00011100 .5803920.3 0 00011100 .6 .6 .6 00011100 .996078.684314.73921600011100 .946667.763137.21372500011100 0. 0.0 0.0 0x1c red brown gray pink tan black colors for front three planes (could have maximum of 7 colors + 1 for transparency) for the elipsoid fill pattern area 1 2 3 0.0 0.0 1.0 0.0 1.0 0.0 0.0 0.0 1.0 0xe0 11100000 0xe0 black green purple In the above example there are three writemasks. The first writemask uses two bitplanes for a total of four colors. The second and third writemasks each use 3 bitplanes for a total of seven colors each. The total number of possible colors for the example "colordef.dat" is 18 of which 11 are defined. "colordef.dat" file — sample 2 (8 plane display) 0 1 2 3 4 5 6 7 8 9 10 11 0.0 1.0 0.0 0.1 0.5 0.3 0.4 1.0 0.0 1.0 0.0 0.5 Version 6.2a- 26 May 2006 0.0 1.0 0.0 0.2 0.5 0.3 0.4 1.0 0.0 1.0 0.0 0.25 0.0 1.0 1.0 0.3 0.5 0.3 0.4 1.0 0.0 1.0 1.0 0.0 black medium grey SL-GMS Function Reference 455 Workstation/Window — bitplanes colors for front (panel) planes (could have maximum of 7 colors + 1 for transparency) 1 2 3 4 5 6 7 1.0 0.0 0.1 0.5 0.3 0.4 1.0 0.0 0.0 0.2 0.5 0.3 0.4 1.0 0.0 0.0 0.3 0.5 0.3 0.4 1.0 11100000 0xe0 0xe0 0xe0 0xe0 0xe0 0xe0 red black dark blue-grey grey grey grey white The second example "colordef.dat" file is from the avionics on-line example.1 The avionics "colordef.dat" file uses one writemask that occupies the front three bitplanes which leaves five bitplanes for normal use. Five bitplanes allow 32 colors of which 11 are defined. The avionics "colordef.dat" file also changes the color of index 0 from its default 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 that begins with "_vm" and ends with the hexedecimal value of the writemask. For example, a View named "_vm_map_0xe0" is drawn with the writemask "0xe0". Typically, as each View is created, the Models for the View are loaded. 1. The avionics on-line example is available only on the SGI-IRISGL platform. Version 6.2a- 26 May 2006 SL-GMS Function Reference 456 Workstation/Window — bitplanes EXAMPLE back_mask = 0x3; front_mask = 0xe0; prefix = "_vm"; /* setup view with back write mask */ 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 displays that support only one hardware color map (a color map is a table that relates pixel values to screen colors). As an SL-GMS application that uses bitplane masking is started, other windows on the display may change color as they are forced to use the SL-GMS color map. EXAMPLE The following function calls can be used to cause the red rubber-banding echo and the black/white popup menus to be drawn in an overlay (a masked set of bitplanes). As an example, if bitplanes 6 and 7 are used for overlays, assuming 8 bitplanes, the mask would be 0xc0. At initialization the color map for these bitplanes is set: Version 6.2a- 26 May 2006 SL-GMS Function Reference 457 Workstation/Window — bitplanes 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, the menu 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. "transparent." Color 0 is When an SL-GMS bitplane writemask is in effect, all color indexes are interpreted as being in the bitplanes specified by the current writemask. A color index below the writemask is transformed up; a color index above the writemask is set to the last overlay color in the writemask. Views with bitplane masking Bitplane masking is implemented in SL-GMS by adding the capability to the View object, as well as by the functions described above. A View can contain a bitplane writemask; if a writemask is present, the View sets the bitplane writemask before drawing. In the present implementation of SL-GMS 5.x, the bitplane writemask is temporarily put in the View name field, using the following convention: if the View name begins with "_vm" then it contains a writemask; the writemask is a substring beginning with "0x" at the end of the View name. For example, a View named "_vm_panel0xe0" is drawn with the writemask "0xe0." The avionics on-line example provides source and executables that illustrate the use of double-buffering and bitplane masking in SL-GMS. This on-line example uses front bitplanes for the "panel" Model. DIAGNOSTICS If a Workstation/Window having overlay objects drawn is moved or uncovered, the objects are redrawn subject to the writemask in force at Version 6.2a- 26 May 2006 SL-GMS Function Reference 458 Workstation/Window — bitplanes the time of the redraw; the result may be that overlay objects are drawn in the normal planes. Version 6.2a- 26 May 2006 SL-GMS Function Reference 459 Workstation/Window — coordinate conversion Workstation/Window — coordinate conversion SUMMARY convert a point in Device Coordinates to SL-GMS Internal Coordinates NAME gmsWsPointDCToIC( ) SYNTAX int gmsWsPointDCToIC (workst, point) id workst; /* Workstation/Window */ idPoint point; /* point in Device Coords */ DESCRIPTION The gmsWsPointDCToIC( ) function converts a point in Device Coordinates (DC) to Internal Coordinates (IC) for a given Workstation/Window. The Internal Coordinates replace the Device Coordinates in the Point object provided to the function. DIAGNOSTICS The gmsWsPointDCToIC( ) function returns 0 for failure. EXAMPLE The mouse is moved to a location over an object in a Model and clicked. The window handle, and the location of the mouse in Device Coordinates, are provided by system-dependent event handlers. Find the object in the Model that is under the mouse. idPoint pt; id workst, locevent, vu, obj; ... /* Find Workstation/Window associated with system-dependent window handle */ workst = gmsQWorkst((unsigned long)window_handle); Version 6.2a- 26 May 2006 SL-GMS Function Reference 460 Workstation/Window — coordinate conversion /* Create a point object that contains the 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 ALSO gmsQWorkst( ), gmsQWsView( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 461 Workstation/Window — events Workstation/Window — events SUMMARY functions to set up Workstation/Window Event handlers or query Workstation/Window or timer Event masks NAME gmsWsEventFctn( ), gmsWsEventMask( ), gmsQWsEventMask( ), gmsWsTextEditObj( ), gmsWsKbdFilterFctn( ), gmsWsLowEventFctn( ), gmsNonWsLowEventFctn( ), gmsWsSynchronize( ) SYNTAX int gmsWsEventFctn (workst, eventcode, fctn) id workst; /* Workstation/Window which is to receive Event */ int eventcode; /* type of Event */ int (*fctn)( ); /* callback function to be invoked upon Event */ int gmsWsEventMask (workst, eventcode, action) id workst; /* Workstation/Window which is to receive Event */ int eventcode; /* type of Event */ int action; /* G_ENABLE or G_DISABLE */ int gmsQWsEventMask (workst, event_type) id workst; /* Workstation/Window which is to receive Event */ int event_type; /* type of Event */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 462 Workstation/Window — events int gmsWsTextEditObj (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 = G_MULTI_EVENT/G_ONE_SHOT/ G_ONE_SHOT_CLEAR */ int (*fctn)( ); /* callback function to be invoked upon Event */ int gmsWsKbdFilterFctn (workst, fctn) id workst; idLinkRef (*fctn)( ); int gmsWsLowEventFctn (workst, fctn) id workst; int (*fctn)( ); int gmsNonWsLowEventFctn (fctn) int (*fctn) ( ); int gmsWsSynchronize (workst) id workst; Version 6.2a- 26 May 2006 SL-GMS Function Reference 463 Workstation/Window — events DESCRIPTION The gmsWsEventFctn( ) function is invoked from an application program. This function sets up Event handlers on a per-Workstation/Window basis by passing the object pointer for the desired 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 Event codes, in the chapter Event Handling, of the SL-GMS Reference. If the fctn pointer passed is 0, 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 define an 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 doing so interferes with SL-SMS’ Event-handling capability. The gmsWsEventMask( ) function enables or disables a type of Event in the Workstation/Window Event mask. The gmsQWsEventMask( ) function returns the current Workstation/Window Event mask, either G_ENABLE or G_DISABLE. The gmsWsTextEditObj( ) function defines an object (textobj must be a Text or Text Rectangle object) as the echo object for Text input and editing. This function also becomes the focus for all KEY_PRESS Events and is responsible for dispatching a STR_DONE Event by executing the given callback function. This function should not be used in SL-SMS. The gmsWsTextEditObj( ) function sets up an Event-handler for String Events 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 characters to echo in the Text or Text Rectangle object, and is used to prevent overflow. Version 6.2a- 26 May 2006 SL-GMS Function Reference 464 Workstation/Window — events The promptstring and initstring arguments together define the text that will actually be displayed. The text displayed after a is determined by dispatch_mode. The dispatch_mode can have one of three valid values: 1. G_MULTI_EVENT — after promptstring and initstring; a redisplay 2. G_ONE_SHOT — after a do not redisplay promptstring and initstring (i.e., leave text that has been entered); 3. G_ONE_SHOT_CLEAR — after a do not redisplay promptstring and clear initstring (i.e., clear text that has been entered). The gmsWsKbdFilterFctn( ) function installs a Workstation/Window KeyEvent filter function. This function does not enable any Events. The gmsWsLowEventFctn( ) function is used to establish an Event-handler to intercept Workstation/Window Events before SL-GMS receives them. The gmsWsLowEventFctn( ) function registers a low-level Event-handler with SL-GMS. The registered function is given a chance to check each Event, and should return to SL-GMS a signed integer flag instructing SL-GMS on further processing of 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 To enable total application access to the Event Queue, four parameters are passed to the application’s low-level Event-handler: a pointer to the X Display structure, an X window id, a pointer to the XEvent union, and a flag indicating SL-GMS "intentions" for the Event. Version 6.2a- 26 May 2006 SL-GMS Function Reference 465 Workstation/Window — events Flag Value 1 normal 0 "flush" -1 "modified flush" Case Description 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. SL-GMS is attempting to "throw away" the Event. In some cases it may prove fatal for the application to try processing these Events. 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. The gmsProcessLowEvent( ) function is used to pass events to SL-GMS when an application event loop function external to SL-GMS is being used (flag value non-zero in the call to gmsExternalEventLoop( )). The gmsProcessLowEvent( ) function is system-dependent and is only used with the SL-GMS interface to Xt and X at present. Under Xt and X, gmsProcessLowEvent( ) accepts a pointer to an Xevent structure as its argument. The event structure is then checked by SL-GMS to see if any SL-GMS object has an interest in the event. If SL-GMS had no interest in the event, a value of 0 is returned. Alternatively, if SL-GMS was interested in the event and took some action, a non-zero value is returned from gmsProcessLowEvent( ) to the application. In either case, event-handler functions may be specified to SL-GMS through the use of either the gmsWsLowEventFctn( ) or the gmsNonWsLowEventFctn( ) functions. In the case of SL-GMS interest in the event, if an event-handler was registered with SL-GMS through the use of gmsWsLowEventFctn( ), Version 6.2a- 26 May 2006 SL-GMS Function Reference 466 Workstation/Window — events this registered event-handler function allows the application to have a chance to check and/or take some action regarding each event that SL-GMS has an interest in before SL-GMS does anything with the event. This may include preventing SL-GMS from taking action regarding the event if that is appropriate for the particular situation in the application. In the case of no SL-GMS interest in the event, if an event-handler function was registered with SL-GMS through the use of gmsNonWsLowEventFctn( ), this registered event-handler function gives the application a chance to check and/or take some action regarding this event. Alternatively, the application’s event loop function may be designed to process the events not associated with SL-GMS and the use of gmsNonWsLowEventFctn( ) to register an event-handler function is superfluous. If no event-handler function was specified to SL-GMS through use of either gmsWsLowEventFctn( ) or gmsWsLowEventFctn( ), SL-GMS dispatches and processes the event it has been handed. NOTE: The gmsWsLowEventFctn( ) function is currently available on X platforms only and will be provided on other platforms in a future release of SL-GMS. The gmsNonWsLowEventFctn( ) function is used to establish an Event-handler to receive Events that are not associated with an SL-GMS Workstation/Window. Applications using gmsMainLoop( ) can use gmsNonWsLowEventFctn( ) to register an Event-handler to process Events in which SL-GMS has no interest. The Event-handler expects a single XEvent parameter. A sample Event-handler is: int NonGmsWindowCB (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; } Version 6.2a- 26 May 2006 SL-GMS Function Reference 467 Workstation/Window — events The gmsWsSynchronize( ) command stream. function synchronizes the low-level DIAGNOSTICS The gmsWsEventFctn( ) and gmsWsTextEditObj( ) functions should not be called when using SL-SMS (i.e., when gmsInitStates( ) is also called). SEE ALSO gmsStTextEditObjName( ), gmsStTextEditObj( ) The section Event-handler functions outside SL-SMS in the SL-GMS Reference provides additional information about the gmsWsEventFctn( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 468 Workstation/Window — object Workstation/Window — object SUMMARY initialize, activate, deactivate, and change cursor echo type for Workstation/Window objects NAME gmsWorkst( ), gmsWsDefaultOpts( ), gmsWsAct( ), gmsWsDeact( ), gmsWsClose( ), gmsWsEchoMask( ), gmsWsLocEcho( ), gmsWsProcArgs( ), gmsWsProcArgsStr( ) SYNTAX id gmsWorkst (cls, name, conn, type, wind, code) struct ClassDef *cls;/* pointer to Workstation/Window class */ char *name; char *conn; char *type; char *wind; int code; /* name of Workstation/Window */ /* connection for Workstation/Window (DISPLAY) */ /* Workstation/Window type */ /* window id */ /* Workstation options */ int gmsWsDefaultOpts (code) int code; /* Workstation options */ int gmsWsAct (workst) id workst; /* Workstation/Window */ int gmsWsDeact (workst) id workst; /* Workstation/Window */ int gmsWsClose (workst) id workst; /* Workstation/Window */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 469 Workstation/Window — object int gmsWsEchoMask (workst, mask) id workst; /* Workstation/Window */ int mask; /* Locator echo mask */ int gmsWsLocEcho (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 */ id gmsWsProcArgs (argc, argv, wsopts) int argc; char **argv; int wsopts; id gmsWsProcArgsStr (argstr, wsopts) char *argstr; int wsopts; DESCRIPTION These functions create or modify Workstation/Window objects. A Workstation/Window object must be created and activated before any View can be displayed. The gmsWorkst( ) function creates Workstation/Window objects. In basic X application programs using SL-GMS, gmsWorkst( ) is called to create a window-manager window. An Xt application program, however, creates all widgets (and associated window-manager windows) it needs and then passes the id of the drawing area to gmsWorkst( ). The cls argument specifies the class of the Workstation/Window, and should be the return value of the gmsQDefaultWsClass( ) function. The name argument is an arbitrary (non-optional) name which may be used to reference the Workstation/Window using gmsFindByName( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 470 Workstation/Window — object The conn argument specifies a physical or logical connection to the display device. Under Xt, the conn argument is ignored because the display connection is found from the Xt widget specified as the wind argument (discussed below). Under X, when an id of an X window is specified as the wind argument, the conn argument must be specified as the X display connection id associated with the X window. When the wind argument is null under X, the conn argument is assumed to be the name of an X display connection to open. If both the conn and wind arguments are null strings under X, the X display connection to open is found from the DISPLAY environment variable, for example, "unix:0.0". The window argument, wind, is used to specify a pre-existing X window or Xt widget where SL-GMS is to draw dynamic graphics. The wind argument, if given, must be an X window or Xt widget id. NOTE: An Xt application must wait for the first Expose event before calling gmsWorkst( ) (i.e., the gmsWorkst( ) function must be passed a "realized" widget). Both conn and wind should be converted to strings (using sprintf( )) before passing them to gmsWorkst( ). For example, char string_id[32]; sprintf(string_id, "%lu", window_id); gms_workst = gmsWorkst(gmsQDefaultWsClass( ), "ws1", "", "default", string_id, flags); Version 6.2a- 26 May 2006 SL-GMS Function Reference 471 Workstation/Window — object A null string passed as the wind argument means that SL-GMS will open a window-manager window using the 80% Rule 2 if no Workstation/Window attributes 3 are in effect. NOTE: SL-GMS properly handles all interrupts and Events when attached to a single server or physical device. Multiple servers independently communicating with a single application process will be supported in a future release of SL-GMS. The Workstation/Window type is not normally used, and should be set to 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-created Workstation/Window as shown in the following tables. Valid Bit Values for gmsWorkst( ) “code" argument on Unix/X11 Systems Decimal 1 Hex Mnemonic 0x0001 G_WS_DBUFF_ERASE 2 0x0002 G_WS_NO_HARDWARE 8 0x0008 G_WS_DBUFF_CLEAR Description enable software double-buffering (Erase Update Mode) do not use special hardware-drawing routines enable software double-buffering (Clear Redraw Mode) 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. Version 6.2a- 26 May 2006 SL-GMS Function Reference 472 Workstation/Window — object Valid Bit Values for gmsWorkst( ) “code" argument on Unix/X11 Systems continued) Decimal Hex Mnemonic Description 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 0x8000 G_WS_MATRIX_HW enable matrix hardware 0 routines (SGI-IRISGL only) 65536 0x1000 G_WS_TEXT_BCOLOR enable Text background 0 color 3. Workstation/Window attributes are changed with the functions described in the section Workstation/Window — attribute changes on page -439. Version 6.2a- 26 May 2006 SL-GMS Function Reference 473 Workstation/Window — object Valid Bit Values for gmsWorkst( ) “code" argument on Unix/X11 Systems continued) Decimal Hex Mnemonic 131072 0x2000 G_WS_CACHE_GC 0 262144 0x4000 G_WS_NOPASTE 0 Description enable X Graphics Context caching (HP-UX only) disable middle mouse button for control of cut and paste enable Bitplane masking 1048576 0x1000 G_WS_PLANE_MASKING 00 8388608 0x8000 G_WS_EXPOSE_RECT enable expose-rectangle 00 (SGI-IRISGL only) More than one option is entered by bitwise OR-ing their values together. Version 6.2a- 26 May 2006 SL-GMS Function Reference 474 Workstation/Window — object Valid Bit Values for gmsWorkst( ) "code" argument on 32-bit Windows Decimal Hex Mnemonic 1 0x0001 G_WS_DBUFF_ERASE Description 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. The Workstation/Window object exhibits the following default behavior on 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 operations. The gmsWsDefaultOpts( ) function allows an application to establish default Workstation/Window options that hold for any Workstation/Window created thereafter via the gmsWorkst( ) function. Any code arguments given with the gmsWorkst( ) function are OR’d with the defaults given in the gmsWsDefaultOpts( ) function. Workstation/Windows are activated by default when created. In a system with multiple Workstation/Windows, specific Workstation/Windows may be activated or deactivated as desired. No objects 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 be associated with this Workstation/Window before anything can be Version 6.2a- 26 May 2006 SL-GMS Function Reference 475 Workstation/Window — object displayed upon it. Workstation/Windows are associated with particular Views by using the gmsWsNum( ) function. The gmsWsAct( ) and gmsWsDeact( ) functions, respectively, activate and deactivate a Workstation/Window. The gmsWsClose( ) function destroys the Workstation/Window. The gmsWsEchoMask( ) function sets the bitplane writemask used for Locator echo. If mask is 0 (zero), the Locator echo is XOR’d onto the display. If mask is non-zero, the system’s Locator echo writemask is used. The gmsWsLocEcho( ) function sets the Locator echo type for the given Workstation/Window. The Locator echo type controls the type of echoing for the mouse cursor. Valid codes for the echotype argument are provided in the table on the following page. Version 6.2a- 26 May 2006 SL-GMS Function Reference 476 Workstation/Window — object gmsWsLocEcho( ) — Valid Codes for "echotype" Argument Code G_LOC_ECHO_DEFAULT G_LOC_ECHO_LINE_1 Description normal (arrow) single moving line; parameters: one anchor point G_LOC_ECHO_LINE_2 double (jointed) moving line; parameters: two anchor points G_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_UNPR disproportional scaling rectangle; OP parameters: two points specifying the extent of the rectangle, one reference point Version 6.2a- 26 May 2006 SL-GMS Function Reference 477 Workstation/Window — object gmsWsLocEcho( ) — Valid Codes for "echotype" Argument continued) Code G_LOC_ECHO_LINE_MOVE G_LOC_ECHO_PLINE_MOVE G_LOC_ECHO_DJPLINE_MOVE Description single moving line (no anchor point); parameters: two points specifying the extent of the line, one reference point "stuck" on the mouse moving continuous (single) polyline; parameters: points specifying the polyline points, one reference point "stuck" on the mouse moving disjoint (noncontinuous) polyline; parameters: points specifying the polyline points, one reference point "stuck" on the mouse The echoconst argument to the gmsWsLocEcho( ) function can be G_LOC_ECHO_HORIZ, G_LOC_ECHO_VERT, or 0. The echoconst argument restricts the movement of the echo to the x or y dimension (or in the case of 0, provides no constraint at all). The pointlist argument contains Points to be used as "anchors," when such parameters are necessary. If pointlist is nil, Locator echo is turned off. The gmsWsProcArgs( ) function processes the switches in the command line, and uses the information obtained to create a Workstation/Window. The options available are platform-dependent and are listed for both Unix X/11 and 32- bit Windows systems. These options are specified in the function’s third argument, wsopts. The function returns a pointer to the Workstation/Window created, or the first Workstation/Window created if more than one Workstation/Window is created. NOTE: The switches used by gmsWsProcArgs( ) are reserved by SL-GMS and should not be used (for application-specific purpose) by programs that call gmsMainInit( ). Version 6.2a- 26 May 2006 SL-GMS Function Reference 478 Workstation/Window — object For non-C programming languages, or situations where the argc-argv mechanism is inconvenient or simply unavailable, the gmsWsProcArgsStr(argstr, wsopts) function can be used instead of gmsWsProcArgs( ). argstr is of type char *, where the character string contains space-separated arguments. Quotes attempting to combine words into one argument are not accounted for. SEE ALSO gmsSetup( ), gmsWsNum( ), gmsView( ), gmsFindByName( ), gmsQDefaultWsClass( ) SL-GML COMMANDS name act name deact Version 6.2a- 26 May 2006 SL-GMS Function Reference 479 Workstation/Window — Window query Workstation/Window — Window query SUMMARY query Workstation/Window Window attributes NAME gmsQWinBannerName( ), gmsQWinExt( ), gmsQWinIconName( ), gmsQWindowId( ), gmsQWorkst( ) SYNTAX char * gmsQWinBannerName (workst) id workst; /* Workstation/Window */ int gmsQWinExt (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) id workst; /* Workstation/Window */ unsigned long gmsQWindowId (workst) id workst; /* Workstation/Window */ id gmsQWorkst (window_handle) unsigned long window_handle; DESCRIPTION The gmsQWinBannerName( ) function queries the name in the banner name field of the Workstation/Window. It returns the Workstation/Window’s banner name if successful, 0 for failure. Version 6.2a- 26 May 2006 SL-GMS Function Reference 480 Workstation/Window — Window query The gmsQWinExt( ) function returns the extent (size) of a Workstation/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( ). This function returns 1 for success, 0 for failure. The gmsQWinIconName( ) function returns the icon name field of the Workstation/Window, or 0 for failure. The gmsQWindowId( ) function returns unsigned long, the Workstation/Window’s system-dependent window id: under X — the Workstation’s window id, under SGI-IRISGL — the gid of the Workstation’s first window; under Windows NT — the window handle for a given Windows NT Workstation. The gmsQWindowId( ) function returns 0 for failure. The gmsQWorkst( ) functions returns the Workstation/Window associated with a given system-dependent window id. The gmsQWorkst( ) function returns 0 for failure. Version 6.2a- 26 May 2006 SL-GMS Function Reference 481 Workstation/Window — Workstation query 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 id gmsQDefaultWsClass ( ) void * gmsQDisplayId (workst) id workst; /* Workstation/Window */ int gmsQScreenExt (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) id workst; /* Workstation/Window */ id gmsQWsColDef (workst, index) id workst; /* Workstation/Window */ int index; /* color index */ Version 6.2a- 26 May 2006 SL-GMS Function Reference 482 Workstation/Window — Workstation query int gmsQWsColormapIndex (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 */ int gmsQWsNumColors (workst) id workst; /* Workstation/Window */ long gmsQWsEchoMask (workst) id workst; /* Workstation/Window */ int gmsQWsPopMode (workst) id workst; /* Workstation/Window */ id gmsQWsViewport (workst) id workst; /* Workstation/Window */ id gmsQWsView (workst, locevent) id workst; /* Workstation/Window */ id locevent; /* Locator event */ DESCRIPTION The gmsQDefaultWsClass( ) function returns the id of the default Workstation/Window class. Its return value is used as the first argument in the gmsWorkst( ) function. Version 6.2a- 26 May 2006 SL-GMS Function Reference 483 Workstation/Window — Workstation query The gmsQDisplayId( ) function returns a Workstation/Window’s system-dependent display identifier: under X — the Workstation/Window’s display id, under SGI-IRISGL — the gid of the first window of the Workstation/Window. The gmsQScreenExt( ) function is used to obtain the extent of a display device, which allows an application to configure itself (for example, to center a window-manager window on a screen) according to the available screen resolution. The workst argument is a Workstation/Window object. A call to gmsQDefaultWsClass( ) can be used in place of a Workstation/Window object. The screen extent in Device Coordinates is returned in the lower_left and upper_right arguments. The pntX( ) and pntY( ) functions are used to obtain the coordinate values from each Point. The conn argument specifies a physical or logical connection to the display device. Under X, if the conn argument is a null string, this value is taken from the DISPLAY environment variable, for example, “unix:0.0”. The integer returned from the gmsQWidgetId( ) function is system-dependent: under Xt — the widget’s handle is returned, under X — 0 (zero) is returned, and under SGI-IRISGL — the gid of the first window of the Workstation/Window is returned. The gmsQWsColDef( ) function creates and returns a ColDef object containing the values for the color with the given index. The gmsObjFree( ) 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 store in colormap_index the window colormap index associated with that SL-GMS color index, if possible. The function returns 1 if it succeeds and 0 if it fails. Currently, gmsQWsColormapIndex( ) is implemented in the X Workstation layer only. When using this layer, the colormap index obtained by gmsQWsColormapIndex( ) is a pixel value. The gmsQWsColormapId( ) functions returns a Workstation/Window's system-dependent colormap identifier: Under X, the Version 6.2a- 26 May 2006 SL-GMS Function Reference 484 Workstation/Window — Workstation query Workstation/Window's X colormap id is returned. All other Workstation/Window types, such as WindowsNT, currently return 0. The gmsQWsNumColors( ) function returns the number of colors defined for a given Workstation/Window. The number of colors returned does not include colors allocated for bitmaps. If the workst argument is NULL, the number of colors returned is the maximum number of colors defined by any single Workstation/Window. The gmsQWsEchoMask( ) function returns the Workstation/Window Locator echo mask set by gmsWsEchoMask( ). The gmsQWsPopMode( ) function returns the Workstation/Window’s preferred Pop-on/pop-off Mode using gmsPopOn( )/gmsPopOff( ): either G_WS_POP_RASTER or G_WS_POP_CLIP. The gmsQWsViewport( ) function returns the Workstation/Window's Viewport (an Extent object). extent of the The gmsQWsView( ) function returns the View in which a Locator event occurred, given a Workstation/Window and a Locator event. EXAMPLE To get the , pixel values for a Workstation/Window Viewport: id wsvp = gmsQWsViewport(g_workst); printf("x1 = %d, y1 = %d, x2 = %d, y2 = %d\n", extX1(wsvp), extY1(wsvp), extX2(wsvp), extY2(wsvp)); Version 6.2a- 26 May 2006 SL-GMS Function Reference 485 Workstation/Window — Workstation query For a full-screen window on an SGI platform, output from the above code is: x1 = 0, y1 = 0, x2 = 1267, y2 = 950 SEE ALSO gmsWorkst( ), gmsWsEchoMask( ), gmsPopOn( ), gmsPopOff( ) Version 6.2a- 26 May 2006 SL-GMS Function Reference 486 World Coordinates World Coordinates SUMMARY create Points from World Coordinates; set World Coordinate Scale Factor NAME gmsWPoint( ), gmsWPXY( ), gmsSWPXY( ), gmsWValue( ), gmsWCScale( ), gmsWCoordX( ), gmsWCoordY( ) SYNTAX idPoint gmsWPoint( ) idPoint gmsWPXY (x, y) double x, y; int gmsSWPXY (point, x, y) idPoint point; double x; double y; int gmsWValue (x) double x; int gmsWCScale (scale) double scale; double gmsWCoordX (x) coordVar x; Version 6.2a- 26 May 2006 SL-GMS Function Reference 487 World Coordinates double gmsWCoordY (y) coordVar y; DESCRIPTION These functions are used to create and set values for Points using World Coordinates. All Points used as arguments to the SL-GMS functions may be created using the gmsWPXY( ) function which takes floating-point arguments. The x and y values are multiplied by the World Coordinate Scale Factor and returned in a Point object. The gmsWPoint( ) function creates a Point which is equivalent to gmsWPXY(0.0,0.0). Once a Point is created, its x and y values are set using gmsSWPXY( ) rather than creating another Point. Points created using these functions may be freed using the pntFree( ) function. All Points generated by SL-GML commands are created using the gmsWPXY( ) function. The gmsWValue( ) function takes a double argument and converts it to an integer using the World Coordinate Scale Factor. If this function is called with an argument of 1.0, it returns the current World Coordinate Scale Factor. The gmsWCScale( ) function sets the World Coordinate scaling factor. The gmsWCoordX( ) function converts an SL-GMS Internal Coordinate to a World Coordinate. The gmsWCoordY( ) function converts an SL-GMS Internal Coordinate to a World Coordinate. Version 6.2a- 26 May 2006 SL-GMS Function Reference 488 World Coordinates DIAGNOSTICS Currently, gmsWCoordX( ) and gmsWCoordY( ) are identical, since there is only one World Coordinate Scale Factor. Future implementations may provide separate scale factors for the x and y directions. SEE ALSO gmsWind( ), gmsNPXY( ), pnt*( ) SL-GML COMMAND coordscale real Version 6.2a- 26 May 2006 SL-GMS Function Reference 489 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 A absolute move ............................................... 5 rotation............................................ 8 scale ............................................. 10 AND operation .................................. 317 apply transformation ........................... 13 aspect ratio of window, setting of Workstation ......................... 473, 475 autodeactflag, setting for State ......... 354 B background color of Model ........................................ 15 of Workstation/Window ............... 448 Batch Erase Mode .............................. 80 batcherase flag ................................... 78 Bitmap creation of ..................................... 20 scaling of....................................... 20 Bitmap Write Mode ............................. 21 bitpad devices enabling for Workstation ............. 473 Bitplane masking enabling for Workstation ............. 474 bitplane masking............................... 451 BLOBs (Binary Large Objects) 245, 252, 253, 254, 255, 256 Version 6.2a- 26 May 2006 bus error handler for ...................................412 with gmsVarDefine( )...................111 C cache SubModel ....................242, 243, 269 center of object.........................................24 center of object vs center of extent26, 144 CGM file format converting to SL-GMS Model ......241 Circle, create .......................................28 class class-definition structures..............66 name strings on-line file location...................31 testing if object is a member .........30 clear Graphs ........................................285 variables set up in .dat files...........51 View ..............................................32 Workstation ...................................32 Clear Redraw Mode ..................472, 475 clearflag, setting for State .................353 Clip Mode ..........................................426 clipping ......................................426, 428 clockwise flag ....................................341 clone Graphical Primitive object .............33 Point ............................................293 example.................................294 State class exemplar...................365 close, SL-GMS ..................................344 close_read( ) .....................................257 close_write( ).....................................254 Closed Spline object .........................350 closure attribute...................................34 ColDef objects freeing from memory ...................162 SL-GMS Function Reference i color background of Model .................................. 15 of Workstation/Window ......... 448 color index, setting RGB values for39 of objects ...................................... 36 Text background, enabling Workstation for................ 473 colordef.dat file ................................... 39 colormap, setting for a Workstation .. 473 command line process arguments ................. 4, 478 compare version numbers, SL-GMS 347 complement ...................................... 317 concave fill enabling for Workstation ............. 473 configuration number, SL-GMS ........ 347 coordVar variable type...................... 293 copy, objects....................................... 33 crash handler, SL-GMS .................... 413 create Events......................................... 120 current Group ............................................ 40 Model ............................................ 40 View .............................................. 40 cursor.................................................. 43 cursor movement, elimination of flashing on screen for............................... 473 custom Markers ................................ 229 D d1flag, setting for State..................... 354 Datasource class adding a method to ................. 53 creation of ............................... 53 installation into the run-time environment ................ 53 looking up given a name ......... 53 Version 6.2a- 26 May 2006 Instance.........................................54 messages ................................59 datflag, setting for State ....................354 debugging dumps ...........................................68 debugging utility SL-SMS.......................................376 default SL-GMS search path...............62, 63 Deferred Update Mode................66, 415 definevars method.....................114, 384 detectability attribute .........................436 directories............................................62 dispatch_mode..................................368 display .................................................65 display flag ........................................437 double-buffering, enabling Workstation for 472, 475 double-buffering, on an object.............69 dump ...................................................68 duration time spent updating.....................281 Dynamic Description create ............................................71 querying ........................................74 dynamics end ................................................81 in non-replicated SubModel ..........98 initialize .........................................81 optimized.......................................85 prevention of update ...................355 update ...........................................81 user-defined functions.................418 Variable References......................94 dynarray flag .......................................88 DynProps creating .........................................70 maximum length of........................71 SL-GMS Function Reference ii E External SubModel Mode..................243 edge color of .......................................... 36 style ............................................ 391 width ........................................... 118 end dynamics...................................... 81 erase batcherase .................................... 78 GraphTraces ............................... 285 marking objects for ....................... 65 Erase Update Mode.................. 472, 475 event dispatch input.............................. 130 dispatch timer ............................. 131 functions ..................................... 130 GISMO........................................ 131 intercept all events ...................... 376 set priority of processing ............. 131 wait ............................................. 130 Events add to Workstation event queue . 120 create .......................................... 120 enable Locator motion ................ 360 main loop ............................ 131, 223 modify ......................................... 120 query........................................... 132 Timer........................................... 138 processing priority................. 131 exploding SubModels ....................... 261 EXPORT macro definition..................... 4 expose-rectangle enabling for Workstation ............. 474 extended Point List ........................... 287 extent center.................................... 26, 144 of an object, query for ................. 146 external SubModel moving to Local List .................... 394 query Model’s List of................... 238 F Version 6.2a- 26 May 2006 failure return value ................................3 Filer interception files ........................244 filer_callback( ) ..........................246, 250 fill attribute .......................................151 direction.......................................148 percent ........................................148 objects other than Rectangles150 valid range for........................149 style.............................................391 fill (concave) enabling for Workstation .............473 Fill attribute color of ..........................................36 Filled Text Rectangle create ..........................................320 FillGroup close............................................187 close each member of List ..........187 create ..........................................187 open ............................................187 open List of FillGroups ................187 find by name Datasource class object ................53 object...........................................157 State Instance .............................377 find file function install ...........................................153 flag batcherase ....................................78 example...................................80 clockwise.....................................341 display, force redraw ...................437 global...........................................264 non-replication, SubModels.........264 permanent ...................................267 repair ...........................................189 SL-GMS Function Reference iii example .................................. 80 updflag ........................................ 139 visible .......................................... 437 yes, query user ........................... 345 flashing (with cursor movement), elimination of............................... 473 font index from font name............................ 160 font_index parameter........................ 160 force redraw...................................... 437 fpercent errors which were not noticeable before.......................................... 150 freeflag, setting for State................... 353 freeing from memory ColDef objects ............................ 162 List of objects.............................. 162 objects ........................................ 162 Variable Definitions..................... 162 from .dat files .......................... 51 full screen, setting to use Workstation option .............. 473, 475 functions, adding user-defined.......... 418 G G_BKGR_TYPE_COLOR................. 448 G_BKGR_TYPE_INDEX .................. 448 G_BKGR_TYPE_SYSTEM............... 448 G_BPAD_BUTTON_* Event codes . 134, 137 G_BTM_NO_TRANS flag ................... 22 G_BTM_TRANS_IMPULSE flag......... 22 G_CONTROL_KEY Event code ....... 134 g_dyninit_state.................................... 82 G_FILER_BINARY ........................... 246 G_FILER_CHAR............................... 246 G_FILER_CLOSE_READ......... 249, 250 G_FILER_CLOSE_WRITE_FAILURE249 G_FILER_CLOSE_WRITE_SUCCESS .. 248 G_FILER_LOCFILE.......................... 246 Version 6.2a- 26 May 2006 G_FILER_M1 ............................245, 246 G_FILER_M2 ....................................246 G_FILER_OPEN_READ ...........249, 250 G_FILER_OPEN_WRITE .........248, 250 G_FILER_QUERY_EXISTS......248, 250 G_FILER_QUERY_READABLE249, 250 G_FILER_QUERY_WRITABLE 248, 250 G_FILER_WCHAR............................246 G_FilerData.......................................246 G_LOC_* Event codes..............134, 137 G_LOC_ECHO_HORIZ ....................478 G_LOC_ECHO_VERT ......................478 G_LOCK_KEY Event code ...............134 G_MULTI_EVENT.....................368, 465 G_NO_REPLICATE ..........................264 G_ONE_SHOT..........................368, 465 G_ONE_SHOT_CLEAR............368, 465 G_REPLICATE_ALWAYS ................264 G_REPLICATE_IF_RENVARS.........264 G_SHIFT_KEY Event code...............134 G_TCOLOR_NULL ...........................449 G_WIN_CONCAVE_FILL .................443 G_WIN_DBUFF_CLEAR ..................443 G_WIN_DBUFF_ERASE ..................443 G_WIN_DESTROYED ......................443 G_WIN_FULL_SCREEN...................443 G_WIN_KEEPASPECT ....................443 G_WIN_MATRIX_HW.......................443 G_WIN_NOBANNER ........................443 G_WIN_NOPASTE ...........................443 G_WIN_NOPOSITION......................443 G_WIN_NORESIZE ..........................443 G_WIN_WORKSTATION..................443 G_WS_BPAD....................................473 G_WS_BW_REV ......................473, 475 G_WS_CACHE_GC..........................474 G_WS_CONCAVE_FILL...................473 G_WS_DBUFF_CLEAR............472, 475 G_WS_DBUFF_CLEAR flag...............69 G_WS_DBUFF_ERASE ...........472, 475 SL-GMS Function Reference iv G_WS_DBUFF_ERASE flag .............. 69 G_WS_EXPOSE_RECT................... 474 G_WS_FULL_SCREEN ........... 473, 475 G_WS_KEEP_ASPECT ........... 473, 475 G_WS_LOOKUP_COLORS ............. 473 G_WS_MATRIX_HW........................ 473 G_WS_NO_HARDWARE................. 472 G_WS_NOPASTE ............................ 474 G_WS_PLANE_MASKING............... 474 G_WS_PLANE_MASKING workstation option .......................................... 453 G_WS_POP_CLIP............................ 473 G_WS_POP_RASTER ..................... 473 G_WS_POP_RASTER Workstation Option ..................... 313 G_WS_TEXT_BCOLOR................... 473 genlocfile utility................................ 192 gismoflag, setting for State ............... 353 GISMOs initialize ....................................... 169 process a function key ................ 170 global flag ......................................... 264 gms.h file .............................................. 3 gmsDsDeactivate( ).............................58 gmsDsMsg( ).......................................55 gmsDynEnd( ) .............72, 116, 117, 163 gmsDynInit( ) 72, 87, 92, 94, 97, 98, 109, 111, 116, 163, 203, 242, 366, 384, 385, 387 gmsDynUpdate( ) ..................88, 92, 113 gmsE gmsEndView( )..................................457 gmsExternalEventLoop( )..................466 gmsF gmsFindByName( ) ...200, 201, 437, 470 gmsFindObject( )...............135, 428, 429 gmsFreeAllVarDefs( )..................51, 163 gmsG gmsGenerateLocFileSO( ) ................193 example.......................................194 gmsI gms_ gmsInitGismos( ) ...............................224 gmsInitStates( ) .................139, 225, 376 gmsInMode( ) ....................................224 gms_dms.h file...................................... 3 gms_sms.h file...................................... 3 gmsL gmsA gmsATran( )...................................... 334 gmsC gmsClassAddMethod( ) .............. 61, 372 gmscodes.h file........................... 30, 109 gmsCompareVersion( )..................... 348 gmsCoordLimits( ) ............................ 179 gmsCurrent( ).................................... 187 gmsD gmsLQExtCenter( ) .............................27 gmsM gmsM2Get( ) .............................263, 366 gmsM2Merge( ).................................263 gmsM2Save( )...................................263 gmsM2XGet( )...................102, 263, 271 gmsMainInit( ) ...........................344, 412 gmsMainInit( ) .......................................4 gmsMainLoop( ) ........................131, 142 gmsMGet( ) .......................................367 gmsMGet( ) .......................................457 gmsDsActivate( ) ................................ 58 Version 6.2a- 26 May 2006 SL-GMS Function Reference v gmsModApplyLocFileSO( )192, 195, 196, 197, 203, 204 example ...................................... 204 gmsModCacheCapacity( ) 103, 269, 272 gmsModCacheCount( )103, 270, 271, 272 gmsModDynInitVarDefTable( ) ........... 97 gmsModNonReplicate( ) ................... 104 gmsModPermanent( ) ....................... 272 gmsMSave( ) .................................... 395 gmsMXGet( ) .................... 102, 264, 271 gmsN gmsNonWsLowEventFctn( ) ............. 142 gmsNPXY( )...................................... 433 gmsO gmsObjFree( )... 113, 116, 117, 210, 377 gmsP gmsPlotClear( )................................. 176 gmsPop*() functions setting to use clip rectangle for Workstation................ 473 setting to use rasters for Workstation................ 473 gmsPopOff( ) .................................... 354 gmsPort( ) ................................. 274, 295 gmsPortXY( ) .................................... 304 gmsProcessLowEvent( )................... 466 gmsProject( ) .................................... 344 gmsPsLViewWrite( ) ......................... 303 gmsPsPolyMaxPoints( ).................... 303 gmsPsWsProcArgs( ) ....................... 303 gmsQ gmsQCenter( ) .................................. 144 gmsQDefaultWs( ) ............................ 442 gmsQDefaultWsClass( ) ................... 470 gmsQEvStringC( )............................. 136 gmsQEvStringSO( ) .......................... 136 Version 6.2a- 26 May 2006 gmsQExtCenter( ) ...............................24 gmsQModCacheCapacity( )..............271 gmsQModCacheCount( ) ..........271, 272 gmsQPartList( ) ...................................67 gmsQSRStringSO( )..........................195 example.......................................203 gmsQStringC( ) .................209, 211, 212 gmsQStringWC( )..............209, 210, 211 gmsQTPrec0RotFlag( ) .....................407 gmsQTStringC( ) ...............403, 404, 405 gmsQTStringSO( ) ............................403 gmsQTStringWC( )....................403, 404 gmsQTStrSO( ) .................................406 gmsQWsBackgroundColor( ) ....449, 450 gmsQWsColDef( ) .............................162 gmsR gmsRect( )...........................................74 gmsRedCode( ).................................281 gmsRedraw( )....................................425 gmsRefPoint( ) ............ 7, 9, 12, 329, 331 gmsRemVarDefLinks( ).........72, 82, 163 gmsRenamedStr( )......................82, 116 gmsRenVarStrConstReplSO( ) ...72, 201 example.........................................73 gmsRepairFlag( ) ........................78, 189 gmsRMove2( ).......................................7 gmsRRotZ( )..........................................9 gmsRScale( ) ......................................12 gmsRSTran( )....................................165 gmsRTran( ) ......................................343 gmsS gmsSetTraps( ) .................................224 gmsSetup( ).......................................245 gmsSEvModifiers( )...........................125 gmsSRApplyLocFileSO( ) 195, 196, 197, 199 example.......................................202 gmsStActivate( )................................376 SL-GMS Function Reference vi gmsStAddModelName( ) .................. 277 gmsStDeactivate( ) ........................... 376 gmsStFreeAllVarDefs( ).................... 163 gmsStReset( )................................... 376 gmsString( ) example ........................................ 73 gmsStringC( ).................... 194, 209, 211 example .............................. 202, 204 gmsStringEmpty( ) ............................ 213 gmsStringResource( )....................... 195 gmsStringSetC( ) ...................... 209, 211 gmsStringSetWC( )................... 209, 210 gmsStringWC( ) ........................ 209, 210 gmsStVarDefAddress( ).................... 384 gmsStVarDefCount( ) ....................... 384 gmsStVarDefine( ) ........ 92, 98, 162, 387 gmsStVarDefSize( ) .......................... 384 gmsT gmstimer process killing of (X Workstation) ............. 413 spawning of................................. 139 gmsTimerPeriod( ) ............................ 360 gmsTRepl( ) ...................................... 200 gmsTStringC( ) ......................... 403, 404 gmsTStringSO( )....................... 403, 405 example ...................................... 203 gmsTStringWC( ) .............................. 403 gmsU gmsUnlinkVarDefs( )..... 72, 82, 163, 203 gmsUpdate( ) ........ 84, 87, 242, 321, 425 gmsV gmsVarChanged( ) ....... 88, 95, 100, 355 gmsVarDefAddress( ) ....................... 112 gmsVarDefCount( )........................... 112 gmsVarDefine( )... 55, 71, 84, 91, 92, 94, 117, 162, 163, 383, 419 gmsVarDefineChanged( ) ................. 163 Version 6.2a- 26 May 2006 gmsVarDefineNoTable( )91, 92, 93, 162, 163 gmsVarDefSize( )..............................112 gmsVarInitFctn( ).......................112, 385 gmsVarRefName( ) .............................87 gmsView( ) ........................................457 gmsVuRFile( ) .....................................21 gmsW gmsWCScale( ) .................................344 gmsWinDims( )..................................443 gmsWindXY( ) ...................................425 gmsWinFlags( ) valid codes for bit argument ........443 gmsWinPush( )..................................446 gmsWinUnmap( ) ..............................447 gmsWorkst( ).............................224, 449 gmsWPoint( ) ....................................295 gmsWPXY( ) .............295, 321, 338, 432 gmsWsBackgroundColor( )448, 449, 450 gmsWsClose( )..................................441 gmsWsEventFctn( )...........................360 gmsWsLocEcho( ) valid codes for echotype argument ...477 gmsWsLowEventFctn( ) ....................142 gmsWsProcArgs( ) ................4, 224, 478 gmsWsProcArgsStr( ) .......................479 gmsWsPsProcArgs( )............................4 gmsWValue( ) ....... 7, 294, 323, 327, 332 gmsX gmsXTran( ) ........................7, 9, 12, 165 gmsZ gradient fill styles acyclic .........................................173 cyclic ...........................................172 elliptic ..........................................173 GraphAxis object SL-GMS Function Reference vii create .......................................... 174 major tick spacing ....................... 176 minor tick spacing ....................... 176 set ends of axis........................... 176 values for endpoints.................... 176 GraphTrace object clear ............................................ 285 creating ....................................... 178 erase and clear Point List ........... 285 plot Points ................................... 284 query number of traces ............... 278 Grid object ........................................ 181 Group redrawing .................................... 189 Group object ..................................... 185 close ........................................... 187 close each member of List.......... 187 create .......................................... 187 current........................................... 40 destroy ........................................ 187 destroy Groups in a List.............. 187 gsave Model ..................................... 242 gmsQFGradient( )............................. 173 H hardware-drawing routines, disabling Workstation for............................ 472 highlight .............................................. 65 I id variable type...................................... 2 idLinkRef variable type ......................... 2 idPoint variable type ............................. 2 Immediate Update Mode .... 66, 331, 415 IMPORT macro definition ..................... 4 impulse filter kernel and scaling Bitmaps...................... 22 include files order of in SL-GMS programs......... 3 initialize Version 6.2a- 26 May 2006 dynamics .......................................81 State............................................359 Variable References local to State..........................382 input events.......................................130 install find file function ...........................153 Instance, SubModel ..........................261 Internationalization ............................190 Model apply localization file .............195 generate localization file........193 source code localization file for..................195 interrupt signals, handler for..............412 invisible .............................................437 K keysymdef.h file ................................134 L lib directory ...........................................2 Line color of ..........................................36 create ..........................................214 style.............................................391 Linked Reference (LinkRef) object....215 -loc option .................................192, 203 loc_motion method............................135 loc_press method..............................135 loc_release method...........................135 local SubModel moving to External List................394 query Model’s List of ...................238 localization file commands gmsModApplyLocFileSO( ) .........200 gmsSRApplyLocFileSO( ) ...........199 localization files definition of..................................191 SL-GMS Function Reference viii new function generated from Models ................... 193 Unicode....................................... 193 wide character and multi-byte..... 198 locator events capture for a View....................... 424 Locator object ................................... 158 M m2flag parameter.............................. 266 main Event loop starting ........................................ 223 main loop, external ........................... 140 Marker object color of .......................................... 36 creating ....................................... 233 custom drawing function ............. 229 Marker class ................................. 31 setting size.................................. 234 style ............................................ 391 masking, bitplane.............................. 451 matrix hardware routines, enabling for Workstation ................................. 473 menus pop-up......................................... 311 message tracing ............................... 236 middle mouse button disabling for cut and paste.......... 474 mode, update.................................... 415 Model apply localization file to ............... 195 background color .......................... 15 current................................... 40, 237 generate localization file ............. 193 example ................................ 194 object creating ................................. 237 prevention of dynamic update..... 355 pseudo-files ................................ 244 save ............................................ 240 Version 6.2a- 26 May 2006 user header string .......................258 Variable Definition Table ...............97 Model Instance (ModInst) object .......261 modelname parameter ......................266 modify Events .........................................120 mouse button middle, disabling cut and paste for Workstation .....................474 mouse cursor ......................................43 move absolute...........................................5 multiple Views, in PostScript .............304 N name find object by ...............................157 of an object..................................275 of SL-GMS Run-time Functions ......3 NDC scaling factor ............................273 noerase flag, for an object...................80 non-replicated SubModels ................265 non-replication flag............................261 on SubModels .............................264 normalized Point ...............................273 O object center Point ...................................24 detectability .................................436 free List from memory .................162 freeing from memory ...................162 get Point List ...............................287 name ...........................................275 query owner List..........................276 radius ..........................................310 replace Point List.........................290 style attribute...............................391 UserData .....................................422 UserWord ....................................422 SL-GMS Function Reference ix Variable Definition......................... 92 visibility ....................................... 436 open_read( ) ..................................... 255 open_write( )..................................... 253 optimized dynamics ............................ 85 OR operation .................................... 317 overlapping Views............................. 427 overwrite ........................................... 317 owner of object ...................................... 276 P pan.................................................... 434 PartPrim class..................................... 31 paths ................................................... 62 percent-fill attribute....................................... 149 objects other than Rectangles .... 150 permanent flag.......................... 261, 267 picking objects .................................. 427 Pie object create .......................................... 282 modify ......................................... 340 plane masking................................... 451 plot plotshift ....................................... 285 Points .......................................... 285 pntFree( ) ... 24, 144, 163, 274, 293, 323, 488 pntX( ) ............................................... 135 pntY( ) ............................................... 135 Point clone ........................................... 292 example ................................ 294 create .......................................... 292 List .............................................. 290 Normalized Device Coordinates . 273 plot .............................................. 284 Reference Point .......................... 322 with World Coordinates............... 487 Version 6.2a- 26 May 2006 x coordinate.................................292 Point y coordinate .............................292 pointer types, in SL-GMS ......................2 Polygon object create ..........................................296 Polyline object create ..........................................214 popflag, setting for State ...................354 Popon/Popoff Mode ..........................312 PostScript..........................................298 preserve_sub_vdt parameter ......97, 102 Prim class............................................31 priority, View......................................426 processing priority .............................131 Project object ....................................306 ps_comment......................................300 ps_dcmax_x ......................................299 ps_dcmax_y ......................................299 ps_flags.............................................300 ps_off_x.............................................299 ps_off_y.............................................299 ps_one_pix........................................300 ps_rotate ...........................................300 pseudo-files.......................................244 psflags bit options....................................300 pull-down menus raster save and restore ...............311 Q query Events .........................................132 Model parts .................................278 object parts..................................278 user .............................................308 query_exists( )...................................252 query_readable( )..............................255 query_writable( ) ...............................252 quit, SL-GMS.....................................344 SL-GMS Function Reference x R radius object .......................................... 310 raster operations ................................... 316 Raster Operation Mode ........ 21, 316 raster image View ............................................ 314 Rectangle object create .......................................... 319 redraw Group.................................... 189 Reference Extent, definition of............ 22 Reference Point ................................ 322 refFreAll().......................................... 380 refKilAll( ) .......................... 144, 163, 288 refNew( ) ........................... 214, 233, 296 relative move ........................................... 325 scale ........................................... 330 transformation..................... 328, 333 Renamed Variables creating ......................................... 70 in SubModel Replicate Mode ........ 72 maximum length of ....................... 71 query string ................................... 74 repair flag.......................................... 189 replace string .................................... 401 replication, SubModel ....................... 263 reset transformation.......................... 335 Resolution Check Mode.................... 426 return values ......................................... 3 reverse black and white setting Workstation for ........ 473, 475 RGB, setting for a color index............. 39 rotation.............................................. 328 absolute .......................................... 8 S save Model ....................................... 240 Version 6.2a- 26 May 2006 scale............................................10, 330 scoping initialize variables local to State ..382 search path, SL-GMS changing of....................................62 default ...........................................63 Sector object create ..........................................337 modify..........................................340 segmentation violation handler for ...................................412 with gmsVarDefine( )...................111 segments...........................................426 set transformation .............................342 setup .................................................344 size attribute Marker .........................................234 SL-GML command act ...............................................476 amove .............................................6 amovex............................................6 amovey............................................6 arclength .....................................341 arotz ................................................8 ascale............................................11 ascalex ..........................................12 ascaley ..........................................12 batcherase ....................................78 bitmap ...........................................21 bitmapflag......................................21 center ............................................24 cir2 ................................................29 circ.................................................28 clear ..............................................32 clip...............................................428 clone..............................................33 closed............................................34 color ..............................................36 coordlimits ...................................176 coordscale...........................344, 488 SL-GMS Function Reference xi cspline......................................... 350 ctb ................................................. 39 current......................................... 427 dbflag ............................................ 69 deact ........................................... 476 detect .......................................... 437 dump............................................. 68 dynprop......................................... 71 endview....................................... 427 estyle .......................................... 391 etime ........................................... 281 ewidth ......................................... 118 fcir2 ............................................... 29 fcirc ............................................... 29 fcolor ............................................. 36 finter............................................ 391 font.............................................. 396 fpoly ............................................ 296 frect............................................. 320 fsec2 ........................................... 338 fsec3 ........................................... 338 fsect ............................................ 338 fstyle ........................................... 391 ftrect............................................ 320 graphaxis .................................... 174 graphtrace................................... 178 grid .............................................. 181 gsave .......................................... 241 height .......................................... 397 inst2 ............................................ 263 lcolor ............................................. 36 lstyle............................................ 391 majorspacing .............................. 176 mark ............................................ 233 mcolor ........................................... 36 minorspacing .............................. 176 model get .................................... 240 model xget .................................. 240 modinst ....................................... 263 modinst2 ..................................... 263 Version 6.2a- 26 May 2006 moffset ........................................326 mrotz ...........................................329 mscale.........................................332 msize...........................................234 mstyle..........................................391 mtran ...........................................168 mtran0 .........................................336 noerase .........................................80 offset ...........................................326 pan ..............................................435 path .............................................396 plotclear.......................................285 plotdata .......................................284 plotdatax......................................285 plotdatay......................................285 plotreset ......................................285 plotshiftx ......................................285 plotshifty ......................................285 points...........................................287 poly..............................................296 port ..............................................433 prec .............................................396 project .................................306, 344 project get ...................................306 project merge ..............................307 project save.................................306 quit ..............................................344 radius ..........................................310 rastop ..........................................316 rect ..............................................320 refpoint ........................................322 renamedvars .................................71 reschk..........................................429 rfrect ............................................320 rftrect ...........................................320 rmove ..........................................326 rmovex ........................................326 rmovey ........................................326 rrect .............................................320 rrotz .............................................328 SL-GMS Function Reference xii rscale .......................................... 331 rscalex ........................................ 331 rscaley ........................................ 331 save ............................................ 240 scale ........................................... 331 sec2 ............................................ 338 sec3 ............................................ 338 sect ............................................. 338 spline .......................................... 350 startangle .................................... 341 stext ............................................ 402 stress .......................................... 389 tcolor ............................................. 36 text .............................................. 402 time ............................................. 281 tran.............................. 167, 334, 342 tran0............................................ 336 userdata...................................... 423 userword ..................................... 423 valuelimits ................................... 176 view............................................. 427 vis ............................................... 437 wind ............................................ 432 xpoints ........................................ 287 xtran .............................................. 13 xvaluelimits ................................. 179 yvaluelimits ................................. 179 zoom ........................................... 435 zoomin ........................................ 435 zoomout ...................................... 435 zos .............................................. 435 zpr............................................... 435 SL-GMS close ........................................... 344 compare version numbers .......... 347 configuration number .................. 347 convert Internal Coordinate to World Coordinate ...................... 488 crash handler .............................. 413 initialize ....................................... 223 Version 6.2a- 26 May 2006 installation directory ....................346 quit ..............................................344 setup ...........................................344 version date.................................347 version number ...........................348 SL-SMS debugging utility ..........................376 source ...............................................317 Spline object create ..........................................350 modify..........................................340 stress...........................................389 State ".m2"/".m1" search order .............376 class ............................................356 add methods..........................357 create ....................................356 find by name..........................376 install .....................................357 definevars method...............114, 384 initialization..................................359 Instance activate ..................................363 attributes of............................352 clear List of Models ...............367 clear View pointer..................367 create ....................................363 deactivate ..............................366 find by name..........................377 free Model .............................377 initialize Variable References 382 messaging .............................371 Model.....................................367 modify....................................363 query .....................................378 TextEdit object.......................367 Variable Definition objects.....386 View.......................................367 clear pointer367 Workstation/Window..............366 SL-GMS Function Reference xiii local variables ............................. 382 mark and reset............................ 369 messaging .................................. 371 query........................................... 378 set version 3.0 compatibility........ 376 update method............................ 114 stress, Splines .......................... 350, 389 String Events Event-handlers for ...................... 464 String object........................ 72, 195, 403 creating and querying ................. 209 example ................................ 73, 193 String Resource object example ...................................... 205 style attribute .................................... 391 SubModel cache .......................... 242, 243, 269 exploding .................................... 261 external ....................................... 394 local ............................................ 394 non-replicated with dynamics ....... 98 non-replication .................... 261, 265 permanent................................... 267 replication ................................... 263 SubModel Replicate Mode........ 261, 279 success codes ...................................... 3 system calls (bad), handler for.......... 412 System Pull-Down Menu .................. 302 T Text................................................... 401 background color, enabling Workstation for................ 473 color of .......................................... 36 Text object create .......................................... 402 query attributes ........................... 407 set attributes ............................... 396 Text Rectangle constraint attribute ...................... 409 Version 6.2a- 26 May 2006 TextEdit object ..................................367 State Instance .............................367 time_level flag ...................................281 timer event ................................131, 138 timing information..............139, 281, 360 traces, number of ..............................278 transformation absolute general..........................164 absolute move.................................5 absolute scale ...............................10 apply..............................................13 Bitmap object ................................20 relative.........................................333 relative 2D scale..........................330 relative general............................167 relative move...............................325 relative rotation............................328 reset ............................................335 set ...............................................342 transparent Views .............................427 traps, setting of..................................412 trend Graphs .....................................285 type attribute .......................................92 types, of variables .................................2 U Unicode localization files...................193 update dynamics .......................................81 modes .........................................416 times............................................281 update method ..................................114 update( ), State method ....................106 updflag flag........................................139 setting for State ...........................354 UserData maximum length of......................423 set and query ..............................422 user-defined function adding and removing...................418 SL-GMS Function Reference xiv dynamic ...................................... 418 userfctns_initialize() .......................... 420 UserWord set and query .............................. 422 V variable define new type........................... 113 determining which are present at run time ................................... 94 inform SL-GMS of value change. 113 SL-GMS types ................................ 2 Variable Definition created with gmsVarDefineNoTable( ) freeing from memory162 definition of............................ 109 find object.............................. 117 freeing from memory....... 51, 117 query address92, 387 count92, 387 size92, 387 query name ............................. 93 removal of links to ................. 116 set address91, 112, 387 count91, 112, 387 size92, 112, 387 type92 Variable Reference definition of.............................. 82 query address95 name94 number of95 query an object ....................... 94 removal of links to ................. 116 Variable Definition Table Version 6.2a- 26 May 2006 for a Model ....................................97 inform SL-GMS of value change .100 number of objects..........................99 object by name..............................99 objects by index ............................99 recommended uses.......................98 version date, SL-GMS.......................347 version number, SL-GMS..................348 View capture locator events.................424 clear ..............................................32 Clip Mode ....................................428 clipping ........................................426 create ..........................................427 current ...........................................40 delayed redraw............................425 detectability .................................436 dimensions ..................................426 make temporary WC-window change permanent .......................435 multiple printing in PostScript .............304 pan and zoom .............................434 printing in PostScript ...................303 priority .........................................426 raster image ................................314 reset pan and zoom ....................435 Resolution Check Mode ..............429 transparent ..................................427 Viewport ......................................431 visibility........................................436 WC-window .................................431 Workstation/Window number ......428 Viewport ............................................431 Virtual-window, setting for a Workstation/Window ...................443 visflag, setting for State.....................354 visibility attribute................................436 visible flag .........................................437 SL-GMS Function Reference xv W wait for event .................................... 130 WC-Window...................................... 431 width, of edge ................................... 118 Workstation aspect ratio, constraining Window to initial setting ............ 473, 475 bitpad devices, enabling of ......... 473 Bitplane masking, enabling of..... 474 colormap, setting of .................... 473 concave fill, enabling of .............. 473 expose-rectangle, enabling of..... 474 full screen setting Window to use473, 475 gmsPop*() functions setting to use clip rectangle .. 473 setting to use rasters............. 473 hardware-drawing routines disabling of ...................... 472 matrix hardware routines enabling of ...................... 473 mouse (middle) for cut and paste, disabling of ...................... 474 reverse black and white setting of ................. 473, 475 software double-buffering enabling of .............. 472, 475 Text background color enabling of ...................... 473 X Graphics Context caching enabling of ...................... 474 Workstation/Window ......................... 469 activate ....................................... 476 background color, setting............ 448 bitplane masking......................... 451 bitplane writemask for Locator echo ................... 476 clear .............................................. 32 color map index .......................... 453 Version 6.2a- 26 May 2006 coordinate conversion .................460 create ..........................................470 create with command line parameters ......................478 deactivate....................................476 destroy ........................................476 externally created ..................441 Events .........................................462 externally created destroy...................................441 Locator echo type........................476 number ........................................426 options.........................................475 query Window attributes..............480 query Workstation attributes .......482 writemask ....................................454 World Coordinate Scale Factor .293, 488 setting value ................................487 X X Graphics Context caching enabling Workstation for .............474 XOR operation ..................................317 Y yes flag..............................................345 yes or no query user ...................................308 Z zoom .................................................434 SL-GMS Function Reference xvi Function Name Index G gmsAddLibPath( ) ...................... 62 gmsAddUserFctn( ) .................. 418 gmsAllVarsChanged( ) ............... 85 gmsAMove2( ) .............................. 5 gmsAMoveX( ) .............................. 5 gmsAMoveY( ) .............................. 5 gmsArcLength( ) ....................... 340 gmsARotZ( ) ................................. 8 gmsAScale( ) .............................. 10 gmsAScaleX( ) ........................... 10 gmsAScaleY( ) ........................... 10 gmsAskLine( ) .......................... 308 gmsASTran( ) ........................... 164 gmsATran( ) .............................. 342 gmsAutoUpdateMode( ) ............ 85 gmsBackgrFlag( ) ....................... 15 gmsBatchErase( ) ...................... 78 gmsBatchEraseMode( ) ............. 78 gmsBColor( ) ............................ 396 gmsBitmap( ) .............................. 20 gmsBitmapFlag( ) ....................... 20 gmsCASca2( ) ............................ 10 gmsCASTran( ) ......................... 164 gmsCATran( ) ............................ 342 gmsCenter( ) .............................. 24 gmsCGMGet( ) ......................... 240 gmsChdir( ) ................................. 62 gmsCir2( ) ................................... 28 gmsCirc( ) ................................... 28 gmsClassAddMethod( ) ..... 52, 356 gmsClear( ) ................................. 32 gmsClip( ) ................................. 426 gmsClone( ) ................................ 33 gmsClose( ) .............................. 344 gmsClosed( ) .............................. 34 gmsCloseGroup( ) .................... 185 gmsClrAllWs( ) ........................... 32 gmsCompareVersion( ) ............ 347 Version 6.2a- 26 May 2006 gmsCoordLimits( ) ................... 174 gmsCrashHandlerFctn( ) ......... 411 gmsCRMv2( ) ........................... 325 gmsCRRotz( ) .......................... 328 gmsCRSca2( ) .......................... 330 gmsCRSTran( ) ........................ 167 gmsCRTran( ) ........................... 333 gmsCSpline( ) .......................... 350 gmsCTB( ) .................................. 36 gmsCTr0( ) ................................ 335 gmsCurGroup( ) ......................... 40 gmsCurModel( ) ......................... 40 gmsCurrent( ) ............................. 40 gmsCurView( ) ........................... 40 gmsCWFlag( ) .......................... 340 gmsDatDsFreeAll( ) ................... 51 gmsDefu( ) ................................ 415 gmsDeGroup( ) ........................ 185 gmsDetect( ) ............................. 436 gmsDispatchInputEvents( ) ..... 130 gmsDispatchTimerEvents( ) .... 130 gmsDisplay( ) ............................. 65 gmsDoubleBufferFlag( ) ............ 69 gmsDsActivate( ) ....................... 54 gmsDsAddVarDef( ) ................... 54 gmsDsClass( ) ............................ 52 gmsDsClassFindByName( ) ...... 52 gmsDsClassInstall( ) ................. 52 gmsDsDeactivate( ) ................... 54 gmsDsFindVarDef( ) .................. 54 gmsDsInst( ) ............................... 54 gmsDsInstFree( ) ....................... 54 gmsDsListActivate( ) ................. 57 gmsDsListDeactivate( ) ............. 57 gmsDsListFree( ) ....................... 57 gmsDsListGet( ) ......................... 57 gmsDsListSave( ) ....................... 57 gmsDsListUpdate( ) ................... 57 gmsDsMsg( ) .............................. 59 gmsDsMsg2( ) ............................ 59 SL-GMS Function Reference i gmsDsMsg3( ) ............................ 59 gmsDsMsg4( ) ............................ 59 gmsDsObjFree( ) ........................ 57 gmsDsObjNew( ) ........................ 57 gmsDsPMsg( ) ............................ 59 gmsDsPMsg1( ) .......................... 59 gmsDsPMsg2( ) .......................... 59 gmsDsPMsg3( ) .......................... 59 gmsDsPMsg4( ) .......................... 59 gmsDsUpdate( ) ......................... 54 gmsDsVarDefFree( ) .................. 54 gmsDump( ) ................................ 68 gmsDumpViews( ) ...................... 68 gmsDynEnd( ) ............................ 81 gmsDynInit( ) .............................. 81 gmsDynInitNoMarks( ) ............... 81 gmsDynRestore( ) ...................... 81 gmsDynStr( ) .............................. 70 gmsDynUpdArrayFlag( ) ............ 85 gmsDynUpdate( ) ....................... 81 gmsDynUpdateMode( ) ............. 85 gmsEColor( ) .............................. 36 gmsEndCurrent( ) ...................... 40 gmsEndGroup( ) ....................... 185 gmsEndModel( ) ....................... 237 gmsEndView( ) ......................... 426 gmsErase( ) ................................ 65 gmsEStyle( ) ............................. 391 gmsEvAction( ) ......................... 120 gmsEvData( ) ........................... 120 gmsEvent( ) .............................. 120 gmsEventPriority( ) .................. 130 gmsEvExtent( ) ......................... 120 gmsEvKeysym( ) ...................... 120 gmsEvModifiers( ) .................... 120 gmsEvObject( ) ........................ 120 gmsEvPoint( ) ........................... 120 gmsEvStringC( ) ....................... 120 gmsEvStringSO( ) .................... 120 gmsEvTime( ) ........................... 120 Version 6.2a- 26 May 2006 gmsEvTrigger( ) ....................... 120 gmsEvType( ) ........................... 120 gmsEvView( ) ........................... 120 gmsEvWorkst( ) ....................... 120 gmsEWidth( ) ........................... 118 gmsExit( ) ................................. 344 gmsExtentMode( ) ..................... 85 gmsExternalEventLoopFlag( ) 140 gmsExtSubModMode( ) ........... 240 gmsFALibPaths( ) ...................... 62 gmsFastDynPropMode( ) .......... 85 gmsFCir2( ) ................................ 28 gmsFCirc( ) ................................. 28 gmsFColor( ) .............................. 36 gmsFDir( ) ................................ 148 gmsFGradient( ) ....................... 171 gmsFilerDataPseudoFile( ) ..... 244 gmsFilerDataSize( ) ................. 244 gmsFilerFctn( ) ......................... 244 gmsFilled( ) .............................. 151 gmsFillGroup( ) ........................ 185 gmsFillGroupFlags( ) ............... 185 gmsFindByName( ) .................. 157 gmsFindObject( ) ..................... 157 gmsFindVarDefAll( ) ................ 107 gmsFInter( ) .............................. 391 gmsFKeyProcess( ) ................. 170 gmsFPercent( ) ........................ 148 gmsFPie( ) ................................ 282 gmsFPie2( ) .............................. 282 gmsFPolygon( ) ........................ 296 gmsFRect( ) .............................. 319 gmsFreeAllVarDefs( ) .............. 107 gmsFSec( ) ............................... 337 gmsFSec2( ) ............................. 337 gmsFSec3( ) ............................. 337 gmsFStyle( ) ............................. 391 gmsFTRect( ) ........................... 319 gmsGenerateLocFileSO( ) ...... 190 gmsGraphAxis( ) ...................... 174 SL-GMS Function Reference ii gmsGraphTrace( ) .................... 178 gmsGrid( ) ................................. 181 gmsGridSize( ) ......................... 181 gmsGridSizeX( ) ....................... 181 gmsGridSizeY( ) ....................... 181 gmsGroup( ) ............................. 185 gmsHilite( ) ................................. 65 gmsImmu( ) .............................. 415 gmsInitGismos( ) ...................... 169 gmsInitStates( ) ........................ 359 gmsInitStatesOnWs( ) ............. 359 gmsInsExplode( ) ..................... 261 gmsL10nInit( ) .......................... 190 gmsL10nStr( ) ........................... 190 gmsLAMove2( ) ............................ 5 gmsLAMoveX( ) ............................ 5 gmsLAMoveY( ) ............................ 5 gmsLArcLength( ) .................... 340 gmsLARotZ( ) ............................... 8 gmsLAScale( ) ............................ 10 gmsLAScaleX( ) ......................... 10 gmsLAScaleY( ) ......................... 10 gmsLASTran( ) ......................... 164 gmsLATran( ) ............................ 342 gmsLBColor( ) .......................... 396 gmsLBitmapFlag( ) .................... 20 gmsLCenter( ) ............................ 24 gmsLClone( ) .............................. 33 gmsLClosed( ) ............................ 34 gmsLCloseGroup( ) ................. 185 gmsLDeGroup( ) ...................... 185 gmsLDetect( ) ........................... 436 gmsLDisplay( ) ........................... 65 gmsLEColor( ) ............................ 36 gmsLErase( ) .............................. 65 gmsLEStyle( ) ........................... 391 gmsLEWidth( ) .......................... 118 gmsLFColor( ) ............................ 36 gmsLFDir( ) ............................... 148 gmsLFGradient( ) ..................... 171 Version 6.2a- 26 May 2006 gmsLFilled( ) ............................ 151 gmsLFillGroupFlags( ) ............. 185 gmsLFInter( ) ............................ 391 gmsLFPercent( ) ...................... 148 gmsLFStyle( ) ........................... 391 gmsLGridSize( ) ....................... 181 gmsLGridSizeX( ) .................... 181 gmsLGridSizeY( ) .................... 181 gmsLHilite( ) ............................... 65 gmsLine( ) ................................ 214 gmsLMColor( ) ........................... 36 gmsLMkSpline( ) ...................... 350 gmsLMSize( ) ........................... 234 gmsLMStyle( ) .......................... 391 gmsLObjFree( ) ........................ 162 gmsLOpenGroup( ) .................. 185 gmsLPFndPt( ) ......................... 287 gmsLPoints( ) ........................... 290 gmsLQExtCenter( ) .................. 143 gmsLQExtent( ) ........................ 143 gmsLQPointList( ) .................... 287 gmsLQXPointList( ) .................. 287 gmsLRadius( ) .......................... 310 gmsLRastOp( ) ......................... 316 gmsLRefPoint( ) ....................... 322 gmsLRefPointX( ) ..................... 322 gmsLRefPointY( ) ..................... 322 gmsLRMove2( ) ........................ 325 gmsLRMoveX( ) ....................... 325 gmsLRMoveY( ) ....................... 325 gmsLRRotZ( ) ........................... 328 gmsLRScale( ) ......................... 330 gmsLRScaleX( ) ....................... 330 gmsLRScaleY( ) ....................... 330 gmsLRSTran( ) ......................... 167 gmsLRTran( ) ............................ 333 gmsLStartAngle( ) .................... 340 gmsLStress( ) ........................... 389 gmsLTAlign( ) ............................ 396 gmsLTColor( ) ............................. 36 SL-GMS Function Reference iii gmsLTFont( ) ............................ 396 gmsLTHeight( ) ......................... 396 gmsLTPath( ) ............................ 396 gmsLTPrec( ) ............................ 396 gmsLTran0( ) ............................. 335 gmsLTRectTextConstraint( ) .... 409 gmsLTSize( ) ............................ 396 gmsLTStr( ) ....................... 396, 401 gmsLUnFillGroup( ) ................. 185 gmsLUserData( ) ...................... 422 gmsLVis( ) ................................. 436 gmsLXTran( ) .............................. 13 gmsLXTran1( ) ............................ 13 gmsM2Get( ) ............................. 240 gmsM2Save( ) .......................... 240 gmsM2XGet( ) .......................... 240 gmsMain( ) ................................ 223 gmsMainInit( ) .......................... 223 gmsMainInitStr( ) ..................... 223 gmsMainLoop( ) ....................... 223 gmsMainStr( ) ........................... 223 gmsMajorSpacing( ) ................. 174 gmsMAMove2( ) ........................... 5 gmsMAMoveX( ) ........................... 5 gmsMAMoveY( ) ........................... 5 gmsMark( ) ............................... 233 gmsMARotZ( ) .............................. 8 gmsMAScale( ) ........................... 10 gmsMAScaleX( ) ........................ 10 gmsMAScaleY( ) ........................ 10 gmsMASTran( ) ........................ 164 gmsMATran( ) ........................... 342 gmsMBColor( ) ......................... 396 gmsMBitmapFlag( ) ................... 20 gmsMClosed( ) ........................... 34 gmsMColor( ) .............................. 36 gmsMDetect( ) .......................... 436 gmsMEColor( ) ........................... 36 gmsMEStyle( ) .......................... 391 gmsMEWidth( ) ......................... 118 Version 6.2a- 26 May 2006 gmsMExtToLoc( ) ..................... 394 gmsMFColor( ) ........................... 36 gmsMFDir( ) ............................. 148 gmsMFilled( ) ........................... 151 gmsMFInter( ) ........................... 391 gmsMFPercent( ) ..................... 148 gmsMFStyle( ) .......................... 391 gmsMGet( ) .............................. 240 gmsMGetUserHeaderStr( ) ..... 258 gmsMGridSize( ) ...................... 181 gmsMGridSizeX( ) ................... 181 gmsMGridSizeY( ) ................... 181 gmsMGSave( ) ......................... 240 gmsMinorSpacing( ) ................ 174 gmsMLocToExt( ) ..................... 394 gmsMMColor( ) .......................... 36 gmsMMerge( ) .......................... 240 gmsMMSize( ) .......................... 234 gmsMMStyle( ) ......................... 391 gmsModApplyLocFileSO( ) ..... 190 gmsModCacheCapacity( ) ....... 269 gmsModCacheCount( ) ........... 269 gmsModDynInitVarDefTable( ) .. 96 gmsModel( ) ............................. 237 gmsModelWithParts( ) ............. 237 gmsModInst( ) .......................... 261 gmsModInst2( ) ........................ 261 gmsModNonReplicate( ) ......... 261 gmsModPermanent( ) .............. 261 gmsMRastOp( ) ........................ 316 gmsMRMove2( ) ....................... 325 gmsMRMoveX( ) ...................... 325 gmsMRMoveY( ) ...................... 325 gmsMRRotZ( ) .......................... 328 gmsMRScale( ) ........................ 330 gmsMRScaleX( ) ...................... 330 gmsMRScaleY( ) ...................... 330 gmsMRSTran( ) ........................ 167 gmsMRTran( ) ........................... 333 gmsMSave( ) ............................ 240 SL-GMS Function Reference iv gmsMSize( ) ............................. 234 gmsMStress( ) .......................... 389 gmsMStyle( ) ............................ 391 gmsMTAlign( ) .......................... 396 gmsMTColor( ) ........................... 36 gmsMTFont( ) ........................... 396 gmsMTHeight( ) ....................... 396 gmsMTPath( ) ........................... 396 gmsMTPrec( ) ........................... 396 gmsMTran0( ) ........................... 335 gmsMTRectTextConstraint( ) .. 409 gmsMtrFlag( ) ........................... 236 gmsMTSize( ) ........................... 396 gmsMUserHeaderStr( ) ........... 258 gmsMVis( ) ............................... 436 gmsMXGet( ) ............................ 240 gmsNDCScale( ) ...................... 273 gmsNoErase( ) ........................... 78 gmsNoFlags( ) ............................ 85 gmsNoFlagsMode( ) .................. 85 gmsNonWsLowEventFctn( ) .... 462 gmsNoUpdImmu( ) ................... 415 gmsNPXY( ) .............................. 273 gmsObjFree( ) .......................... 162 gmsObjIsClass( ) ....................... 30 gmsObjIsClassName( ) ............. 30 gmsObjNameStr( ) ................... 275 gmsOpenGroup( ) .................... 185 gmsPan( ) ................................. 434 gmsPartRpPs( ) ........................ 290 gmsPGet( ) ............................... 306 gmsPie( ) .................................. 282 gmsPie2( ) ................................ 282 gmsPlotClear( ) ........................ 284 gmsPlotData( ) ......................... 284 gmsPlotDataX( ) ....................... 284 gmsPlotDataY( ) ....................... 284 gmsPlotReset( ) ....................... 284 gmsPlotShiftX( ) ....................... 284 gmsPlotShiftY( ) ....................... 284 Version 6.2a- 26 May 2006 gmsPMerge( ) .......................... 306 gmsPoints( ) ............................. 290 gmsPolygon( ) .......................... 296 gmsPopOff( ) ............................ 311 gmsPopOn( ) ............................ 311 gmsPopReset( ) ....................... 311 gmsPort( ) ................................. 431 gmsPortXY( ) ............................ 431 gmsProcessLowEvent( ) ......... 140 gmsProject( ) ............................ 306 gmsPSave( ) ............................. 306 gmsPsLViewWrite( ) ................ 298 gmsPsPolyMaxPoints( ) .......... 298 gmsPsSetParams( ) ................. 298 gmsPsViewWrite( ) .................. 298 gmsPsWsProcArgs( ) .............. 298 gmsPsWsProcArgsStr( ) ......... 298 gmsQAllStates( ) ...................... 378 gmsQArcLength( ) ................... 340 gmsQAutoUpdateMode( ) ......... 85 gmsQBackgrFlag( ) .................... 15 gmsQBColor( ) ......................... 407 gmsQBitmapFlag( ) .................... 20 gmsQCenter( ) ........................... 24 gmsQClosed( ) ........................... 34 gmsQColor( ) .............................. 36 gmsQConfig( ) .......................... 347 gmsQCurGroup( ) ...................... 40 gmsQCurModel( ) ...................... 40 gmsQCurrent( ) .......................... 40 gmsQCurView( ) ........................ 40 gmsQDefaultWsClass( ) .......... 482 gmsQDefRefPt( ) ..................... 322 gmsQDetect( ) .......................... 436 gmsQDisplayId( ) ..................... 482 gmsQDynStr( ) ........................... 70 gmsQDynStrList( ) ..................... 70 gmsQDynUpdateMode( ) .......... 85 gmsQEColor( ) ........................... 36 gmsQEStyle( ) .......................... 391 SL-GMS Function Reference v gmsQEvAction( ) ...................... 132 gmsQEvButtons( ) .................... 132 gmsQEvData( ) ......................... 132 gmsQEvExtent( ) ...................... 132 gmsQEvKeysym( ) ................... 132 gmsQEvModifiers( ) ................. 132 gmsQEvObject( ) ...................... 132 gmsQEvPoint( ) ........................ 132 gmsQEvStringC( ) .................... 132 gmsQEvStringSO( ) ................. 132 gmsQEvTime( ) ........................ 132 gmsQEvTrigger( ) ..................... 132 gmsQEvType( ) ......................... 132 gmsQEvView( ) ........................ 132 gmsQEvViewIndex( ) ............... 132 gmsQEvWorkst( ) ..................... 132 gmsQEWidth( ) ......................... 118 gmsQExtCenter( ) .................... 143 gmsQExtent( ) .......................... 143 gmsQExtentMode( ) ................... 85 gmsQExternalEventLoopFlag( ) 140 gmsQExtModelList( ) ............... 237 gmsQExtSubModMode( ) ........ 240 gmsQFastDynPropMode( ) ........ 85 gmsQFColor( ) ............................ 36 gmsQFDir( ) .............................. 148 gmsQFilerDataAction( ) ........... 244 gmsQFilerDataFilename( ) ...... 244 gmsQFilerDataFiler( ) .............. 244 gmsQFilerDataPseudoFile( ) .. 244 gmsQFilerDataSize( ) .............. 244 gmsQFilerDataType( ) ............. 244 gmsQFilled( ) ............................ 151 gmsQFInter( ) ........................... 391 gmsQFPercent( ) ...................... 148 gmsQFStyle( ) .......................... 391 gmsQGismoEvent( ) ................ 130 gmsQGmsHome( ) ................... 346 gmsQGridSizeX( ) .................... 181 gmsQGridSizeY( ) .................... 181 Version 6.2a- 26 May 2006 gmsQLocModelList( ) .............. 237 gmsQMaxTraceLength( ) ......... 178 gmsQMColor( ) ........................... 36 gmsQModCacheCapacity( ) .... 269 gmsQModCacheCount( ) ........ 269 gmsQModelList( ) .................... 237 gmsQModNonReplicate( ) ....... 261 gmsQModPermanent( ) ........... 261 gmsQMSize( ) .......................... 234 gmsQMStyle( ) ......................... 391 gmsQMUserHeaderStr( ) ........ 258 gmsQNoFlagsMode( ) ............... 85 gmsQNumParts( ) .................... 278 gmsQNumTraces( ) .................. 278 gmsQNumVarRefs( ) ................. 94 gmsQObjNameStr( ) ................ 275 gmsQOwner( ) .......................... 276 gmsQOwnerList( ) .................... 276 gmsQOwnerModel( ) ............... 276 gmsQOwnerState( ) ................. 276 gmsQOwnerView( ) ................. 276 gmsQPartExtent( ) ................... 143 gmsQPartList( ) ........................ 278 gmsQPartNum( ) ...................... 278 gmsQPartPointList( ) ............... 287 gmsQPointList( ) ...................... 287 gmsQRadius( ) ......................... 310 gmsQRastOp( ) .......................... 20 gmsQRefPoint( ) ...................... 322 gmsQRefPointX( ) .................... 322 gmsQRefPointY( ) .................... 322 gmsQReleaseDate( ) ............... 347 gmsQRenamedStr( ) .................. 70 gmsQScreenExt( ) ................... 482 gmsQSRStringSO( ) ................ 190 gmsQStartAngle( ) ................... 340 gmsQStClassName( ) .............. 378 gmsQStCurState( ) .................. 378 gmsQStEvState( ) .................... 378 gmsQStIsActive( ) .................... 378 SL-GMS Function Reference vi gmsQStModel( ) ....................... 378 gmsQStModelList( ) ................. 378 gmsQStModelName( ) ............. 378 gmsQStName( ) ....................... 378 gmsQStress( ) .......................... 389 gmsQStringC( ) ........................ 208 gmsQStringWC( ) ..................... 208 gmsQStStrMsgState( ) ............ 378 gmsQStSubStates( ) ................ 378 gmsQStSuperState( ) .............. 378 gmsQStTextEditObj( ) .............. 378 gmsQStTopState( ) .................. 378 gmsQStVarDefAddress( ) ........ 386 gmsQStVarDefCount( ) ............ 386 gmsQStVarDefSize( ) .............. 386 gmsQStView( ) ......................... 378 gmsQStViewName( ) ............... 378 gmsQStWorkst( ) ...................... 378 gmsQStWorkstName( ) ............ 378 gmsQSubModel( ) .................... 261 gmsQSubModelName( ) .......... 261 gmsQSubModReplicateMode( ) 261 gmsQTAlignX( ) ........................ 407 gmsQTAlignY( ) ........................ 407 gmsQTColor( ) ............................ 36 gmsQTFont( ) ........................... 407 gmsQTHeight( ) ........................ 407 gmsQTimerEventMask( ) ......... 138 gmsQTPath( ) ........................... 407 gmsQTPrec( ) ........................... 407 gmsQTraceNum( ) .................... 278 gmsQTrapSignalMode( ) .......... 411 gmsQTRectTextConstraint( ) ... 409 gmsQTSizeX( ) ......................... 407 gmsQTSizeY( ) ......................... 407 gmsQTStringC( ) ...................... 401 gmsQTStringSO( ) ................... 401 gmsQTStringWC( ) .................. 401 gmsQuery( ) ............................. 308 gmsQuit( ) ................................. 344 Version 6.2a- 26 May 2006 gmsQUserData( ) ..................... 422 gmsQUserWord( ) .................... 422 gmsQUseShadowMode( ) ......... 85 gmsQVarDefAddress( ) ............. 90 gmsQVarDefCount( ) ................. 90 gmsQVarDefName( ) ................. 90 gmsQVarDefSize( ) .................... 90 gmsQVarDefType( ) ................... 90 gmsQVarRefAddr( ) ................... 94 gmsQVarRefName( ) ................. 94 gmsQVDTCount( ) ..................... 96 gmsQVDTVarDefAtIndex( ) ....... 96 gmsQVDTVarDefByName( ) ..... 96 gmsQVersion( ) ........................ 347 gmsQVis( ) ............................... 436 gmsQVuLocCaptureMode( ) ... 424 gmsQWidgetId( ) ...................... 482 gmsQWinBannerName( ) ........ 480 gmsQWindowId( ) .................... 480 gmsQWinExt( ) ......................... 480 gmsQWinIconName( ) ............. 480 gmsQWorkst( ) ......................... 480 gmsQWsBackgroundColor( ) .. 448 gmsQWsBitplaneMask( ) ........ 451 gmsQWsColDef( ) .................... 482 gmsQWsColormapId( ) ............ 482 gmsQWsColormapIndex( ) ...... 482 gmsQWsCursor( ) ...................... 43 gmsQWsCursorInfo( ) ................ 43 gmsQWsCursorNames( ) .......... 43 gmsQWsEchoMask( ) .............. 482 gmsQWsEventMask( ) ............. 462 gmsQWsFontNameIndex( ) ..... 160 gmsQWsNumColors( ) ............ 482 gmsQWsPopMode( ) ............... 482 gmsQWsView( ) ....................... 482 gmsQWsViewport( ) ................ 482 gmsQXPointList( ) .................... 287 gmsRadius( ) ............................ 310 gmsRastOp( ) ........................... 316 SL-GMS Function Reference vii gmsRect( ) ................................ 319 gmsRedraw( ) ........................... 415 gmsRedrawNoErase( ) ............ 415 gmsRefPoint( ) ......................... 322 gmsRefPointX( ) ....................... 322 gmsRefPointY( ) ....................... 322 gmsRemUserFctn( ) ................. 418 gmsRemVarDefLinks( ) ........... 107 gmsRenamedStr( ) ..................... 70 gmsRenamedStrNoRelink( ) ..... 70 gmsRenVarStrConstReplSO( ) . 70 gmsResChk( ) .......................... 426 gmsRFRect( ) ........................... 319 gmsRFTRect( ) ......................... 319 gmsRMove2( ) .......................... 325 gmsRMoveX( ) .......................... 325 gmsRMoveY( ) .......................... 325 gmsRRect( ) ............................. 319 gmsRRotZ( ) ............................. 328 gmsRScale( ) ............................ 330 gmsRScaleX( ) ......................... 330 gmsRScaleY( ) ......................... 330 gmsRSTran( ) ........................... 167 gmsRTran( ) .............................. 333 gmsRvrsPts( ) ........................... 290 gmsSec2( ) ............................... 337 gmsSec3( ) ............................... 337 gmsSect( ) ................................ 337 gmsSetFileFindFctn( ) ............. 153 gmsSetTraps( ) ......................... 411 gmsSetup( ) .............................. 344 gmsSNPXY( ) ........................... 273 gmsSpline( ) ............................. 350 gmsSRApplyLocFileSO( ) ....... 190 gmsSt30Flag( ) ......................... 375 gmsStActivate( ) ....................... 363 gmsStAddModelName( ) ......... 363 gmsStartAngle( ) ...................... 340 gmsStateClass( ) ..................... 356 gmsStateInst( ) ......................... 363 Version 6.2a- 26 May 2006 gmsStAutoDeactFlag( ) ........... 352 gmsStClassFindByName( ) ..... 375 gmsStClassInstall( ) ................ 356 gmsStClearFlag( ) .................... 352 gmsStClrModelNames( ) ......... 363 gmsStD1Flag( ) ........................ 352 gmsStDatFlag( ) ....................... 352 gmsStDeactivate( ) .................. 363 gmsStDebugFlag( ) .................. 375 gmsStEventFctn( ) ................... 375 gmsStFindByName( ) .............. 375 gmsStFindVarDefAll( ) ............. 382 gmsStFindVarDefByAddrAll( ) 382 gmsStFindVarDefByNameAll( ) 382 gmsStFreeAllVarDefs( ) ........... 382 gmsStFreeFlag( ) ..................... 352 gmsStGismoFlag( ) .................. 352 gmsStLocMotionEnable( ) ....... 359 gmsStM2Flag( ) ....................... 375 gmsStMark( ) ............................ 369 gmsStPopFlag( ) ...................... 352 gmsStPStrMsg( ) ...................... 371 gmsStPStrMsg1( ) ................... 371 gmsStPStrMsg2( ) ................... 371 gmsStReset( ) .......................... 369 gmsStResetToMark( ) .............. 369 gmsStResetToTop( ) ................ 369 gmsStress( ) ............................. 389 gmsStringC( ) ........................... 208 gmsStringEmpty( ) ................... 208 gmsStringResource( ) ............. 190 gmsStringSetC( ) ..................... 208 gmsStringSetWC( ) .................. 208 gmsStringWC( ) ....................... 208 gmsStStrMsg( ) ........................ 371 gmsStStrMsg1( ) ...................... 371 gmsStStrMsg2( ) ...................... 371 gmsStStrMsgNI( ) .................... 371 gmsStStrMsgNI1( ) .................. 371 gmsStStrMsgNI2( ) .................. 371 SL-GMS Function Reference viii gmsStTextEditObj( ) ................. 363 gmsStTextEditObjName( ) ....... 363 gmsStUpdFlag( ) ...................... 352 gmsStVarChanged( ) ............... 382 gmsStVarDefAddress( ) ........... 386 gmsStVarDefChanged( ) ......... 382 gmsStVarDefCount( ) ............... 386 gmsStVarDefine( ) .................... 382 gmsStVarDefineChanged( ) .... 382 gmsStVarDefSize( ) ................. 386 gmsStVarInitFctn( ) .................. 382 gmsStViewName( ) .................. 363 gmsStVisFlag( ) ........................ 352 gmsStWasFreed( ) ................... 375 gmsStWorkstName( ) .............. 363 gmsSubModelName( ) ............. 261 gmsSubModReplicateMode( ) 261 gmsSWPXY( ) .......................... 487 gmsTAlign( ) ............................. 396 gmsTColor( ) .............................. 36 gmsText( ) ................................. 401 gmsTFont( ) .............................. 396 gmsTHeight( ) ........................... 396 gmsTimeLevel( ) ....................... 281 gmsTimerEventFctn( ) ............. 138 gmsTimerPeriod( ) ................... 138 gmsTPath( ) .............................. 396 gmsTPrec( ) .............................. 396 gmsTPrec0RotFlag( ) .............. 396 gmsTran( ) ................................. 342 gmsTran0( ) .............................. 335 gmsTrapSignalMode( ) ............ 411 gmsTRectTextConstraint( ) ..... 409 gmsTRepl( ) .............................. 401 gmsTSize( ) .............................. 396 gmsTStr( ) ................................. 396 gmsTStringC( ) ......................... 401 gmsTStringSO( ) ...................... 401 gmsTStringWC( ) ..................... 401 gmsUnFillGroup( ) ................... 185 Version 6.2a- 26 May 2006 gmsUnlinkVarDefs( ) ................ 107 gmsUpdate( ) ........................... 415 gmsUpdateDisplayOnly( ) ....... 415 gmsUpdateEraseOnly( ) .......... 415 gmsUpdateExtents( ) ............... 415 gmsUserData( ) ........................ 422 gmsUserMarkerFctn( ) ............ 229 gmsUserWord( ) ....................... 422 gmsUseShadowMode( ) ............ 85 gmsValueLimits( ) .................... 174 gmsVarChanged( ) ................... 107 gmsVarChangedAll( ) .............. 107 gmsVarDefAddress( ) ................ 90 gmsVarDefChanged( ) ............. 107 gmsVarDefCount( ) .................... 90 gmsVarDefine( ) ....................... 107 gmsVarDefineChanged( ) ........ 107 gmsVarDefineNoTable( ) ......... 107 gmsVarDefSize( ) ....................... 90 gmsVarDefType( ) ...................... 90 gmsVarInitFctn( ) ....................... 81 gmsVarTypeDefine( ) ............... 107 gmsVDTIndicesChanged( ) ....... 96 gmsView( ) ................................ 426 gmsVis( ) .................................. 436 gmsVuDim( ) ............................. 426 gmsVuFindObject( ) ................. 157 gmsVuList( ) ............................. 426 gmsVuLocCaptureMode( ) ...... 424 gmsVuPri( ) ............................... 426 gmsVuRedrawOnNextUpdate( ) 424 gmsVuRFile( ) .......................... 314 gmsVuRRest( ) ......................... 314 gmsVuRSave( ) ........................ 314 gmsVuWorkst( ) ........................ 426 gmsWaitEvent( ) ....................... 130 gmsWCoordX( ) ....................... 487 gmsWCoordY( ) ....................... 487 gmsWCScale( ) ........................ 487 gmsWinBannerName( ) ........... 439 SL-GMS Function Reference ix gmsWinClear( ) ........................ 439 gmsWind( ) ............................... 431 gmsWinDestroy( ) .................... 439 gmsWindowDestructionFctn( ) 439 gmsWindXY( ) .......................... 431 gmsWinExt( ) ............................ 439 gmsWinFlags( ) ........................ 439 gmsWinIconName( ) ................ 439 gmsWinMap( ) .......................... 439 gmsWinPop( ) ........................... 439 gmsWinPts( ) ............................ 431 gmsWinPush( ) ......................... 439 gmsWinSetFocus( ) ................. 439 gmsWinUnmap( ) ..................... 439 gmsWorkst( ) ............................ 469 gmsWPoint( ) ............................ 487 gmsWPXY( ) ............................. 487 gmsWsAct( ) ............................. 469 gmsWsAddCursor( ) .................. 43 gmsWsAddEvent( ) .................. 120 gmsWsBackgroundColor( ) ..... 448 gmsWsBitplaneMask( ) ............ 451 gmsWsClear( ) ........................... 32 gmsWsClose( ) ......................... 469 gmsWsColDef( ) ....................... 451 gmsWsCursor( ) ......................... 43 gmsWsDeact( ) ......................... 469 gmsWsDefaultOpts( ) .............. 469 gmsWsEchoMask( ) ................. 469 gmsWsEventFctn( ) ................. 462 gmsWsEventMask( ) ................ 462 gmsWsKbdFilterFctn( ) ............ 462 gmsWsLocEcho( ) .................... 469 gmsWsLowEventFctn( ) ........... 462 gmsWsNum( ) ........................... 426 gmsWsPointDCToIC( ) ............. 460 gmsWsPort( ) ........................... 439 gmsWsPortXY( ) ...................... 439 gmsWsProcArgs( ) ................... 469 gmsWsProcArgsStr( ) .............. 469 Version 6.2a- 26 May 2006 gmsWsSoftClip( ) ..................... 426 gmsWsSynchronize( ) ............. 462 gmsWsTextEditObj( ) ............... 462 gmsWsWind( ) .......................... 439 gmsWsWindXY( ) ..................... 439 gmsWValue( ) ........................... 487 gmsWVXY( ) ............................. 431 gmsXKillTimer( ) ...................... 411 gmsXTran( ) ................................ 13 gmsXTran1( ) .............................. 13 gmsXValueLimits( ) .................. 178 gmsYesFlag( ) .......................... 344 gmsYValueLimits( ) .................. 178 gmsZmIn( ) ............................... 434 gmsZmOut( ) ............................ 434 gmsZoom( ) .............................. 434 gmsZpr( ) .................................. 434 gmsZps( ) ................................. 434 M msDsMsg1( ) .............................. 59 msQVarDefTable( ) .................... 96 P pntClone( ) ................................ 292 pntFree( ) .................................. 292 pntNew( ) .................................. 292 pntNewXY( ) ............................. 292 pntSetXY( ) ............................... 292 pntX( ) ....................................... 292 pntY( ) ....................................... 292 R refAdd( ) .................................... 215 refAppend( ) ............................. 215 refAt( ) ....................................... 215 refAtInsert( ) ............................. 215 refAtPut( ) ................................. 215 refCloAll( ) ................................ 215 refCount( ) ................................ 215 SL-GMS Function Reference x refDo1All( ) ............................... 215 refDo2All( ) ............................... 215 refDo3All( ) ............................... 215 refDo4All( ) ............................... 215 refDoAll( ) ................................. 215 refDupAll( ) ............................... 215 refFilter( ) .................................. 215 refFind( ) ................................... 215 refFndName( ) .......................... 215 refFreAll( ) ................................. 215 refFree( ) ................................... 215 refIndex( ) ................................. 215 refKilAll( ) .................................. 215 refLast( ) ................................... 215 refNew( ) ................................... 215 refNewN( ) ................................ 215 refNewRef( ) ............................. 215 refQReference( ) ...................... 215 refQSuccessor( ) ...................... 215 refRemove( ) ............................. 215 refReplace( ) ............................. 215 Version 6.2a- 26 May 2006 SL-GMS Function Reference xi