sl-gms referencesldownloads.sl.com/docs/c++dev/6.2x/pdffiles/gref/gref.pdf · version 6.2a- 26 may...

Part Number GREF-360526

SL-GMS® Reference

SL Corporation®

OBJECT-ORIENTED

GRAPHICAL MODELING SYSTEM

Version 6.2a- 26 May 2006

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

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

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

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

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

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

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

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

LIMITATIONS ON USE

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

SL CORPORATION240 Tamal Vista Blvd.

Corte Madera, CA 94925

CUSTOMER SUPPORTPhone 800.548.6881 (inside U.S.)

415.927.8400Fax 415.927.8401E-mail [email protected]

5/26/06 v6.2x

Part Number GREF-360526

Table of Contents
1. SL-GMS Reference
How to use this manual ................................................................ 1-1

2. Overview of SL-GMSIntroduction ................................................................................. 2-1Mapping application library ......................................................... 2-6Programming frameworks ............................................................ 2-8File types in SL-GMS .................................................................. 2-11Localization................................................................................. 2-14

3. DynamicsIntroduction ................................................................................. 3-1Actions ........................................................................................ 3-5Display dynamics ........................................................................ 3-6Expressions ................................................................................. 3-9Input dynamics ............................................................................ 3-11Integration with native GUI control objects.................................. 3-12SubModels and dynamic instancing ............................................. 3-16Charts and Graphs as dynamic SubModels ................................... 3-21Attaching Dynamic Descriptions to Objects ................................. 3-23General syntax for display dynamic descriptions.......................... 3-27Evaluation of sample DynProps ................................................... 3-29DynProp execution ...................................................................... 3-33Using function calls ..................................................................... 3-34User-defined functions................................................................. 3-35Ranges in dynamics ..................................................................... 3-43Adding dynamics to a Model object ............................................. 3-44Erasing objects and holes ............................................................. 3-45Double buffering ......................................................................... 3-48Dynamics driven by array variables ............................................. 3-52Dynamics driven by structure variables ........................................ 3-53Renaming variables ..................................................................... 3-55RenamedVars and updating behavior ............................................ 3-57Nested variables .......................................................................... 3-59Previewing the Dynamic Behavior of Objects .............................. 3-61

4. GraphsIntroduction ................................................................................. 4-1Using Graphs ............................................................................... 4-1

SL-GMS Reference iVersion 6.2a- 26 May 2006

Graph components ....................................................................... 4-2Graph types ................................................................................. 4-3Renaming the GraphAxis variables .............................................. 4-4Renaming GraphTrace variables .................................................. 4-6Graph variables............................................................................ 4-9Renamed Graph variables: an example ........................................ 4-9Using trend Graphs: an example ................................................. 4-12Designing new Graphs ................................................................. 4-14GraphAxis objects ....................................................................... 4-16Grid GraphAxes........................................................................... 4-18Date and time GraphAxes ............................................................ 4-18Non-Graphical components of GraphAxis objects ........................ 4-26GraphTrace objects ...................................................................... 4-28Creating GraphTrace dynamics .................................................... 4-31Graph template structure .............................................................. 4-37Example Graph template Model ................................................... 4-39

5. GISMOsIntroduction ................................................................................. 5-1GISMO Construction ................................................................... 5-2Highlight Functions ..................................................................... 5-5Sample construction of a GISMO................................................. 5-7Toggle Group............................................................................... 5-15Using GISMOs ............................................................................ 5-26The GISMO Library .................................................................... 5-27

6. The Enhanced State Management SystemIntroduction ................................................................................. 6-1

7. Event HandlingIntroduction ................................................................................. 7-1Event Handling in SL-SMS.......................................................... 7-1Event codes ................................................................................. 7-3Event modifier codes ................................................................... 7-4State class event-handlers and events ........................................... 7-6Using the event query functions — examples ............................... 7-7Simulating Events ........................................................................ 7-12

SL-GMS Reference iiVersion 6.2a- 26 May 2006

8. Display of ModelsOverview ..................................................................................... 8-1Coordinate systems ...................................................................... 8-1Displaying a Model ..................................................................... 8-4

9. TextIntroduction ................................................................................. 9-1Default Fonts ............................................................................... 9-3Specifying alternative and additional fonts................................... 9-5PostScript output ......................................................................... 9-14

10. ColorIntroduction ................................................................................. 10-1Monochrome displays .................................................................. 10-1Changing SL-GMSDraw’s color palette ....................................... 10-2PostScript colors.......................................................................... 10-4Reverse video .............................................................................. 10-4Grey-scale ................................................................................... 10-4AutoCAD colors .......................................................................... 10-5Common Desktop Environment (CDE) colors .............................. 10-7

11. PerformanceIntroduction ................................................................................. 11-1Optimization by users .................................................................. 11-1Optimization by programmers...................................................... 11-5

12. The Graphical Modeling LanguageIntroduction ................................................................................. 12-1Converting Model files ................................................................ 12-5Projects ....................................................................................... 12-7

Appendix A — SL-GMS GISMO Library ReferenceIntroduction ................................................................................. A-1Standard styles of the SL-GMS GISMO Library .......................... A-1SL-GMS GISMO Library Model names ....................................... A-2GISMO construction .................................................................... A-3BUTTON GROUP ....................................................................... A-24SPECIAL PURPOSE ................................................................... A-37Scrolling functions ...................................................................... A-53NON STANDARD ....................................................................... A-76

SL-GMS Reference iiiVersion 6.2a- 26 May 2006

SL-GMS GISMO Action Functions.............................................. A-81Reserved variable names for GISMO DynProps ........................... A-108Appearance variables for GISMO DynProps ................................ A-110Appearance of BUTTON Type GISMOs ...................................... A-112

Appendix B — Glossary

Appendix C — SL-GMS Interface with the X Toolkit and X Windows

Introduction ................................................................................. C-1The SL-GMS / Xt Interface.......................................................... C-1The SL-GMS / X Interface ........................................................... C-3

Appendix D — Model UtilitiesIntroduction ................................................................................. D-1Basic Model Conversion Utilities................................................. D-2AutoCAD dxf2g ".dxf" file converter ........................................... D-4The genlocfile utility ................................................................... D-14

Appendix E — The State Management SystemIntroduction ................................................................................. E-1Components of SL-SMS .............................................................. E-1State-changing GISMOs .............................................................. E-3Attributes provided by the generic State Class ............................. E-4Building Custom State Class Objects ........................................... E-5Event-handler functions outside SL-SMS..................................... E-19

Appendix F — Datasource ManagementIntroduction ................................................................................. F-1Datasource classes and Instances ................................................. F-2Datasource files ........................................................................... F-2Types of Datasources ................................................................... F-2Using Datasources within SL-SMS .............................................. F-3On-line examples ......................................................................... F-3

Appendix G — Linking SL-GMS applicationsIntroduction ................................................................................. G-1Components of the SL-GMS Run-time Function Libraries ........... G-1PC-Intel ....................................................................................... G-4

SL-GMS Reference ivVersion 6.2a- 26 May 2006

Sun systems ................................................................................. G-7

Index

SL-GMS Reference vVersion 6.2a- 26 May 2006

List of Figures

Number Title Page

Figure 2-1: Attaching dynamics specifications to an object............................ 2-2

Figure 2-2: The SL-GMSDraw editor with the “buttons” palette active ............ 2-3

Figure 3-1: The SL-GMSDraw editor ............................................................. 3-1

Figure 3-2: DynProp containing two dynamic descriptions............................. 3-7

Figure 3-3: DynProp with unconditional display dynamics ............................. 3-7

Figure 3-4: Dynamic description with conditional display dynamics ............... 3-8

Figure 3-5: SL-GMS encapsulates control object behavior ............................ 3-13

Figure 3-6: Control Object Palette (Windows) ............................................... 3-15

Figure 3-7: Control Object Palette (Motif) ...................................................... 3-16

Figure 3-8: Building the "meter" Model.......................................................... 3-17

Figure 3-9: Instancing the "meter" Model as an external SubModel ............... 3-18

Figure 3-10: An "aircraft" Model ...................................................................... 3-19

Figure 3-11: Instances of the "aircraft" SubModel in a cockpit screen.............. 3-20

Figure 3-12: Two Instances of the Graph template "lineplot"............................ 3-21

Figure 3-13: GraphAxis and GraphTrace objects ............................................. 3-22

Figure 3-14: A DynProp in the "Object Dynamic Properties" window ............... 3-24

Figure 3-15: A DynProp indented after pressing the "Apply" button ................. 3-25

Figure 3-16: A DynProp typed incorrectly with an error on line 3 ..................... 3-26

Figure 3-17: A dialog box displaying the location of an error ........................... 3-26

Figure 3-18: General syntax for display dynamic descriptions ......................... 3-27

Figure 3-19: DynProps are executed in depth-first object hierarchy order ........ 3-33

Figure 3-20: One unconditional and two conditional dynamic descriptions....... 3-36

Figure 3-21: A user-defined function in a dynamic description ........................ 3-37

Figure 3-22: "Model Dynamic Properties" window ........................................... 3-45

Figure 3-23: Diamond with dynamics to move over a static line ....................... 3-46

Figure 3-24: Diamond moving and erasing portions of the line ........................ 3-47

Figure 3-25: Diamond moving over the line ..................................................... 3-47

Figure 3-26: Renaming the "bg_color" variable in a Model Instance ................ 3-56

Figure 3-27: "Edit Data File" window............................................................... 3-61

Figure 3-28: "Preview Options" window........................................................... 3-62

Figure 4-1: A Graph consists of GraphAxes and GraphTraces ....................... 4-2

Figure 4-2: Graph showing use of tick spacing .............................................. 4-5

SL-GMS Reference viVersion 6.2a- 26 May 2006

Figure 4-3: Graph with variables renamed (after Previewing) ........................ 4-10

Figure 4-4: Trend Graph that shifts to the left ................................................ 4-13

Figure 4-5: GraphAxis object with variables renamed to constants ................ 4-27

Figure 4-6: GraphAxis object with variables renamed to variables ................. 4-27

Figure 5-1: General structure of a GISMO DynProp ...................................... 5-2

Figure 5-2: Syntax of a typical GISMO DynProp ........................................... 5-3

Figure 5-3: Light switch ................................................................................ 5-7

Figure 5-4: Background pieces of the light switch ......................................... 5-8

Figure 5-5: Assembled background of the light switch ................................... 5-9

Figure 5-6: First part of GISMO .................................................................... 5-10

Figure 5-7: Two lines added to switch object ................................................. 5-11

Figure 5-8: "off_state" and "on_state" objects ............................................... 5-12

Figure 5-9: Placing the "off_state"/"on_state" Group on the background........ 5-13

Figure 5-10: Examples of BUTTON GROUP type GISMOs .............................. 5-15

Figure 5-11: "GISMO helper" buttons.............................................................. 5-15

Figure 5-12: Parts of the "state_0" Group from the "md_button" GISMO.......... 5-17

Figure 5-13: Parts of the "state_1" Group from the "md_button" GISMO.......... 5-18

Figure 5-14: Three Instances before and after renaming variables .................. 5-20

Figure 5-15: Using an array to control a Radio Group GISMO ......................... 5-21

Figure 5-16: Using a single variable to control a Radio Group GISMO............. 5-23

Figure 5-17: An array variable used to control a CHECK GROUP GISMO ....... 5-24

Figure 7-1: Event-handling ........................................................................... 7-2

Figure 8-1: A Model in World Coordinate space ............................................ 8-4

Figure 8-2: Mapping a Model into a View object ............................................ 8-5

Figure 8-3: Two different View WC-extents.................................................... 8-6

Figure 8-4: Mappling of a Model into a window ............................................. 8-7

Figure 8-5: A "win_size" equal to (0.4, 0.3) ................................................... 8-8

Figure 8-6: A "win_position" equal to (0.5, 0.0) ............................................. 8-10

Figure 8-7: Normalized Window Coordinates (NWC) ..................................... 8-11

Figure 8-8: Some common "win_positin_offset" values ................................. 8-12

Figure 9-1: Default Precision 0 SL-GMS Fonts .............................................. 9-1

Figure 9-2: Default Precision 0 fonts across Workstation classes .................. 9-3

Figure 9-3: Precision 1 Hershey text fonts..................................................... 9-4

Figure 9-4: An example of SL-GMS "fontdef.dat" entries ............................... 9-5

Figure 9-5: Example "fontdef.dat" for the X Window System .......................... 9-6

SL-GMS Reference viiVersion 6.2a- 26 May 2006

Figure 9-6: Sample "fontdef.dat" for a Japanese Sun Workstation ................. 9-7

Figure 9-7: Example "fontdef.dat" for a Windows NT system ......................... 9-9

Figure 9-8: An example of a Windows NT SL-GMS font name ....................... 9-11

Figure 9-9: Example "fontdef.dat" for a PostScript workstation ...................... 9-13

Figure 9-10: PostScript output for fonts with precision 0 or 2 ........................... 9-15

Figure 9-11: PostScript output for fonts with precision 1 .................................. 9-15

Figure 12-1: The SL-GML interpreter displaying the Model "cogen"................. 12-1

Figure A-1 "GISMO helper" buttons.............................................................. A-24

Figure A-2 The "state_1" object ................................................................... A-112

Figure A-3 The "state_0" object ................................................................... A-113

Figure A-4 The Group of "state_1" and "state_0".......................................... A-114

Figure A-5 Parts of the "state_1" Group ....................................................... A-117

Figure A-6 Parts of the "state_0" Group ....................................................... A-119

Figure A-7 The Group of "state_1" and "state_0".......................................... A-121

Figure G-1 The basic layers of the SL-GMS Run-time Function Libraries ...... G-1

SL-GMS Reference viiiVersion 6.2a- 26 May 2006

Version 6.2a- 26 May 2006

Sherrill−Lubinski

SL-GMS Reference

How to use this manual

This manual provides background information concerning SL-GMS con-cepts. Reference information is available in the SL-GMS® Quick Referencemanual. This manual should be consulted for information once the readeris familiar with the material presented in the Getting Started with SL-GMS®manual.

Terminology clarificationThe steps for the examples throughout this manual often state,

Clicking a button, unless otherwise specified, refers to pressing and releas-ing the left mouse button. Clicking and choosing an option from a pull-downmenu in the SL-GMSDraw editor refers to dragging — pressing the leftmouse button on the pull-down menu name, moving the mouse over thepopped-up menu, keeping the left button depressed, and then releasingthe left mouse button on the desired option.

Special keys are enclosed in angle-brackets. For example,

<RETURN>

specifies entry (pressing) of the Return key; it does not specify entry of thecharacters "<", "R", "E", "T", "U", "R", "N", and ">".

Other programming languagesFollowing standard practices in software engineering, the examples in thisbook are presented in C, which has become the language of choice fortutorial examples in the literature. The C examples are still applicable whenthe functions are called in a different programming language.

Click the ... button ... Click the ... Pull-Down orMenu and choose ...

SL-GMS Reference 1-1

12

2

Version 6.2a- 26 M

Overview of SL-GMS

Introduction

SL-GMS (SL Graphical Modeling System) is a graphics software packageused by developers to create and embed dynamic graphical screens intoapplication software. SL-GMS provides the following features

• Flexibility through object-oriented technology

• Screen Dynamics

• SubModels and dynamic instancing

• A powerful drawing tool

• High-level programming objects

• Powerful integration with native GUI control objects

• Performance optimization

• Flexible support for imported graphics

• Multiple language interfaces

• Flexible data interface

• Editor customization

• Mapping applications Library

• Numerous example applications

• Unified solution for portability and multi-platform applicationdeployment

SL-GMS Reference 2-1ay 2006

Overview of SL-GMS

Figure 2-1: Attaching dynamics specifications to an object

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

Overview of SL-GMS

The SL-GMSDraw graphical editor, provided with a Development license ofSL-GMS, is the primary tool used to create dynamic Models — a collectionof graphical objects that change in real-time in response to changes inapplication data. Models may be used as screens for the application orinstanced as a component of another Model. Instances of several differentModels may be placed together into a Palette. This Palette can be called upat any time and one or more of the predefined symbols can be selected foruse in Model construction.

Figure 2-2: The SL-GMSDraw editor with the “buttons” palette active

Display or input dynamics are implemented by attaching DynProps(Dynamic Properties) to objects with the Object Dynamic Propertiesoption of the Dynamics Pull-Down Menu in SL-GMSDraw. Applicationdevelopment time is greatly reduced as dynamic specifications (and pro-


Overview of SL-GMS

gram state sequencing as described below) are built into Models, not intoapplication code. Chapter 3 — Dynamics provides detailed informationabout dynamics specification.

User interaction is an integral part of a graphical interface. Operators mustbe able to control real-world, real-time processes through actions at themouse and/or keyboard. This interaction is commonly conducted throughinterface controls: buttons, sliders, pull-down menus, scrolling lists, and textentry boxes.

The native Control-Object Library supplied with the State-Class Librarygreatly reduces the programming effort necessary to create the completegraphical user interface for an application. In Windows 95 and Windows NTenvironments, native controls means Windows control objects and Win-dows NT control objects. In UNIX and OpenVMS environments, native con-trols generally means X-based Motif widgets.The support for native controlsets in SL-GMS is encapsulated, generic, easy-to-use, and portable acrossWindow Systems. Native controls can be added to any SL-GMS graphicalModel.

The developer can select any generic control in the library from a Palette inSL-GMSDraw. Native control attributes can be directly connected to appli-cation variables (as with any other graphical object in SL-GMS) to eitherdisplay the value of the variables or to set them in response to user actions.In addition, pre-defined callback functions are automatically attached tothese generic controls. The callbacks either set variables in response toactions or execute a message function with parameters attached to thecontrols.

SL-GMS also provides GISMOs (Graphical Interactive Screen ManagementObjects) for user interaction. A large number of ready-to-use, predefinedGISMOs are provided in the SL-GMS GISMO Library and described com-pletely in Appendix A. In addition, any SL-GMS graphical object can haveinput dynamics attached to it, and be made into a GISMO. When selected,a GISMO can highlight, call user-defined callback functions, and/or changethe current state of the application. Additional information about GISMOs isprovided in Chapter 5 — GISMOs.

SL-GMS uses a data linkage technique that can be interfaced to any dataacquisition system. Variable references in Dynamic Properties are boundwith memory locations. When SL-GMS is notified of a change in the valueat a specified memory location, the graphic objects associated with thatvalue are updated automatically. The variable reference/memory bindings


Overview of SL-GMS

are organized in tables that deliver high performance updates. Access to avariable binding table can be restricted to a single State instance, or agroup of State instances which localizes the data where it is needed andimproves performance.

Classes are provided to give the developer easy access to Model informa-tion at run-time. The list of variable references in a Model can be queried atany time. Once the list of variable references is obtained, they can bebound with data obtained from sockets, pipes, shared memory, or any othersource of data. Linkage to data and variable scoping are described in VariableHandling in the SL-GMS Examples Manual.

A currently evolving component of SL-GMS — The Datasource Manage-ment System (SL-DMS) — will ultimately eliminate all programmingrequired to connect with external data sources or internal variables.SL-DMS is described in Appendix F.

SL-GMS also simplifies the often enormous development task of managingapplication states by encapsulating the basic elements (e.g., the activewindow-manager window, Model(s), event-handlers, complex user-interac-tions such as object selection, zoom/pan, and so on, and data sources) ofdynamic graphical applications into State objects. State objects are imple-mented by the State Management System (SL-SMS) component ofSL-GMS. SL-SMS is described in Chapter 6 — The Enhanced State Man-agement System.

Many file converters are distributed with SL-GMS. For example, with them1g script, Models may be converted to ASCII format for portability acrossall SL-supported platforms, for updating to newer versions of SL-GMS, andfor global editing with any standard text editor. Another utility, dxf2g, con-verts AutoCAD “.dxf” (Data Exchange Format) files to SL-GMS “.g” (ASCII)Model files. The m1m2 script allows conversion of Models so thatscreen-Model input is accomplished in one quick read, thereby improvingapplication performance.

The SL-GMS run-time Functions, provided with a Development or arun-time license, are linked with the application program to load and runModels. Specific instructions for linking are provided in Appendix G.


Overview of SL-GMS

Mapping application library

Applications that use map and network data have special requirements dueto the large number of objects and images, and the navigation and viewingtechniques used with such large data sets. The SL-GMS Mapping applica-tion library provides developers with the capability of creating interactive,animated graphics that satisfy the needs of map and network based appli-cations.

Support of Imported Vector BackgroundsUtilities are provided for converting map data into SL-GMS Models that canbe layered and tiled for increased viewing performance. A large, complexMap Model can be seperated into overlapping or stacked Models whichserve as Map layers. For example, interstate highways in one Model, rail-roads in another Model, bodies of water in a Model, major streets in a Mod-el, and neighborhood streets in a Model. Then, Map layers can be dividedinto adjoining rectangular Models called tiles.

Automatic management of Map tilesThe SL-GMS Mapping Library controls the movement of Models to andfrom memory based on the current view of the map. Only the visible tilesthat fall within the current view of the Map are in memory.

Smooth Pan, Zoom and DeclutteringMany options are available with SL-GMS for panning and zooming Maps.The Map library supports continuous zooming and panning. Automatic andmanual decluttering allows individual layers of the Map to be displayed orhidden. The zoom thresholds at which layers are hidden or made visiblecan be adjusted without any programming changes, simply by editing thelayer configuration file.

Dynamic Vector MapsDynamic Properties can be associated with Map vectors allowing the color,style, or thickness of any vector to change in response to real-time data.

Dynamic IconsGraphic icons are instanced and moved dynamically on top of the Mapbased on real-time position data. Conversely, users can select a (moving)


Overview of SL-GMS

icon and the icon will remain centered in the Map window while the back-ground Map moves beneath it. Also, different icons can be used to repre-sent the same object at various zoom levels of the Map

Non-Programmatic ConfigurationThe SL-GMS Mapping library supports configuration files that specify

• information about the layers and tiles that make up the Map.

• information about the layers in the Map including their stackingorder and zoom thresholds for automatic decluttering.


Overview of SL-GMS

Programming frameworks

SL-GMS can be used within native application frameworks. The applicationframework is buit using tools native to the environment. The framework cre-ates windows, or drawing areas in which SL-GMS can draw Models.

SL-GMS AX/DeveloperSL-GMS AX/Developer enables users to create dynamic graphic displaysusing SL-GMSDraw and then animate these displays with live data fromwithin any ActiveX container such as Visual Basic or MS Internet Explorer.The SL-GMS AX/Developer includes the SL-GMSDraw graphical editor, theSL-GMS ActiveX control, and example uses of the control in the VisualBasic and HTML environments.

The developer is able to create sophisticated graphical user interfaces inVisual Basic or web scripting environments without writing any C/C++code. The Models created with SL-GMSDraw are also portable to C/C++ orJava product environments.

SL-GMS C++/DeveloperSL-GMS C++/Developer provides a complete solution for a wide range ofgraphics display and user interface requirements. The SL-GMS C++/Devel-oper contains the SL-GMSDraw graphical editor, SL-GMS Runtime libraryfor C++, tools and source templates for C/C++ application development.

SL-GMS C++/MapSL-GMS C++/Map is an extension to SL-GMS C++/Developerwhich allows for the inclusion of high performance dynamicgeographical map displays and map icons within user interfaceapplications. SL-GMS C++/Map includes the SL-GMS Mappinglibrary and API , and traffic application frameworks.

SL-GMS C++/Map is useful for traffic management systems, andutilities such as gas and power distribution who need highperformance geographical maps and real-time dynamicgraphics.

The features of the SL-GMS Mapping library and API aredescribed in the section Mapping application library on page 2-6.


Overview of SL-GMS

SL-GMS C++/NetSL-GMS C++/Net is an extension to SL-GMS C++/Developerwhich provides functionality specific to the graphical userinterface needs of telecom/network management applicationdevelopers. SL-GMS C++/Net includes the Advanced Mappinglibraries providing support for node and connectivity features,and network management application frameworks.

SL-GMS C++/Net is useful for customers needing highperformance cartographic maps, physical network diagrams,logical network diagrams, and equipment displays.

SL-GMS J/DeveloperSL-GMS J/Developer allows for quick prototyping and rapid deployment ofJava applications and Java applets that require high performance dynamicgraphics. The SL-GMS J/Developer includes the SL-GMSDraw graphicaleditor, a code generator for Java, tools and source templates for Java appli-cations and Java applets.

SL-GMS J/NetSL-GMS J/Net is an extension to SL-GMS J/Developer whichprovides functionality specific to the graphical user interaceneeds of telecom/network management developers on the Javaplatform. SL-GMS J/Net includes the J/Net network libraryextension and associated API, network sysmbols library, telecomapplication frameworks and source templates.

SL-GMS J/Net features Thin Client technology, highperformance, customizable icons, industry standard icon libraryand automatic icon placement algorithms.

Integration with Motif GUI buildersTo avoid the complexities of Motif programming, a growing number of largecorporate and government developers begin application development usingMotif productivity tools such as TeleUSE, UIM/X, or Builder Xcessory.These tools enable developers to build widgets interactively with drawingtools and to link events and callbacks to their code. SL-GMS provides themeans to easily integrate dynamic graphics, designed with SL-GMS draw-ing tools, with the Motif widgets produced by the productivity tools and to


Overview of SL-GMS

extend the object-oriented appearance provided by Motif to encompass thefunctional aspects of the application.

Further information about X integration is provided in Appendix C.

Integration with Visual C++ application frameworksUnder Windows NT, SL-GMS is compatible with window control code andapplication frameworks developed with Visual C++. Developers may useVisual C++ to design the window controls for all or part of the user interace.SL-GMS provides access to and display of data within the existing frame-work of the application.

Integrating graphicsThe application provides SL-GMS a single widget or multiplewidgets including a “drawing area” in which to draw. On-lineexamples distributed with SL-GMS show how widget creationand passing of the “drawing area” are done.

Extending the object-oriented appearanceCurrently evolving sub-libraries of SL-SMS provide pre-cannedStates and SL-supplied callbacks that act as “wrappers” around

Motif widgets. These “wrappers” eliminate much of thehand-coding ordinarily required to activate the widgets, feeddata to be displayed in them, and define callback functions tocontrol the application functions. In the resulting systemprocess, GUI screen states follow the required system statechanges, according to the overall object-oriented design, ratherthan forcing the system states to be driven by changes on thescreens. Current SL-SMS sub-libraries provided are:

SL-SMS Sub-library Used for

SL-SMS-XM SL-GMS/Motif applications

SL-SMS-WNT SL-GMS/Windows NT applications


Overview of SL-GMS

With SL-GMS, the application is portable across Motif builders;in fact, Windows NT objects can be substituted for Motif widgets.

File types in SL-GMS

This section describes the file types used by SL-GMS. To distinguishbetween the file types, SL-GMS reserves the following file suffixes.

“.dat” filesData files recognized by the SL-GMS Preview utility for dynamics are ASCIIfiles which can be conventionally edited by any O/S editor. (Further infor-mation about preview “.dat” files is provided in the section Previewing theDynamic Behavior of Objects on page 3-61.) The SL-GMS Preview utility isaccessed via SL-GMSDraw’s Preview Options option of the DynamicsPull-Down Menu.

“.dxf” filesAutoCad ".dxf" (Data Exchange Format) files can be converted to SL-GMS".g" (ASCII) Model files using the SL-GMS utility dxf2g. The dxf2g utility isdescribed in the section AutoCAD dxf2g ".dxf" file converter on page D-4.

File Suffixes Reserved by SL-GMS

Suffix Description.dat data file recognized by SL-GMS Preview

utility for dynamics.dxf AutoCad ".dxf" (Data Exchange Format) files.g standard ASCII Model file.i raster (Bitmap) file (format dependent upon

Workstation type).m1 standard binary (noncontiguous) Model file.m2 compressed binary (contiguous) Model file.p1 Project files.ps standard PostScript file.rc resources file


Overview of SL-GMS

“.g” filesASCII screen-description files (“.g”) can be interpreted by SL-GML, pro-duced by the SL-GMSDraw graphical editor, and/or conventionally editedby any O/S editor and transported to other SL-GMS platforms and environ-ments. “.g” files can be created with the GML Script option of the Exportsubmenu of SL-GMSDraw’s File Pull-Down Menu (described in the sectionFile Menu of the SL-GMSDraw User’s Guide) or with the SL-GML gsavecommand. “.g” files can be created at run time with the gmsMGSave( )function. All coordinates in a ".g" file have four significant digits after thedecimal point.

".g" files can also be viewed with the View GML File option of the FilePull-Down Menu in SL-GMSDraw.

“.i” filesRaster files can be imported for display in SL-GMS and exported for use bya variety of print/display device drivers. The format of the raster file isdependent upon the SL-GMS Workstation (e.g., X) in use.

Raster files can be imported/exported with SL-GMSDraw’s Import andExport options of the File Pull-Down Menu (described in the section FileMenu of the SL-GMSDraw User’s Guide). The raster files may also bemanipulated programmatically with the gmsBitmap( ) and gmsVuRSave( )functions.

In previous versions of SL-GMS, raster files were imported/exported with afilename extension of ".i". SL-GMS now imports/exports images with thefilename extension ".xwd" on Unix X systems, and ".bmp" on Windows 32systems. Models that contain instances of Raster files with a filename

Workstation Raster File DescriptionX imports/exports raster files in the Xwd format;

also retains a hook to import the old (pre-4.0d) custom SL-XImage File Format, but in this format the colormap information was not preserved, so colors may be incorrect

NT the standard Windows type Bitmap format (the ".bmp" format) is supported


Overview of SL-GMS

extension of “.i” will still load correctly. However, SL-GMSDraw will not list“.i” files when importing images.

“.m1” filesNoncontiguous binary-executable screen-description files are produced bythe SL-GMS drawing editor or user application programs and can be readby SL-GMSRUN. “.m1” files are created with the Save or Save as... optionof SL-GMSDraw’s File Pull-Down Menu or with the SL-GML save com-mand. The “.m1” files can be created at run time with the gmsMSave( )function.

“.m2” filesContiguous binary-executable screen-description files are optimized for runtime screen-load performance. “.m2” files are created from “.m1” files withthe m1m2 Model conversion utility or at run time with the gmsM2Save( )function. Further information about “.m2” files is provided in the section Fileusage on page 11-2.

“.p1” filesProject files contain a collection of Views and Models. Before SL-SMS evolved, Projects were used when multiple Views and Mod-els were to be displayed in the same Workstation/Window. AlthoughProjects can still be used to build an application without programming, it isrecommended that SL-SMS be used to handle multiple Views and Models.Project files are created with the SL-GML project save command. Projectfiles can be created at run time with the gmsPSave( ) function.

“.ps” filesPostScript formatted screen-description files can be accessed by any Post-Script device drivers. PostScript output of Models can be created with thePrint option of SL-GMSDraw’s File Pull-Down Menu or can be created atrun time with the gmsPsViewWrite( ) function.

“.rc” files

Files used to save and restore settings.


Overview of SL-GMS

Localization

SL devotes significant resources to internationalization and localization ofits Graphical Modeling System. Native language text input, output, menus,and messages are supported across several platforms. For example, Japa-nese versions of SL-GMS are available for Hewlett-Packard, Sun, andToshiba workstations. A Korean version is available on Sun workstations.Extensions to the Latin character set are available across a wide range ofplatforms to support most European languages. Additional platforms andlocales are under development. SL Sales or SL Customer Support can becontacted for the current list of languages and platforms supported.


3

Version 6.2a- 26 M

Dynamics

Introduction

Figure 3-1: The SL-GMSDraw editor

The aim of SL-GMS screen dynamics is to establish a one-to-one corre-spondence between 1) events on the screen, and 2) events in the real-timeenvironment — that is, the real process being visualized.


Dynamics

Dynamic behavior is accomplished through actions which specify changesto be applied to the graphical representation in response to changes inapplication variables.

All SL-GMS actions are directly implemented. For example, if a moveaction is specified in response to a change in the variable named position,the graphical object is moved via a transformation matrix. Some examplesof actions are:

Examples of Dynamic Actions

Sample Application Dynamic Action

Position and movement with X and Y controlled independently

Scale and/or size of objects

Rotation of objects from any designated reference

Fill and percent-fill of Circles, Closed Splines, Rectangles, and Polygons

Amps


Dynamics

Color

Visibility

Line style, Line width

Radius (of Circle)

Text replace, including digital-readout values and strings

Examples of Dynamic Actions(continued)


ALARM blackandred

34.5


Dynamics

Text font and height

Graph axes and traces, linear, log, and calendar/clock

Bars, pies, and charts

Examples of Dynamic Actions(continued)


h hh


Dynamics

Actions

Dynamic behavior is accomplished through actions which specify changesto be applied to objects in response to changes in application variables.These are:

SL-GMS Action Types

Action Type Description

Attribute any change to a standard SL-GMS graphical attribute, such as position, size, and color, may be specified in an action; for example, the visibility of an object, including an entire screen, may be determined by the state of a Boolean variable in the application

Transformation the complex position, scaling, or rotation of objects can be easily controlled: either an exact position or end-points (range) may be specified; if end-points are specified, exact position is then calculated (interpolated) from the value(s) of the corresponding database variable; for example, the specific angle of a meter pointer is automatically calculated, given the end-points and the range of the driving variable; the position of an aircraft along its trajectory may be calculated from a nonlinear function of several variables and constants

Text a text string and format attribute(s) may be specified to indicate the field width, number of decimal places, and justification of Text objects; for example, the text string presented can represent the real-time numeric value of a specified data variable, or a text string providing labels, warnings, or special instructions

Point Change graphical objects may be modified by replacing the Points that define the object


Dynamics

Display dynamics

Display dynamics are specifications for changes to objects as a result of achange in an application variable. Any object, or individual object ele-ments, may be driven separately by as many different variables asrequired.

A dynamic description is text in a syntax recognized by SL-GMS that speci-fies a change in the appearance of an object in response to a change in anapplication variable, or an action to be taken in response to input events forthe object. A DynProp (Dynamic Property) is all of the dynamic descrip-tions attached to an object.

Icon Switch permit the automatic display of one of several objects or icons within a higher order Model object, based upon the value of a named variable or expression; for example, in a process control system a valve may be represented by one screen icon when the valve is open, another when the valve is closed, and a third when it is out of service

Graph changes to Graphs such as scaling limits, variable to drive a trace, and trace type, are included in Graph actions

User-defined any changes may be specified in a user-defined function which is invoked via the call action in a DynProp

SL-GMS Action Types(continued)

Action Type Description


Dynamics

Figure 3-2: DynProp containing two dynamic descriptions

In Figure 3-3:, the dynamic description is unconditional. It specifies,"Whenever the variable stat changes, the object is filled with the colorindexed by the value of stat."

Figure 3-3: DynProp with unconditional display dynamics

fcolor is an action keyword. A complete table of all valid dynamic actionkeywords is provided in the chapter Dynamics Reference of the SL-GMSQuick Reference.

stat is a Variable Reference. A Variable Reference can be identical to avariable in a programming language like Ada, FORTRAN, Pascal, or C. AVariable Reference can also be an expression — a more complex entityinvolving formulas, function calls, data structures, files, and other data.Expressions can include any number of references to variables, or calls toapplication-specific functions and standard arithmetic and logical opera-tors. Expressions are parsed for conventional notations.

Actions in unconditional dynamic descriptions are executed whenever anyVariable Reference in an object’s DynProp changes. Compare this to theconditional dynamic description in Figure 3-4:. It specifies, "When the vari-able tankvol1 is within the indicated range, the object becomes per-

* fcolor stat

tankvol1

= (tankmin1+1) : (tankmax1-1)

fpercent 0:100

fcolor 2

description

descriptionDynProp

dynamic

dynamic

* fcolor stat


Dynamics

cent-filled according to where in the range the variable falls, and the fillcolor is set to the color indexed by 2."

Figure 3-4: Dynamic description with conditional display dynamics

fpercent and fcolor are action keywords that change the fill-percent and fillcolor attributes of the object. tankvol1, tankmin1, and tankmax1 are Vari-able References. tankmin1+1 and tankmax1-1 are expressions.

As seen from the sample DynProps above, actions may be either:

• unconditional — action that occurs when any Variable Referencein an object’s DynProp changes, or

• conditional — action that occurs only when a specific variable isequal to a constant or within a certain range

Actions may also be:

• implicit — SL-GMS restores an object to its original state (or toan error state) when a variable falls outside any ranges specifiedby the user

DynProps are included as attributes of objects, along with other graphicalattributes, all within the SL-GMS drawing editor. At runtime, wheneverspecified data variables change, SL-GMS automatically makes the correctsequence of library function calls to make specified changes on the screen.

DynProps can be attached to SL-GMS objects using API calls in programcode, or interactively with the SL-GMSDraw editor. This flexibility allowsusers to create an object to represent any underlying data quickly and testthe dynamics immediately.

tankvol1= (tankmin1+1) : (tankmax1-1)

fpercent 0:100fcolor 2


Dynamics

Expressions

Expressions may be used wherever variables are allowed in dynamicdescriptions. Expressions are always surrounded by a pair of parentheses.SL-GMS expression operators are similar to those defined in the C pro-gramming language.

The complete list of expression operators is provided in the section Expres-sion operators of the SL-GMS Quick Reference.

Variables and constants can be combined in expressions. Constants canbe either integer or real values, however; constants must correspond to thetype of variables used or unpredictable results may occur. Constantswhich include decimal points are real values.


Dynamics

The following elements are valid in expressions:

Some examples of expressions follow. Two variables, named temp andpres, are used in these examples. These variables have no special mean-ing attached to them, and can be used in an application.

(temp * 100) Multiply temp by 100

(((temp - 32) * 5 ) / 9) Convert temp to Centigrade

(temp * pres) Multiply temp by pres

(temp > 99) TRUE if temp greater than 99

((temp * pres) < 200) TRUE if product is less than 200

((temp > 99) || (pres > 50)) TRUE if either comparison true

Elements Valid in Expressions

Expression Ele-ment Description

A Variable Reference

the name of a variable in the user’s application may be used

Integer, Real, and String Constants

entries such as 2, 99, 234.45, "hello," and "STOP" are valid

Unary and Binary Expressions

the ability to add(+), subtract(-), multiply(*), divide (/), or exponentiate (**) variables, constants, or the resultant variables of other expressions

Relational Expressions1

1. "==" is also valid for string comparision

these include C operators that result in a true or false value i.e., >, <, >=, <=, ==, &&, || and !=

Function Call Expressions

these may include any C-library defined trigonometric, exponential, and/or mathematical function: in addition, user-written, application-specific functions may be provided in the application program; such functions need only be entered into SL-GMS by name as long as they have been compiled and linked with the application program


Dynamics

All variables used in an expression are attached to the same dynamicexpression, so a change in any of the variables in an expression signalsthat the expression must be re-evaluated.

Expressions can be used as the Variable Reference, the logical expres-sion, and/or the action argument in a dynamic description.

Below is an example of using an expression as a Variable Reference andas a logical expression:

*stext tankvlv1 "%8.2f"

((tankvlv1 >= tankmax1) || (tankvlv1 <= tankmin1))= 1

fcolor 4tankvlv1

= (tankmin1+1):(tankmax1-1)fpercent 0:100fcolor 2

The description above always changes the Text associated with the object.The fill color of the object changes to 4 when the value of the tankvlv1 vari-able goes above or below the range tankmin1 to tankmax1. When thevariable is within the specified range, the object becomes percent-filledaccording to where in the range the variable falls, and the fill color is set to2.

Input dynamics

Input dynamics are specifications for changes to objects as a result of aninput Event. As mentioned earlier, GISMOs are objects that have inputdynamics specified in their DynProps. The DynProp attached to a GISMOgenerally consists of two logical parts:

1. Input dynamics following a pound-sign ("#"), which includeaction(s) to manipulate SL-GMS internal or application programvariable(s) and are performed when the GISMO is selected.

2. Display dynamics which include highlighting action(s) to be per-formed when the GISMO is selected. Typically these highlight-


Dynamics

ing actions are driven by the change in the SL-GMS internal orapplication program variable(s).

Input dynamics are required for GISMOs. Display dynamics are optionalbut typically are used.

GISMO DynProps are generally placed on the GISMO Model,1 although theDynProp may also be placed on any Model part such as a Group or an indi-vidual object.

Often, the actions used in GISMO DynProps are call actions followed by afunction call from the SL-GMS GISMO Action Function Library:

call <SL-GMS GISMO Action Function>

Alternatively, a user-defined function may be used. The SL-GMS GISMOAction Functions provide optimized, special-purpose actions for behaviorsthat are often used.

The actions used in the display dynamics portion of GISMO DynProps aregenerally functions which describe highlighting behaviors (usually followinga gms_hilite_*( ) naming convention).

Chapter 5 — GISMOs and Appendix A provide a complete description ofGISMOs and input dynamics.

Integration with native GUI control objects

Convenient user interaction with the screen in a windowing system is fun-damental to a successful graphical user interface. Operators must be ableto intuitively control real-world, real-time processes through mouse andkeyboard interaction. This interaction can be conducted using controlobjects. Many interface control objects are used, such as buttons, sliders,pull-down menus, scrolling lists, and text entry boxes.

The control objects designed for use in a particular Graphic User Interfaceare said to be “native” to that GUI. For example, the control objects nativeto the X-windows Motif systems are called widgets. Graphical objects builtin SL-GMSDraw are completely compatible with widgets and other nativeGUI control objects. Motif widgets, for example, can be added to an

1. Placing a DynProp on a Model Object is described in the section Adding dynamics to a Model object on page 3-44.


Dynamics

SL-GMS graphical Model or an SL-GMS Model can be displayed in a Motifwidget.

Minimum programmingEncapsulating control object behavior within SL-SMS States frees thedeveloper from the details of programming in the underlying Window Sys-tem. In Windows NT environments native control objects are based uponthe Microsoft Foundation Class Library. In Unix environments native con-trol objects are X-based Motif widgets.

Figure 3-5: SL-GMS encapsulates control object behavior

With encapsulated behavior, there is no need to know details of WindowsNT or Motif programming: the developer can concentrate on the interfacesolution and still receive the benefits. See Figure 3-5:.

Control object interfaceSL-GMS supplies powerful functionality that solves the problem of includ-ing native control objects in application screens. Through SL-GMS encap-sulation, native control objects can:

• Display or modify application variables. No programming isrequired to achieve this.

• Send a State message with parameters. Communication with theapplication is standardized and the application is automaticallymodularized. This separates the interface from the application.

native control message

applicationvariable

to applicationobject

applicationvariable


Dynamics

Programming effort necessary to create a complete interface for an appli-cation is greatly reduced by SL-GMS’ encapsulation of native controlobjects. Data is presented and modified via control objects through a sim-ple, direct-memory accessed table — an approach that is consistent withall other objects in SL-GMS.

The Native Control Object LibraryA library of the most common 32-bit Windows and Motif user interface con-trols is supplied in with SL-GMS. The controls are encapsulated for usewith SL-GMS and organized in palettes for convenient use in SL-GMS-Draw. The Control Objects provided in the library include:

• Push Button, Mode Button, Radio Button, Check Button, and3-state Check Button

• Labels, Text Display and Text Edit Boxes (single and multi-line)

• Text List Boxes

• Scale Controls

• Various Container Controls

• Option menus


Dynamics

Figure 3-6: Control Object Palette (Windows)


Dynamics

Figure 3-7: Control Object Palette (Motif)

SubModels and dynamic instancing

Any graphical Models created using a SL-GMS drawing editor can be usedrepeatedly (nested) in the construction of other Models, with full inherit-ance of the object’s dynamic properties. SL-GMS supports the nesting ofgraphical Models without writing any application code. This benefits devel-opers who wish to standardize the appearance of various screen elements.Examples of such nesting include common icons in a menu system, sym-bols representing information overlaid on maps, buttons, meters, valves,gauges, charts, and graphs on process control screens. SL-GMS develop-ers often build libraries of Models that they reuse as SubModels in variousapplications.


Dynamics

For example, the "meter" Model, shown in Figure 3-8:, can be re-used asmany times as required as a SubModel. Multiple Instances are shown inFigure 3-9: on page 3-18.

Figure 3-8: Building the "meter" Model


Dynamics

Figure 3-9: Instancing the "meter" Model as an external SubModel

Instances of SubModels become part of the Model as references only.When SubModels are re-edited or changed in any way, all Models in whichthey are incorporated as External are automatically updated to reflect thechanges.

In SL-GMSDraw, Models can be nested within other Models to an arbitrarynumber of levels. Each Model Instance retains the dynamic properties ofthe original Model. Models may be instanced in the run-time applicationwith the gmsModInst( ) function. Users differentiate Instance behavior byrenaming variables associated with the original Model.

The ability to instance Models and then attach different driving variables iscalled parametric instancing.


Dynamics

Parametric instancing is achieved in SL-GMSDraw by interactively creatingan instance and assigning new values or variables to each instance param-eter. Each instance parameter can be assigned to a variable, a constant,an expression, or the value returned by a user function. For applicationsthat need to dynamically instance objects, parametric instancing can beaccomplished programmatically through API functions that are used to cre-ate an instance and assign values or variables to its parameters.

For example, a voltmeter Instance of a meter Model might rename the vari-able m to volts, (where m is the variable controlling the original meter Mod-el’s dynamics), whereas an ohmmeter Instance might rename the mvariable as ohms. The application program ultimately driving the displayassociates different Datasources with the two Instances.

The aircraft icons, shown in Figure 3-10: and Figure 3-11: on page 3-20, areeach a group of three instances of SubModels: speed bar, missile envelopeand detection ring. The “speed bar” indicates the speed and direction oftravel, the “detection ring” indicates the range of aircraft detection, and the“missile envelope” indicates a firing range. Instances of the aircraft Sub-Model are created at runtime by the application.

Figure 3-10: An "aircraft" Model

missile envelope

speed bar

detection ring


Dynamics

Figure 3-11: Instances of the "aircraft" SubModel in a cockpit screen

SL-GMS developers build libraries of Models that they re-use as SubMod-els in many different applications.

RANGE STATUS NEXT

60 KM


Dynamics

Charts and Graphs as dynamic SubModels

Parametric instancing is particularly valuable for Graphs, where the samebasic Graph type may have several controlling parameters, such as valuelimits, x trace data, y trace data, background color, and so on. The Sub-Model, or template, may be instanced, as shown in Figure 3-12:, with differ-ent values set for each of its driving variables.

To support dynamically changing graphs and charts, an extensive library ofready-to-use standard Graph templates are defined in SL-GMS. TheSL-GMS Graph Library2 includes trend graphs, pie charts, and logarithmicplots.

Creating a working Graph involves simply instancing a Graph Model andrenaming variables for tick mark spacing, axis limits, and other characteris-tics.

Figure 3-12: Two Instances of the Graph template "lineplot"

2. A complete description of the templates provided in the SL-GMS Graph Library is provided in the chapter The SL-GMS Graph Library of the SL-GMS Quick Reference.


Dynamics

In addition, customized graphs and charts are easily created through theuse of two special objects (see Figure 3-13:):

• GraphAxis — an axis of a graph, including labels and scale ticks

• GraphTrace — a combination of Lines and Markers that isdynamically updated to plot individual Points or arrays of Points

Figure 3-13: GraphAxis and GraphTrace objects

These objects, along with the existing Graphical Primitive capabilities, pro-vide all components necessary to construct complex, customized, dynamiccharts and graphs consisting of any number or variety of axes and traces.Everything about the graph axes and traces functions in the same way asother Graphical Primitives, including a set of special actions to support thedynamic modification of any graph attributes (such as value limits and plotdata).

GraphAxis

GraphAxisReference Point major minor tick

GraphTrace(Polyline) (Markers)

GraphTrace GraphTrace(Polyline/Markers)

tick tick label


Dynamics

Attaching Dynamic Descriptions to Objects

Objects can be given dynamic descriptions that cause them to rotate,move, change scale, change Text strings, change Line style and color, andbecome visible or invisible. The proper syntax for dynamic descriptions isdescribed in the section General syntax for display dynamic descriptions onpage 3-27.

Editing DynamicsDynamic descriptions are normally attached to objects by using the ObjectDynamic Properties option of the Dynamics Pull-Down Menu in SL-GMS-Draw. The Object Dynamic Properties option displays the Object DynamicProperties window.

The Object Dynamic Properties window instances a simple text editor usedto create or modify the object’s dynamic description. No changes are actu-ally made to the object’s dynamics until the Apply button is clicked.

Only one object at a time may have a DynProp edited in the Object Dynam-ic Properties window. If multiple objects are on the Select List, use theLoop Control buttons in the Main Menu bar (refer to the SL-GMS®DrawUser’s Guide) to select the next object on the Select List.

Click inside the Object Dynamic Properties window to begin editing. Anexample of a DynProp typed into the Object Dynamic Properties window isshown in Figure 3-14:.


Dynamics

Figure 3-14: A DynProp in the "Object Dynamic Properties" window

Press the <RETURN> key at the end of a line to move the cursor to thenext line to be typed. To insert a line, click at the end of the previous lineand press the <RETURN> key. To modify a line, click the line, backspaceover the characters you wish to change, and enter the correct information.You can place the cursor anywhere on the line and edit from that point. Todelete a line, either click on the line until the entire line is highlighted andpress the <RETURN> key or click on the line and use the <BACKSPACE>key to delete all the characters in the line.

When you have entered the format of the dynamic descriptions correctly,the DynProp automatically indents the line when you click the Apply but-ton. This indentation, illustrated in Figure 3-15:, clarifies the grouping of thedynamic descriptions and the actions and variable tests within a particulardynamic description. The indentation has no effect on the execution of thedynamic description.

*fcolor stattankvol1= (tankmin + 1):(tankmax - 1)fpercent 0:100fcolor 2


Dynamics

Figure 3-15: A DynProp indented after pressing the "Apply" button

Hold, Release, and Clear The Hold button holds the contents of the entire Object DynamicProperties window in a hold buffer. The contents in the holdbuffer are held until quitting SL-GMSDraw or until changed byclicking the Hold button again. Leaving the Object DynamicProperties window does not affect the hold buffer, nor doeschanging between Models affect it.

The Release button replaces the current contents of the ObjectDynamic Properties window with the contents of the hold buffer.

The Clear button clears the contents of the hold buffer.

The Reset button returns the contents of the Object DynamicProperties window to its original content.

Error checkingFigure 3-16: illustrates a DynProp that contains an error. Line 3reads "tankvol 1" instead of "tankvol1." SL-GMSDraw detects

*fcolor stat

tankvol1= (tankmin + 1):(tankmax - 1)fpercent 0:100fcolor 2


Dynamics

"tankvol 1" as an error because it is not a valid dynamic action.When the Apply button is clicked, a dialog box, as shown inFigure 3-17: on page 3-26, will display indicating the line inwhich the error occurs. Click the OK button to acknowledge theerror. Correct all errors and click the Apply button again. TheDynProp will then appear indented, as illustrated in Figure 3-15:on page 3-25.

Figure 3-16: A DynProp typed incorrectly with an error on line 3

Figure 3-17: A dialog box displaying the location of an error

*fcolor stat

tankvol 1= (tankmin + 1):(tankmax - 1)fpercent 0:100fcolor 2


Dynamics

General syntax for display dynamic descriptions

Display dynamics translate changes in application variables to changes ingraphical objects. A display dynamic description may be one of two differ-ent types — unconditional or conditional:

Figure 3-18: General syntax for display dynamic descriptions

Actions in unconditional dynamic descriptions are executed whenever anyVariable Reference3 in an object’s DynProp changes. Testing of a condi-tional dynamic expressions occurs whenever the tested variable, or anyvariable in the dynamic expression argument changes. However, actionsin conditional dynamic descriptions are only executed whenever the testingof any logical expression results in TRUE after reading the value of a Vari-

3. <argument> can contain Variable References.

SL-GMS Editor Syntax SL-GML Syntax

Unconditional (direct)

* (*\

action <argument> (action <argument>)\

. . . (...))

Conditional

Variable Reference (Variable Reference\

= value ( = value\


. . . (...)))

OR OR


= * ( = *\


. . . (...)))

Conditional with value range


= value1:value2 ( = value1:value2\


. . . (...)))


Dynamics

able Reference. When an asterisk (*) is used in a conditional dynamicdescription, the object is updated whenever the variable or any variable inthe arguments in the action(s) changes.

NOTE: Unconditional dynamic descriptions must be specified before anyconditional dynamic descriptions in an object’s DynProp. Unlikeother types of dynamic descriptions, unconditional dynamicdescriptions are executed once upon initialization of dynamicswith gmsDynInit( ). This initial execution allows for unconditionaldynamic descriptions consisting solely of constants to beexecuted once. For example, an unconditional dynamicdescription can be used to cause a text label to appear on anobject upon the first display of a Model. DynProps which containsolely unconditional dynamic descriptions are the most efficientDynProps. More information about efficiency in dynamics isprovided in the section Optimized dynamics on page 11-9.

A Variable Reference is:

1. a name which can include the letters "A-Z", "a-z", the digits"0-9", or the characters "$", "_", and "#". Other printable ASCIIcharacters, except the parenthesis, "(" or ")", are valid if preced-ed by a backslash ("\"). A variable name must begin with the let-ters "A-Z", "a-z", or the character "$";

2. an expression described in the section Expressions on page 3-9;or

3. a function call described in the section Using function calls onpage 3-34.

The value used in a conditional dynamic description may also be a range ofvalues, specified by using two values, separated by a colon rather than asingle value. In the case of a value range, the conditional action is per-formed when the value of the variable falls within the range specified by thetwo values.

An action may be any of the actions listed in the section Dynamic actions ofthe SL-GMS Quick Reference, and include changes to objects’ attributes,orientation, and Text. A conditional or an unconditional dynamic descrip-tion may have a list of actions. All actions are performed in the order in


Dynamics

which they are placed in the dynamic description when the condition (ifany) is matched.

Evaluation of sample DynProps

The collection of dynamic descriptions for an object is called an object’sDynProp (short for Dynamic Property). In SL-GML, all dynamic descrip-tions must be part of a single string following the dynprop keyword. InSL-GMSDraw, the DynProp is broken into many lines with variables (andvalues or ranges) and actions each on its own line of the Object DynamicProperties window. The limit on the number of characters for a DynPropstring is 8192. More discussion is provided in the section AttachingDynamic Descriptions to Objects on page 3-23.

EXAMPLE 1

Sample DynProp:trigger

= 1plotdata x y

The plotdata action is executed only when trigger = 1. Thevalue of trigger is tested whenever trigger, x, or y changes.

NOTE: It is the application program’s responsibility to constrain the datavalues to those which work correctly for a DynProp. In the aboveexample, trigger should be set to 1 by the application programonly when both x and y are available.

EXAMPLE 2

Sample DynProp:4

y= *

plotdata x yThe plotdata action is executed whenever x or y changes. TheSL Graph templates distributed in the GRAPHS subdirectory are

4. There must be a space after the equal sign before the asterisk (" = * ").


Dynamics

set up with this type of dynamic description so that a triggervariable is not necessary.

NOTE: It is the application program’s responsibility to callgmsVarChanged( ) on both x and y at the same time. It isimportant to recognize that, in a conditional dynamic descriptionutilizing the asterisk as shown above, the actions are performednot only when the variable has changed, but also if any of thevariables (arguments) referenced in the actions have changed.

EXAMPLE 3

Sample DynProp: (one conditional dynamic description with interpolation of rotation angle)

volts= 0:120

rotate 0:-90

As the value of the variable volts changes from 0 to 120, itsrotation from 0 to -90 degrees is interpolated automatically bySL-GMS. The rotate action is conditional upon the value ofvolts falling within the defined range.

EXAMPLE 4

Sample DynProp: (one unconditional dynamic description with an expression)

*vis (volts > 120)

When volts is greater than 120, the expression, (volts > 120), isequal to 1. When the expression is false (volts is less than orequal to 120), its value is 0. The vis action makes an objectvisible when its argument is 1, and invisible when its argumentbecomes 0. Because this action begins with an asterisk, it is anunconditional action.


Dynamics

EXAMPLE 5

Sample DynProp (two conditional dynamic descriptions):var1

= 4ewidth 3

var2= *

movex var2movey var3

The ewidth action is executed only when var1 is equal to 4. Themovex and movey actions are executed only when var2 or var3changes.

The above DynProp is not equivalent to:

Sample DynProp (one unconditional and one conditional dynamic description):

*movex var2movey var3

var1= 4

ewidth 3The movex and movey actions are executed whenever var2 orvar3 changes or whenever var1 changes. The ewidth action isexecuted only when var1 is equal to 4.

NOTE: It is important to recognize, as shown in the second DynPropabove, that unconditional dynamic descriptions are executedwhenever any Variable Reference in a DynProp changes.


Dynamics

EXAMPLE 6

Sample DynProp (one unconditional and one conditional dynamic description):

*redraw

var1= 4

ecolor 2In the above DynProp, the redraw action is executed whenevervar1 changes. The ecolor action is executed only when var1 isequal to 4.

Sample DynProp (one conditional dynamic description):var1

= *redraw

In the above DynProp, the redraw action is executed whenevervar1 changes.

NOTE: The redraw action is intended to be used as part of a conditionaldynamic description. If redraw is used as part of anunconditional dynamic description, it is only executed if someother conditional dynamic description is executed.


Dynamics

DynProp execution

Models often contain dynamic objects that have a DynProp attached.Upon system update, the order of the objects in the SL-GMS GraphicalModeling Hierarchy determines the order of DynProp execution. Dyn-Props are executed beginning with the DynProp for the topmost object inthe SL-GMS Graphical Modeling Hierarchy, all the way down to the Dyn-Prop for the lowest-level object in the hierarchy using a depth-first pathdown the tree processing all of the nodes along the first branch of the tree,continuing with all of the nodes down the second branch of the tree, and soon. DynProps for all objects on the same level in the hierarchy are execut-ed in the order in which the objects were added to the system.

Figure 3-19: DynProps are executed in depth-first object hierarchy order

For example, in the figure above, the Model M1 has a DynProp attached tothe Model itself, so that DynProp is executed first. (Attaching dynamics toa Model is explained in the section Adding dynamics to a Model object onpage 3-44.) Because the Group G was the first object created in the Mod-el, the DynProp for that object is the next one executed. Then the Dyn-Props for the three parts that comprise the Group (P1, P2, and P3) areexecuted in the order that the parts were added to the Group. The Dyn-Prop for the Model Instance I is executed followed by the DynProp for the

Model

InstanceGroup Circle

Model

M1

G I C

M2

SectorP1

SectorP2

RectangleP1

LineP2

TextP3

— DynProp

— DynProp — DynProp

— DynProp

— DynPropDynProp —

DynProp —

DynProp DynProp DynProp

�

�

� � �

� �

�

�


Dynamics

Model M2, followed by the DynProps for the parts P1 and P2. Finally, theDynProp for the Circle object C is executed.

Using function calls

A set of function calls can be used as a Variable Reference, the logicalexpression, and/or the action argument in a dynamic description, includingfunction calls taken from the standard C Language Math Library. Forexample, a dynamic description that moves an object with respect to thelogarithm of a variable appears as follows:

time= *

movex timepres

= *movey log(pres)

This dynamic description moves the associated object along the x axis withchanges in time, and logarithmically along the y axis with changes in thevariable pres.

NOTE: To ensure proper DynProp evaluation, the function name mustbe followed immediately (i.e., with no spaces) by an openparenthesis, the argument list, and a closing parenthesis.

A table of function call sets (with return types) currently available beginswith the section Standard C-Library functions recognized in DynProps of theSL-GMS Quick Reference.


Dynamics

User-defined functions

A user-defined function is used with the call action, within an expression,or anyplace where a variable or constant may be used.

As an example, in the dynamic description below, the user-defined functionconvertToAngle( ) is called with the argument pres, and the returned valueis used as the argument to the rotate action.

*rotate convertToAngle(pres)

To use the user-defined function capability, the developer should performthe following:

• Create a "userfctns.c" module that includes: the user-definedfunctions with the proper parameters and return values; and thefunction userfctns_initialize( );

• In the userfctns_initialize( ) function, include a call to thefunction gmsAddUserFctn( ) for each of the user-definedfunctions;

• The "userfctns.c" module is compiled to produce "userfctns.o"and then added to the Makefile for the developer’s applicationand the application is re-linked.

• "userfctns.o" is added to the Makefile for the SL-GMS editor, asdescribed in the section Adding a function to a SL-GMS editor onpage 3-42, and the editor is re-linked.

The steps outlined above are described in the following sections.


Dynamics

Creating a user-defined functionThe DynProp shown in Figure 3-20: is attached to a Filled Rectangle objectthat displays the value of a variable. This DynProp will be used as anexample of the procedure used to create a user-defined function and incor-porate it into a developers application and into a SL-GMS editor.

*stext temperature "%7.2f"fcolor 0tcolor 7ecolor 0

(temperature > hialarm)= 1fcolor 3tcolor 7ecolor 0

(temperature > criticalT)= 1fcolor 1tcolor 0ecolor 7

Figure 3-20: One unconditional and two conditional dynamic descriptions

The value of temperature will be displayed whenever temperature, hialarmor criticalT changes. However, the fill color (fcolor), edge color (ecolor)and Text color (tcolor) of the Filled Text Rectangle will vary depending onthe values of the variables.

If temperature is greater than hialarm, then the fill color is color index 3,the edge color is color index 0 and the Text color is color index 7. If tem-perature is greater than criticalT, the fill color is 1, edge color is 7 and theText color is 0. If temperature is less than hialarm and criticalT then theedge color and fill color are 0 and the Text color is 7.


Dynamics

The DynProp shown in Figure 3-20: on page 3-36 can be optimized5 byproviding a user-defined function, usr_set_color( ), to perform theconditional comparisons.

*stext temperature "%5.2f"call usr_set_color(__self, temperature,

hialarm, criticalT)

Figure 3-21: A user-defined function in a dynamic description

This is useful for several reasons:

• maximizes performance;

• less to type if conditional descriptions are to be used in otherDynProps.

The usr_set_color( ) function is passed four arguments. The first argu-ment is _ _self. _ _self is an internal SL-GMS variable set equal to the idof the object that has the associated DynProp attached to it. _ _self has tobe passed (as an id data type) if an attribute of the object is to be changedor if the object is to have a transformation applied to it, such as move,rotate, etc., based on the values of the other variables being passed to thefunction. The other three variables are temperature, hialarm and criticalT.

5. Chapter 11 provides information concerning optimization and performance.


Dynamics

The usr_set_color( ) function looks like:

intusr_set_color(object, variable, hi_alarm,

critical_alarm)id object; /* Text Rectangle object

displaying value ofvariable */

double variable;/* value of variablebeing displayed */

double hi_alarm;/* hi alarm value */double critical_alarm;/* critical alarm value*/

{/* check if value of variable is

greater than the value ofcritical alarm value */

if (variable > critical_alarm) {gmsTColor (object, 0);gmsFColor (object, 1);gmsEColor (object, 7);

}/* check if value of variable isgreater than the value of hi alarm */

else if (variable > hi_alarm) {gmsTColor (object, 7);gmsFColor (object, 3);gmsEColor (object, 0);

}/* value of variable is less than

the value of critical alarm andhi alarm */

else {gmsTColor (object, 7);gmsFColor (object, 0);gmsEColor (object, 0);


Dynamics

}return 1;

}In the DynProp shown in Figure 3-21: on page 3-37, the usr_set_color( )function is invoked from an unconditional action which increasesperformance. Less information is read from the ".m1" file and the execu-tion is done in a compiled function, rather than interpreted at run time.

In addition, if the conditional dynamic descriptions are to be used in otherDynProps, only the call to the usr_set_color( ) function has to be typedinstead of multiple lines to do the comparisons and set the differentattributes.

Adding a function to an applicationTo utilize the usr_set_color( ) function a "userfctns.c" module is created bythe developer which contains the definition of all of the user-definedfunctions. The "userfctns.c" module also includes the userfctns_initialize() function. Inside the userfctns_initialize( ) function, all of the calls togmsAddUserFctn( ) are placed.

User-defined functions are defined by the application program withgmsAddUserFctn( ) to identify the function, its name, return type, argumentcount, and argument type.6 The gmsAddUserFctn( ) function is describedin the SL-GMS Function Reference. There is no limit to the number ofuser-defined functions for an application.

The "userfctns.c" moduleThis section shows the code for the "userfctns.c" module that contains only one user-defined function: the usr_set_color( )function. Additional user-defined functions would be added before thedefinition of the userfctns_initialize( ) function. Each user-defined func-tion would have a call to gmsAddUserFctn( ) in the userfctns_initialize( )function.

6. For portability, it is recommended that no more than six double arguments be used in a user-defined function. On some RISC versions of SL-GMS, double arguments may be used in the first six arguments only.


Dynamics

#include "gmsc.h"

intusr_set_color(object, variable, hi_alarm,

critical_alarm)

id object; /* Text Rectangle object displayingvalue of variable */

double variable; /* value of variable beingdisplayed */

double hi_alarm; /* hi alarm value */double critical_alarm;/* critical alarm value */

{/* check if value of variable isgreater than value of critical alarm*/

if (variable > critical_alarm) {gmsTColor (object, 0);gmsFColor (object, 1);gmsEColor (object, 7);

}/* check if value of variable isgreater than the value of hi alarm */

else if (variable > hi_alarm) {gmsTColor (object, 7);gmsFColor (object, 3);gmsEColor (object, 0);

}/* value of variable is less than thevalue of critical alarm and hi alarm*/

else {gmsTColor (object, 7);gmsFColor (object, 0);gmsEColor (object, 0);

}


Dynamics

return 1;}

(code continued on next page)intuserfctns_initialize( )

{static int args1p3d[] = {G_POINTER, G_DOUBLE,

G_DOUBLE, G_DOUBLE};

/* add function to set color of text andedge and fill color */

gmsAddUserFctn ("usr_set_color", usr_set_color,G_INTEGER, 4, args1p3d);

return 1;}

The "userfctns.c" module is compiled to produce "userfctns.o"7 and thenadded to the Makefile for the user’s own application.

This will allow the user’s application to execute the user-defined function atrun time. The user-defined function can be added to dynamic descrip-tions of objects using a SL-GMS editor. However, if the Model containingthe user-defined function is exercised using the Preview capability in theeditor, an error message will appear as follows:

ERROR: Cannot locate function: usr_set_color

At this point, the user-defined function has been linked into the developer’sapplication program but it has not been linked into the SL-GMS editor

7. "userfctns.obj" in VAX, and NT Systems.


Dynamics

Adding a function to a SL-GMS editorLinking the user-defined functions into the SL-GMS editor allows theuser-defined functions to be executed whenever the Model is tested usingthe Preview capability in the editor.

Relink the SL-GMSDraw editor in the work/gmsdraw subdirectory on UNIXsystems, and in the work\gmsdraw_mfc subdirectory on NT systems.

UNIX Systems:make

NT Systems:nmake


Dynamics

Ranges in dynamics

In dynamic descriptions, each action may take a range rather than a singlevalue. A range is a pair of values separated by a colon. The type of thetwo range parameters can be mixed because these values are handledinternally as real numbers.

Examples of Action Ranges1:4-12.5:14.00.:100.

Ranges can be used in actions after the equal sign in a conditional descrip-tion. For example, the following dynamic description is conditional uponthe variable pres falling within the range 0 to 200:

pres= 0:200

fpercent 0:100

The action fpercent also contains a range. In this example, the rangeused in the action is not identical to the range used after the variable.When the two ranges used are not identical, the action range is interpolat-ed automatically by SL-GMS according to the value of the variable withinthe total range allowed by the variable’s range. When pres equals 0, thefpercent is also 0, but when pres equals 200, the fpercent is 100. At themiddle of the range, the fpercent is 50.

In the following example, the object is scaled from 1 to 5 times in both the xand y directions, based upon the value of pres. If pres equals 100, thescaling is 5, and if pres equals 50, the scaling is 3 (halfway between thetwo values).

pres= 0:100

scale 1:5


Dynamics

The second value of a range can be less than the first. In this case, themapping of values works the same way, that is, the first value after thevariable maps to the first value in the action range:

pres= 0:200

fcolor 4:1Values of the variable pres from 0 to 49 map to the color 4, from 50 to 99map to 3, from 100 to 149 map to 2, and from 150 to 200 map to 1.

Adding dynamics to a Model object

In addition to adding dynamics to an object in a Model, it is also possible toadd dynamics to a Model object itself.

In an SL-GML ".g" file, the DynProp for a Model is placed directly after thename of the Model, not, as might be expected, after the endm commandthat closes the Model. This is shown in the following example:

colorcells: model. dynprop \

(# \(call gms_color_select(callback,

&colorvar)))...

endm

Dynamics can also be added to the Model using SL-GMSDraw, by select-ing the Dynamics option in the Model Pull-Down Menu. The Model Dynam-ic Properties window is displayed, as shown in Figure 3-22: on page 3-45.


Dynamics

Figure 3-22: "Model Dynamic Properties" window

The dynamic scripting language (described in the section General syntaxfor display dynamic descriptions on page 3-27) is used to add dynamics tothe Model. Type the dynamic script into the Model Dynamic Properties win-dow and click the Apply button.

Erasing objects and holes

Objects are erased by either clearing the entire View where the objectsappear or by redrawing the objects in the background color. Except indouble-buffered applications, erasure by redrawing is the standard way oferasing objects. Erasure by redrawing is unnoticeable except when eras-ing one object leaves a "hole" in another object.

Holes caused by erasures occur as a result of transformations and chang-es in visibility. If two objects overlap, a hole is created in the first objectwhen the second object is drawn. This erasure is the default behavior.As the DynProps in the Model are being executed (The section DynPropexecution on page 3-33 provides further information), the first object ismarked for erasure and redrawn before the DynProp on the second object


Dynamics

is executed. This can be modified by grouping the two objects and usingbatch erasure. With batch erasure, as the DynProp for the Group is beingexecuted, all objects which are marked for erasure are erased first andthen they are redrawn (i.e. there are two passes through the nodes of theDynProp for the Group; one for erasure and one for redraw).

Batch erasure is accomplished by using the batcherase action. Theobjects which are affected by the batch erasure must be in a Group or aseparate Model (placing dynamics on a Model object is explained in thesection Adding dynamics to a Model object on page 3-44).

The batcherase action can be used in conjunction with the repair action.The repair action redraws all objects in a Group whenever any object in theGroup is redrawn.

EXAMPLEFigure 3-23: illustrates a diamond object with attached dynamics that movethe diamond over a static line.

Figure 3-23: 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 theline is erased. A "hole" marking each previous position of the diamondappears in the static line.


Dynamics

Figure 3-24: Diamond moving and erasing portions of the line

In order to move the diamond without erasing portions of the line, dynamicsmust be attached that will erase both the line and diamond objects andthen redraw them. This is the purpose of batcherase.

In order to move the diamond without erasing portions of the line, dynamicsmust be attached that will erase both the line and diamond objects eachtime, 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 theline and diamond Group are as follows:

group. repairflag 1. batcherase 1

With the repair flag set to G_ON for the Group, whenever the diamond isredrawn the line is automatically redrawn. With the batcherase flag set toG_ON for the Group, both the line and the diamond are erased first andthen redrawn as illustrated in Figure 3-25:. The diamond moves over theline without erasing it.

Figure 3-25: Diamond moving over the line


Dynamics

For displays that have many objects moving across each other, such as aradar screen, it is not practical to use batcherase. It is more efficient tomake use of noerase in conjunction with double-buffering or clearing ofViews. This scheme avoids the overhead of marked erasure and simplyredraws everything. The noerase action causes the update pass to omiterasure of any of the object’s parts before redrawing the object. Thenoerase action is usually not required; it is a performance optimization.

Double buffering

The unwanted flickering which occurs as objects are erased and redrawncan detract from the usability of a dynamic screen. Double buffering capa-bility is provided to minimize this flickering and achieve smooth animation.

Software double bufferingSoftware double buffering is provided on X and Windows platforms anduses a pixmap (a rectangular array of pixels) to implement an off-screenbuffer. This pixmap is attached to a Graphical Primitive object and is usedas an intermediary display location or display assembly area, before theWorkstation/Window is updated. The object and all its parts are complete-ly drawn in the pixmap and the pixmap is then copied to the Worksta-tion/Window for display on the screen. The pixmap is sized to the extentof the object and is initially cleared in the current background color.

The pixmap for an object is freed whenever any of the following conditionsoccur:

1. the internal transformation matrix (move, scale, rotate) changesfor an object (or for any object higher in the Graphical ModelingHierarchy, such as a Group or Model)

2. the object's extent changes (radius, startangle, stext)

3. the viewing transformation changes (zoom, pan)

4. the Workstation/Window is resized (G_WIN_RESIZE)

5. the Workstation transformation changes (gmsWsWind( ),gmsWsWindXY( ), gmsWsPort( ), gmsWsPortXY( ))

6. the Workstation/Window, View, or object is freed (gmsObjFree())


Dynamics

The pixmap is reconstructed during the next display pass. In order tomaximize program performance, the application programmer/screen build-er should construct double-buffered objects so that the six conditions listedabove rarely occur.

Since software double buffering slows down the display of objects, onlythose objects that must be double-buffered should be marked. For exam-ple, it is better to make a Group and mark it than to simply mark the entireModel, since the pixmap for the Group will likely be smaller than the pix-map for the Model.

Error MessageIf software double buffering is used on large objects or Workstation/Win-dows on some X servers, the following error message sequence8 mayappear:

X error 11 bad allocX error 9 bad drawablemkpixmap: could not create pixmap.

On Unix systems, SL-GMS uses X pixmaps for software double buffering.On Windows systems, SL-GMS uses bitmaps for software double buffer-ing. As some platforms are limited in their off-screen drawables (which iswhat pixmaps are), the above error messages appear when double buffer-ing occurs. These error messages result each time SL-GMS attempts tocreate a pixmap that the system cannot provide. The basic limitation isthat the server runs out of off-screen drawable memory. If SL-GMSdetects this error has occurred, it turns double buffering off for an objectthat is to be drawn using software double buffering for that particular dis-play pass. Therefore, the object flashes as it is erased and redrawn.

Flagging GroupsIn SL-GMSDraw, objects are marked for software double buffering usingthe doublebuffer option of the Object Flags window.9 The dbflag flagshould not be set on individual objects being transformed; excessive over-head results because the pixmap for each object must be freed and recon-

8. On a Windows system the error message would be "...NT_pixmap: new pixmap dc: create Compatible Bitmap".

9. The Object Flags window is displayed by selecting Properties in the Object Pull-Down Menu, and then Flags in the Properties submenu.


Dynamics

structed on each display pass. Rather, the objects should be grouped withthe dbflag flag placed on the Group. The Group should have a back-ground object (such as a Rectangle) with an extent large enough to coverall possible extents that may occur with the foreground object(s) traversalso that the extent of the Group does not change.

In many cases, it is faster to avoid the erasure of foreground objects in aGroup. This optimization can be accomplished by setting the noeraseoption of the Object Flags window on the Group and attaching the followingDynProp to the background object as well.

<variables that make foreground objects move>= *

redraw

In SL-GML, the command dbflag is used to mark an object for softwaredouble buffering; the command is described in the chapter SL-GML Refer-ence of the SL-GMS Quick Reference.

In an application program, the gmsDoubleBufferFlag( ) function enables ordisables software double buffering on an object. The function is describedin the section Dynamics — double-buffering in the SL-GMS Function Refer-ence.

The dump code "2" is included in the permanent flags for the Prim class toindicate that an object is marked for software double buffering.

Software double buffering can be set for Graphical Primitive and Worksta-tion/Window objects.

Double-buffering ModesDouble buffering is set for Workstation/Window objects by means of theG_WS_DBUFF_ERASE or G_WS_DBUFF_CLEAR Workstation option bitsas described in the gmsWorkst( ) function in the SL-GMS® Function Refer-ence. In software double buffering, a pixmap sized to the extent of the win-dow is used.

SL-GMS has two Double-buffer Modes: Erase Update (set withG_WS_DBUFF_ERASE) and Clear Redraw (set withG_WS_DBUFF_CLEAR). Erase Update Mode is the SL-GMS default.


Dynamics

In Erase Update Mode, Workstations/Windows are drawn in the back bufferin the same manner as in Single-buffer Mode: objects that have changedare erased and redrawn. After the buffers are swapped, or pixmap is cop-ied, the drawing is repeated in the back buffer so that the two buffers are inphase.

In Clear Redraw Mode, a Workstation/Window is cleared and completelyredrawn in the back buffer before the buffer swap or pixmap copy. Afterthe buffer swap, or pixmap copy, no drawing occurs in the back buffer/pix-map.

Clear Redraw Mode is used for Workstations/Windows in which most of theobjects are continually changing. Time is saved by avoiding a selectiveerase.

In summary, Erase Update Mode is desirable when only a few objects onthe screen are changing. Clear Redraw Mode is preferable when manyobjects in a large area of the screen are changing.

EXAMPLE unsigned int workst_options = 0;workst_options = workst_options

| G_WS_FULL_SCREEN| G_WS_KEEP_ASPECT| G_WS_CONCAVE_FILL

/* Erase Update Mode */| G_WS_DBUFF_ERASE;

/* set default Workstation options */gmsSetWsDefOpts(workst_options);/* Workstation is created in gmsMainInit( ) function */gmsMainInit(argc, argv);


Dynamics

Dynamics driven by array variables

In many applications that use SL-GMS, much of the data presented are inthe form of arrays. These data may be arrays of text strings, arrays ofintegers or reals, or even arrays of user-defined structure types (which maycontain other structures).

SL-GMS provides the ability to reference array member elements fromwithin dynamic expressions, using the standard "bracket" syntax:

array[index]

Referencing of array-member elements is particularly useful in accessingarbitrary array elements from different screen graphical elements.

In addition to this basic capability, it is permissible to omit the indexexpression from within the brackets in a dynamic expression. When sucha dynamic expression is evaluated, the index of the current part within theowning Group or Model is used as the index to access the array.

If a DynProp on an object has a reference to an array variable, the indexpassed down is used to access the array. In this way, a single copy of aSubModel Instance is used to display data that are contained in an array,using a different array element for each drawing of the SubModel.

Using Models with Array Dynamics on the SubModel parts is an effectiveway to optimize performance for any screen which contains rows or col-umns of information, either strings, integers, reals, or structures.

SL-GMD Syntaxarrayname[indexexpr] (access to array variable using

an index expression)arrayname[] (access to array variable using

traversal index)

Additional SL-GMD Actiondynarray (mark a Group, Model, or Instance

so it passes the index of eachpart down as the traversal indexto be used in Array Dynamics)

It is necessary to put the dynarray action in a DynProp only on a Group,Model, or Instance, that is, to pass down a traversal index. The dynarray


Dynamics

action provides for the default case where the Group, Model, or Instance isto be treated as a unit, that is, each part receives the same traversal index.The dynarray action must be used explicitly to make use of array dynamicsin this way.

LimitationArray dynamics are currently limited to one-dimensional arrays.

Dynamics driven by structure variables

Access functions for structure data types are available in SL-GMS.SL-GMS recognizes variables of the form

structure_name.member_name

in DynProps. The steps required to use the structure access features areas follows:

1. Define the application’s data structures.

2. For each structure, use gmsVarTypeDefine( ) to tell SL-GMS thesize and structcode of each data structure. structcode must bein the range 0x200 - 0x2000.

3. Use g_struct_define( ) for each structcode to place them in theStructure Definition Table. The syntax is:

intg_struct_define (structcode)

int structcode;

4. Use g_struct_member_define( ) to define each member of eachstructure. The syntax is:

intg_struct_member_define (structcode,

member_name,member_offset,member_typecode, size1, size2)

int structcode;char *member_name;char *member_offset;int member_typecode;


Dynamics

int size1;int size2;

5. Use gmsVarDefine( ) to inform SL-GMS of the address and typeof each structure. A single variable name identifies the entirestructure.

LimitationsThe current implementation of DynProp structure access has the followinglimitations:

• only single-level structures are allowed (i.e., var1.value)

• gmsVarChanged( ) must be called on the entire structure, not onindividual members

• GISMOs do not work on structure members because GISMOs donot know about the types of structure members

Below are possible workarounds for this GISMO limitation:

1. Write custom GISMO Action Functions that use the correct datatype for the expected structure member.

2. Create custom GISMOs that are limited to specific structuretypes, or

3. If a specific structure member must be accessed, create a stan-dard variable name for it with gmsVarDefine( ) (i.e., for var.sta-tus, use var_status).

As of this release, SL-GMS provides this interim version of the DynPropaccess to data structures which will be further enhanced in future releases.For example, the g_*( ) functions, to define structures, may be changed.


Dynamics

Renaming variables

SL-GMS allows you to reuse Models and control objects through instanc-ing. Model Instances, also called Instances or SubModels, retain thedynamic properties of the original Model. The various Instances are differ-entiated from the original by renaming variables — the driving variables arerenamed to different variable names. For example, when you develop apanel of gauges used to represent the same process variable coming frommany different sites, a gauge Model is created with dynamic specificationsdriven by the variable volts. The panel Model would then be created with acollection of gauge Model Instances. The volts variable is renamed foreach instance. For example, volts1, volts2, and so on.

Use the Rename Vars tool in SL-GMSDraw to rename the variables of aSubModel that have been instanced into a Model. To use the Rename Varstool, select an object, click on the Dynamics Pull-Down Menu, and selectObject Renamed Variables. The Object Renamed Variables window,shown in Figure 3-26:, is displayed.

NOTE: If a SubModel has no DynProps attached to it, or if the selectedobject is not a Model Instance, the Object Renamed Variableswindow will be empty, since the object does not have anyvariables that need to be renamed.


Dynamics

Figure 3-26: Renaming the "bg_color" variable in a Model Instance

Double-click on a value to highlight and rename it. Once the value is edit-ed, either double-click on another value or hit the <ENTER> key.

Click the Apply button to apply the renamed variables to the object. TheApply button will be enabled after a change, when another cell is clicked,or when hitting the <ENTER> key.

Only one Model Instance at a time may have its variables renamed. If mul-tiple Model Instances are on the Select List, use the Loop Control buttonsin the Main Menu bar (refer to the SL-GMS®Draw User’s Guide) to selectthe next object on the Select List.

Hold, Release, and Clear The Hold button holds the contents of the entire ObjectRenamed Properties window in a hold buffer. The contents in thehold buffer are held until quitting SL-GMSDraw or until changed


Dynamics

by clicking the Hold button again. Leaving the Object RenamedVariables window does not affect the hold buffer, nor doeschanging between Models affect it.

The Release button replaces the current contents of the ObjectRenamed Variables window with the contents of the hold buffer.

The Clear button clears the Renamed Variable strings of all thevariables in the Object Renamed Variables window.

Error checkingWhen you click the Apply button, SL-GMSDraw will determine whether ornot the renaming is valid. If it is not, a dialog box is displayed indicating theline in which the error occurs. Click the OK button to acknowledge theerror, then correct the error and click the Apply button again.

RenamedVars and updating behavior

If a DynProp contains both unconditional and conditional dynamic descrip-tions and the Variable References in the conditional dynamic descriptionare renamed as constants, the object is marked for update before the Vari-able Reference associated with the unconditional dynamic description isinitialized. Unconditional dynamic descriptions are always performedwhen an object is marked for updating, regardless of the Variable Refer-ence.

EXAMPLESThe fcolor action is unconditional, and the stext action in the examplebelow is conditional:

Sample DynProp on a Filled Text Rectangle:*

fcolor box_colorbox_name

= *stext box_name %s


Dynamics

If the variable box_name is renamed to a constant string, theFilled Text Rectangle object is marked for dynamic update, eventhough the variable box_color may not have been renamed as aconstant. To avoid executing the fcolor action, the DynPropshould be rewritten so that both actions are conditional:

Sample DynProp (conditional only) on a Filled Text Rectangle:

box_color= *

fcolor box_colorbox_name

= *stext box_name %s

EXAMPLEObjects are not marked for update during display of a Model or after a callto gmsDynInit( ) in an application program unless

1. all the variables in DynProps on the objects are renamed to con-stants, or

2. all variables are defined and have been marked for update withgmsVarChanged( ) prior to gmsDynInit( ).10

Sample DynProp on a GraphAxis:x_axis dynprop\

(x_min_value\(= *\

(valuelimits x_min_value x_max_value)\(majorspacing x_tickmajor)\(minorspacing x_tickminor)))

10. More information about gmsDynInit( ) and gmsVarChanged( ) is provided in the SL-GMS® Function Reference.


Dynamics

If all four variables, x_min_value, x_max_value, x_tickmajor,and x_tickminor are renamed as constants, or if all thevariables are defined and have had gmsVarChanged( ) calledprior to gmsDynInit( ), the x_axis object appears with tick marksand labels when the Model containing the GraphAxis object isdisplayed. Otherwise, it does not appear until gmsVarChanged() is called.

Nested variables

When SL-GMS Models are nested, their Renamed Variables are also nest-ed. For example, an Instance of a Model containing an Instance of anoth-er Model would contain all variables of both Models.

Intermediate renaming occurs when a SubModel’s variables are renamedto other variables.


Dynamics

EXAMPLEA meter Model contains a DynProp that uses a variable value to rotate aneedle.

A panel Model contains two Instances of meter. In one Instance, value isrenamed volts, in the other instance it is renamed amps:

value::volts (RenamedVars for first Instance)

value::amps (RenamedVars for second Instance)

A master_control Model contains two Instances of panel. The RenamedVariables for the two Instances might look like:

volts::volts1 (RenamedVars for first Instance)amps::amps1

volts::volts2 (RenamedVars for second Instance)amps::amps2

NOTE: Variables that have been renamed to constants in a SubModelare an exception; they cannot be renamed further.

The nested renamed variables feature enables rapid construction ofdynamic objects with complex behaviors. Renamed variables may beattached to complex SubModels within Models to any level of nesting.


Dynamics

Previewing the Dynamic Behavior of Objects

A Model must be saved if it has been edited, before the dynamics can beexercised. In addition, while it is being previewed, the Model cannot beedited or saved. After previewing, the Model is automatically reloaded sothat any changes made by the dynamic updating are discarded.

Selecting the Preview Options option of the Dynamics Pull-Down Menu inSL-GMSDraw, exercises the DynProps in the current Model using datacontained in a data file. The data file has the name of the current Model,with the suffix ".dat."

To create or edit a ".dat" file during a session, the Edit Data File windowmust be invoked. This is done by clicking the Dynamics Pull-Down Menuand selecting the Edit Data File option. Text can then be entered in thiswindow which will create or modify a ".dat" file. If a data file already existsfor this Model, that data file is automatically displayed in the Edit Data Filewindow. Clicking the Save File button writes the file to disk. Clicking theOpen File button displays a dialog window which allows entry of the nameof a data file.

Figure 3-27: "Edit Data File" window

Further information about the format and use of “.dat” files is provided inthesections Variable types in "preview" on page 3-62, and Using test datafor "preview" on page 3-63.


Dynamics

When the Preview Options option is selected, the Preview Options windowis displayed, as shown in Figure 3-28:.

Figure 3-28: "Preview Options" window

The Preview Options window controls the Timer Period (the number of mil-liseconds between each update). Click the Start button to load the "<mod-elname.dat" file11 and begin previewing the Model. Clicking the Stop buttonterminates the preview. Clicking the Pause button suspends dynamicupdating without leaving Preview Mode but the Model cannot be edited orsaved.

NOTE: If another Model is opened while a Model is being previewed, thenewly-opened Model will begin previewing automatically.

Variable types in "preview"The first time a variable name appears in either a data file or operator input(SL-GMSDraw’s preview facility), its type is set to integer or real, basedupon the absence (integer) or presence (real) of a decimal point, or a stringwith the presence of double quotes. Trying to set the variable to a differenttype later results in an error because there is only one global name spacefor preview variables. As a result, if a variable is set to a different type,preview interprets subsequent data incorrectly.

11. If a "<modelname>.dat" file does not exist, a warning message will display and previewing will not occur.


Dynamics

Since some type checking is required by preview, variables and theircorresponding values should be entered consistently. For example, theuser may choose to use only real values with actions which causetransformations and integer values with actions which produce attributechanges.

Using test data for "preview"When Dynamics are previewed, a data specification file (".dat" file) can either be entered manually in the Edit Data File window, orit can be an existing data specification file (which can also be edited in theEdit Data File window).12 Both methods require the same format for testdata.

A basic line of data contains a variable name and value pair, separated bya space, one pair per line. A blank line signals SL-GMSDraw to updatethe dynamic descriptions of objects. No changes appear in the Model untila blank line, signaling an update, appears in the data. <END-OF-FILE>also causes an update.

The preview facility also recognizes other keywords in data files. The key-words can be used to automatically generate trigonometric, incremental, orrandom values for dynamic variables. The data format for preview is spec-ified completely in the section Previewing dynamics of the SL-GMS QuickReference manual.

12. ".dat" files are searched for in the current directory only


Dynamics

Using the "source file" command for "preview"The source file command is provided to load data in an array. Before thesource file command can be used, the array variables must be declared,along with the size of each array. After the source file command, a dataformat is specified. For example, to load three arrays with high, low, andclosing data from a file called "stocks," the following lines are required:13

float high[100]float low[100]float closing[100]source file "stocks"high low closing...endsource

The data declaration in the above example specifies that there are threefloating point arrays: high, low, and closing, each 100 elements in size.The source file "stocks" is opened and read to fill in the arrays. The dataformat section specifies that high, low, and closing values follow in thisorder until a blank line or <END-OF-FILE> is encountered, and that theremay be up to 100 triplets of data. One, or many, triplets may be presenton the same line and carriage returns, spaces, and tabs are ignored; how-ever, a blank line terminates collecting data for the arrays.

In the next example, a source file named "bridge" contains up to 365 inte-gers representing the number of vehicles crossing a bridge for a year. Asecond set of data, also in the same file, represents the high temperaturefor the day. The step keyword is used to supply ascending date data andthe source file keyword is used to read the file containing the counts andtemperatures:

int date[365]int counts[365]float temperature[365]date step 0 364 0 1source file "bridge"counts...

13. The "..." at the end of a line indicates "repeat reading data until a blank line is encountered." For example, the line "high low closing..." indicates "repeat reading the data in triplicates of high, low, and closing until a blank line is encountered."


Dynamics

temperature...endsource

The "bridge" file should contain 365 integers for the vehicle counts, fol-lowed by a blank line, then 365 floating point temperatures.

NOTE: If a source file does not contain as many data items as specifiedin the declaration, the size of the array is changed to reflect thenumber of points read. If there are more data items than fit in thearray, the last element in the array continues to change until thelast datum is read (a blank line or <END-OF-FILE> isencountered).

When using the step or sine keywords with an array, the entire array isupdated each time a blank line or <END-OF-FILE> is encountered. Thesource file is read only when the keyword source file is encountered in the".dat" file. The keyword endsource marks the end of the source file speci-fications.

float high[100]float low[100]float closing[100]source file "portfolio"high low closing...endsourceint date[365]int counts[365]float temperature[365]date step 0 364 0 1source file "bridge"counts...temperature...endsource


4

Version 6.2a- 26 M

Graphs

Introduction

SL-GMS provides facilities for using a variety of Graph types in a flexiblemanner. In SL-GMS, Graphs are Models and are used by instancing themin another Model. After instancing a Graph, the Instance can be moved,rotated, or scaled. Finally, the variables which control scaling and labelingof the GraphAxes, and which drive the GraphTraces, are renamed to con-stants or to other variables.

The SL Standard Graph Library contains the Graph types shown in thechapter The SL-GMS Graph Library of the SL-GMS Quick Reference. EachGraph is identified by its file name in the GRAPHS subdirectory.

Most users are able to use one of the Standard Graph types; however, if anapplication requires a Graph type that is not listed in the chapter TheSL-GMS Graph Library of the SL-GMS Quick Reference, it can be createdby using any of the objects in SL-GMS. The section Designing new Graphson page 4-14 provides more information.

Using Graphs

Graphs are instanced in exactly the same manner as other SubModels.The section Building Models in the SL-GMSDraw User’s Guide providesmore information about instancing SubModels.

The SL Standard Graph Types are stored in the GRAPHS subdirectory ofthe SL-GMS demo/graphs demo directory. The Reference Point used forpositioning the Model is the intersection of the horizontal and vertical axes.If a Graph type does not have two axes, the positioning Point is in the lowerleft corner of the extent (the rectangular box enclosing the Graph type).This Reference Point does not reserve room for the tick marks and labels;the tick marks and labels do not appear until later, after the Graph’s vari-ables are renamed. It is therefore advisable to leave room for them, belowand to the left or right of the axes.

The user should remember that when positioning Graphs, the rectangulararea on which the values are plotted (inside the axes) overwrites any other


Graphs

objects. This rectangular area is erased when the Graph is initialized or theplots are cleared.

Once the Graph SubModel has been instanced, the Instance can bemoved, rotated, or scaled until it has the desired orientation and size.

Before using a Graph from the Standard Graph Library, the user needs tocopy the Graph Model file to the working directory. Any of the Graph Mod-els in the GRAPHS subdirectory can be modified by other users on the sys-tem, or through future releases of SL-GMS. Making a copy of the Modelguarantees that the Models which reference this Graph will continue towork as expected in the future.

Graph components

Figure 4-1: A Graph consists of GraphAxes and GraphTraces

SL-GMS Graphs consist of two basic components: GraphAxes and Graph-Traces.

A GraphAxis consists of a Line, major and minor tick marks, and tick marklabels. When using the Standard Graph Library, the user need only choose

GraphAxis

GraphAxisReference Point major minor tick

GraphTrace(Polyline) (Markers)

GraphTrace GraphTrace(Polyline/Markers)

tick tick label


Graphs

the upper and lower limits for the GraphAxis and pick the spacing betweenthe tick marks. SL-GMS creates the tick marks and tick mark labels. Mostoften the limits on the GraphAxis are known in advance. It is also possibleto re-initialize a GraphAxis so that the limits and labels are modified andthe axes and any plotted Points are re-displayed. GraphAxes that use dateand time labels can also be created.

Most Graph types also contain at least one GraphTrace. GraphTraces canbe collections of Polylines, Markers, or both. The number of Points in eachGraphTrace object is under user control, as is the color and style of theGraphTrace.

Graphs usually also contain a background grid. The use of GraphAxesobjects to construct a background grid is described in the section GridGraphAxes on page 4-18. Graphs might also contain a background Rectan-gle and some sort of Text label.

Graph types

Four kinds of Graphs are established through the dynamic descriptionswithin the Graph: Plot Graphs, Trend Graphs, Bar Graphs, and PieGraphs.

1. Plot Graphs are Graphs which plot data given a horizontal and avertical position for each Point. Plot Graphs are the simplesttype of Graph.

2. Trend Graphs work like the recording plotters which utilize a penwriting on a drum or roll of paper. In trend Graphs, only the verti-cal position of a Point to be plotted is specified. The horizontalposition, the starting Point, stays the same. As more Points areadded, the plot shifts left or right leaving the most recently plot-ted Point at the starting horizontal position. The direction whichthe trend plot shifts is under the user’s control, as is the startingPoint for the trend plot. Trend Graphs which shift up or down(rather than left or right) are also available.

3. Bar Graphs have no GraphTraces and use percent Filled Rect-angles to display data.

4. Pie Graphs have no GraphTraces and use Filled Wedges ofvarying arc lengths to display data.


Graphs

Composite Graphs combine 1, 2, 3, and 4 (above) to create new Graphtypes.

Renaming the GraphAxis variables

Each Standard Graph Type has a number of variables associated with it.Some of these variables must be renamed so that the GraphAxes can bedisplayed. The values of these required variables must be set before theGraph is used.

The GraphAxis variables needing to be renamed are the:

• minimum and maximum values for x and y axes;

• major and minor tick spacing for x and y axes.

Minimum and Maximum ValuesThe range of values that can be plotted is determined by the minimum andmaximum values for each axis. For example, if the values for the horizontalaxis range from 0 to 1000, the minimum x value is 0 and the maximum xvalue is 1000. If the vertical axis ranges from -250 to 375, the minimum y is-250 and the maximum y is 375. These minimum and maximum values arereal numbers and can have decimal parts. For example, it is possible tohave a range from .120 to 1.115 if necessary.

Some Graphs have date and time axes, which make it possible to labelGraphAxes with ranges of date values (days, months, quarters, years) ortime values (hours, minutes, seconds).

Tick Spacing and LabelingThe spacing between major and minor tick marks should be chosen so asto adequately mark the axes. The major tick marks, which have labelsassigned to them, should be close enough to clearly identify positions onthe axis. However, if the major spacing is too small, the labels will crowd —even overwrite — each other. For best results, tick marks should be cho-sen that divide evenly into the axis range. For example, if the range is 0 to1000, using 100 as the major tick spacing produces eleven tick labels.

Minor tick spacings should evenly divide into the major tick spacings. If 100is the major tick spacing, 20 for the minor tick spacing creates four tickmarks between each major (labeled) tick mark.


Graphs

If the major tick spacings used do not evenly divide the range, one end ofthe axis will not be labeled with a major tick mark.

Figure 4-2: shows a Graph with a horizontal range of 0 to 1000, major tickmarks every 100, and minor tick marks every 20. The vertical axis rangesfrom .12 to 1.2, with a major tick spacing of .09 and a minor tick spacing of.03.

Graph showing use of tick spacingEven with the unusual range on the vertical axis, both axes are neatly labeled. On the horizontal axis, the major spacing of100 evenly divides the range of 1000 (1000/100=10.0), and the minor spacing evenly divides the major spacing (100/20= 5.0). The major spacing on the vertical axis, .09, evenly divides the range, (1.2 -.12 = 1.08, 1.08/.09=12.0),while the minor spacing of .03 evenly divides .09 (.09/.03 = 3.0). If a Graph is created which is not labeled at itsmaximum on an axis, a different major tick spacing is used, onewhich evenly divides the range.

Figure 4-2: Graph showing use of tick spacing

Using variables for axis limitsIt is possible to use variables instead of constants when setting the valuelimits on GraphAxes and GraphTraces. These variables must be set tosome value before the initialization of the Graph.


Graphs

Value limits on GraphAxes and GraphTraces can be reset. The Graphs inthe SL Standard Graph Library include dynamic descriptions which clearand reset a Graph when these variables are changed, thus, a Graph can bedynamically rescaled after it is initialized. An application program can alsoarrange to autoscale Graphs by examining the data to be plotted and set-ting the variables appropriately.

Logarithmic GraphAxesThe SL logarithmic GraphAxis uses log 10. Certain constraints for Renam-ing Variables are used with logarithmic Graphs. Some of these constraintsare based on the nature of logarithms:

• The minimum value for a logarithmic GraphAxis must never be0, and must always be a power of 10 (e.g., 1, 10, 100, 1000, andso on);

• The minor tick spacing for a logarithmic GraphAxis must beequivalent to the minimum value for that GraphAxis;

• The major tick spacing must always be -10 (to notify SL-GMSthat the GraphAxis is logarithmic).

More information about the GraphAxis object is provided in the sectionGraphAxis objects on page 4-16.

Renaming GraphTrace variables

Configuring the GraphTrace entails renaming the variables that "drive" theGraphTrace. These variables correspond to the horizontal (x) and vertical(y) values of the Points to be plotted. A pair of variables exists for eachtrace which appears in a Graph. This is not true of trend Graphs, whereonly the vertical (y) position is set, and for bar Graphs, where a variable foreach bar must be renamed. In addition, the color and style of the Polylinesor Markers which make up the GraphTrace can be changed.

Sometimes it is desirable to display an array of Point values in a singleupdate pass. Graphs have array variables for this purpose. The arrays arefilled with the x and y values of the Points to be plotted, either by an appli-cation or by using a ".dat" file. The Graphs are then automatically updatedto display a trace containing the specified Points. The application programmust call gmsVarChanged( ) on both the x and y values.


Graphs

NOTE: GraphTraces are dynamically allocated and are therefore notsaved when the Model is saved.

Multi-color GraphTracesUsually a GraphTrace is drawn in a single color. However, it is also possi-ble to display a Polyline trace made up of different colored line segments.

Multi-color GraphTraces for each update pass are created by placing anecolor action into the dynamic description for the GraphTrace:

trace_y_array

= *

plotreset

ecolor trace_color

plotdata trace_x_array trace_y_array

The following dynamic description must be deleted from the Graph tem-plate if it exists:

trace_color

= *

ecolor trace_color

The array variables are then renamed:

1. The num_points (trace#_length) variable is renamed to a neg-ative number (i.e., the number of Points in the trace multiplied by-1).

2. The trace#_color variable is renamed to an array of color indi-ces (integers). Each array element corresponds to the color of aline segment. The length of the array should be num_points -1.

3. The trace#_x_array and trace#_y_array variables are renamedto arrays of the x and y values to be plotted.

More information about GraphTrace objects is provided in GraphAxisobjects on page 4-16.


Graphs

Multi-styled GraphTracesUsually a GraphTrace is drawn in a single line style. However, it is alsopossible to display a Polyline trace made up of different line styles.

Multi-styled GraphTraces for each update pass are created by placing anestyle action, which references an array of line style numbers, into thedynamic description for the GraphTrace:

trace_y_array

= *

plotreset

estyle trace_style_array

plotdata trace_x_array trace_y_array

The array variables are then renamed:

1. The num_points (trace#_length) variable has the 0x80000 bitset.

2. The trace#_style_array variable is renamed to an array of linestyles (integers). Each array element corresponds to the linestyle of a line segment. The length of the array should benum_points -1.

3. The trace#_x_array and trace#_y_array variables are renamedto arrays of the x and y values to be plotted.

For example, a multi-colored,1 multi-styled trace with 11 points would havethe numpoints (trace#_length) variable set to -11-32768, while a sin-gle-colored, multi-styled trace with 11 points would have the numpoints(trace#_length) variable set to 11+32768.

More information about GraphTrace objects is provided in GraphAxisobjects on page 4-16.

1. The section Multi-color GraphTraces on page 4-7 provides further information.


Graphs

Graph variables

A complete list of the variable names used in SL Standard Graphs is pro-vided in the chapter The SL-GMS Graph Library of the SL-GMS Quick Ref-erence.

Renamed Graph variables: an example

An example is shown below of the variables defined for a Graph containinga single GraphTrace with a Polyline as they appear in the ObjectRenamed Variables window in SL-GMSDraw.

Figure 4-3: indicates how the GraphAxes looks after the Graph is initializedand a GraphTrace is plotted.

backgr_color :: 8num_points :: 12reset :: (x==13)trace_color :: 7trace_x_array ::trace_x_value :: xtrace_y_array ::trace_y_value :: sin(x / 4)x_max_value :: 12.x_min_value :: 0.x_tickmajor :: 2.x_tickminor :: 1.y_max_value :: 2.y_min_value :: -1.y_tickmajor :: .5y_tickminor :: .25


Graphs

Figure 4-3: Graph with variables renamed (after Previewing)

Any variable can be used without renaming it, however, all Instances ofGraphs which contain the same variable and have not been renamed areaffected when that variable’s value changes.

To animate a Model containing an Instance of this Graph with the variablesrenamed as shown in the example above, a data file can be created con-taining the following information. Alternatively, this information can beentered interactively while using the Edit Data File option of the DynamicsPull-Down Menu in SL-GMSDraw.


Graphs

EXAMPLE

Sample data for Previewing Graph

The system is updated each time a blank line is encountered inthe data. Each time the variable x changes, it triggers theplotting of the next Point in the GraphTrace. The value of yvaries according to the sine of x/4, displaying a portion of a sinecurve.

To rescale a GraphAxis, the minimum and maximum values arechanged for the axis the user wishes to rescale. The dynamicdescriptions on the GraphAxis and GraphTrace in the SL GraphLibrary cause both the axis and the traces to be redrawnaccording to the new scaling.

Any variables which apply to the Graph must be initializedbefore the Graph is updated for the first time. In this example, xis set to 0 before the first blank line. If a variable is not set to aparticular value, it will contain some random value and a randomPoint may be plotted on the Graph.

x 1.

x 2.

x 3.

x 4.

x 5.

x 6.

x 7.

x 8.

x 9.

x 10.

x 11.

note: blank line between data


Graphs

Using trend Graphs: an example

The next example depicts renaming variables for a trend Graph,"htrend.m1", in the GRAPHS directory. Two additional variables appear;x_shift_val and x_start. The trace_x_value variable will not be present(the reset variable is also not present).

The number of Points in the GraphTrace is set equal to the number ofPoints which can be plotted along the x axis. If a greater number of Pointsis used, the extra Points will be drawn at the minimum or maximum hori-zontal range, depending upon the direction of the shift. In this example, thesame sine wave as in the first example is plotted, however, it shifts to theleft as the value of x changes. The same input data shown in the firstexample also applies to this Graph.

backgr_color :: 8num_points :: 12trace_color :: 7trace_x_array ::trace_y_array ::trace_y_value :: sin(x / 4)x_max_value :: 0.x_min_value :: 10.

x_tickmajor :: 2.x_tickminor :: 1.y_max_value :: 2.y_min_value :: -1.y_tickmajor :: .5y_tickminor :: .25

x_shift_val :: 1.x_start :: 0.


Graphs

Figure 4-4: Trend Graph that shifts to the left

The direction of the shift in trend Graphs depends upon two elements: thevalues of the limits on the horizontal (x) axis, and the sign of the value ofx_shift_val. Each time a new Point is plotted, the x_shift_val is added tothe x value of all the Points previously plotted. In the example above,shown in Figure 4-4:, the x_shift_val was positive but the horizontal axisbegan at 10. on the left, and ran to 0 on the right, thus, the plotted lineshifted toward the left, as the x values increased toward 10. If the axis lim-its were from 0 to 10., the x_shift_val must be negative to cause the plot-ted trace to shift to the left. In general, if the value of x_start is greaterthan the value of x_max_value, the x_shift_val must be negative.


Graphs

Designing new Graphs

SL-GMS supplies a variety of two-dimensional Graph templates. Thesetemplates are Models that are copied and used as Instances whereverGraphs are needed, however, the Graphs provided may not be sufficientfor every user’s purposes. This section explains how custom Graphs aredesigned.

The Graph templateThe easiest method of creating a custom Graph is to create a new Graphtemplate (".g" file). A Graph template is an SL-GMS Model which complete-ly specifies the appearance and dynamic behavior for a single Graph type.The template is created using a text editor and the SL Graphical ModelingLanguage (SL-GML).2

The simplest way to design a new Graph template is to begin with a copy ofan existing Graph template. Graph templates use two special objects thatare applicable to Graphs only. The GraphTrace object corresponds to aplotted line, or trace, in a dynamically changing Graph where the oldestPoint may disappear when a new Point is plotted. GraphTraces alsoinclude attributes appropriate for displaying plot lines.

The second object, the GraphAxis, describes the parts which comprise anaxis. A GraphAxis object includes templates for the line that makes up theaxis and for tick marks and tick mark labels, and a range for the values thatwill be plotted against this axis. SL-GMS uses this range, or valuelimits, tolabel the tick marks on the axis appropriately.

GraphTrace and GraphAxis objects are combined into the Graph templateModel. Once a Graph template Model is designed, it can be used in manyapplications, or serve as an example for different Graph templates. SomeSL-GML commands are associated only with building Graph templates,and others are associated with special dynamic actions used in the dynam-ic descriptions for GraphAxis objects and GraphTrace objects.

Once the Graph template is constructed, it may be instanced in other Mod-els, connected to process variables, and animated. The SL-GMSDrawinterface is the easiest way to position Instances of Graph SubModels andto rename the variables associated with them. The sections Using Graphs

2. The template is not created with SL-GMSDraw.


Graphs

on page 4-1 and Renaming the GraphAxis variables on page 4-4 provideadditional information.

A Graph template is a Model with three sections:

• a local SubModel with template parts;

• definitions of GraphAxis and GraphTrace objects; and

• dynamic descriptions.

The local SubModel contains objects used as templates (or dummyobjects) for constructing the Graph’s axes, tick marks, and GraphTraceobjects. These parts are copied when used in a GraphTrace or GraphAxisobject; the template objects are not themselves visible in the SubModel.

The GraphAxis and GraphTrace objects are created by SL-GML com-mands. The graphaxis and graphtrace commands use the template partsthat were defined in the local SubModel. Other SL-GMS objects may alsobe added to the Graph template at this point.

At a minimum, a dynamic description defines which variables are used toplot the Points in the GraphTrace. A dynamic description must exist foreach GraphTrace in the Graph template. Usually, other parts of a GraphModel may be associated with formal variables, such as the value limits ona GraphAxis, or other SL-GMS objects that are part of the Graph. Theseformal variables are renamed when the Graph Model is instanced andallow the creation of Graphs with flexible axis ranges.

On-line examples of Graph template Models are provided in the GRAPHSsubdirectory. (GRAPHS is a subdirectory of the demo/graph directory.)Copies of these templates can be used as the starting Point for designingnew Graph template Models. The user should choose the style of Graphtemplate closest to that of the desired Graph.


Graphs

GraphAxis objects

The GraphAxis object includes those parts that would be expected of aGraph’s axis: a line, divided by tick marks and appropriate labels along theaxis. A GraphAxis consists of a Polyline template, several template objectsused for the tick division markers, and labels. An unlimited number ofGraphAxis objects may appear within a single Graph type.

A GraphAxis object is defined with the following SL-GML command:

name: graphaxis axisline majortick minortick\ ticklabel

The name identifies the object within SL-GML. The graphaxis commandtells the SL-GML interpreter to create a GraphAxis object. axisline is thename of a template object that establishes the attributes used in theGraphAxis object.

Two types of axis divisions, or tick marks, exist: major and minor. Majortick marks are labeled automatically when the Graph is displayed, usingthe ticklabel object as a template. Minor tick marks are displayed withoutlabels. Both major and minor tick marks are copies of the template objects,in fact, the same template object can be used for both.

Usually, the tick mark templates are small Polylines that intersect with theaxisline at right angles and extend below or to the left a short distance. Noconstraints are placed on the size of the lines used as tick mark templates,however, tick mark templates must be constructed relative to the Point (0,0) so they can be positioned correctly along the axis. The tick marksappear in the same relative position when the template is copied along theaxis. Tick marks should not extend above or to the right of the axes (withinthe coordlimits area); this is the display area used for the GraphTraces,and tick marks in the region may be erased or destroyed as the GraphTrac-es are updated.

The ticklabel is the name of a text object that is copied and placed to iden-tify each major tick mark. The ticklabel may be any object containing text.When the ticklabel template object is created, it should be positioned rela-tive to the line used as the major tick mark template.

The GraphAxis template objects (majortick, minortick, and ticklabel) speci-fy the location and appearance of one or more objects relative to the Graphaxis. For example, the object majortick specifies the location (relative tothe axisline) and appearance (line style, line width, and line color) of all


Graphs

major tick marks on the axis. When SL-GMS constructs the Graph axis, thelocation of each major tick mark is computed and copies of majortick aremade at the appropriate locations.

SL-GMS also computes the values for the major tick labels, using the val-ues given for major tick spacing and valuelimits. The format used in the ticklabel is based upon a formatting string that is inserted into the tick labeltemplate. For example, if the tick label is to be a real value with a minimumfield width of four digits (including a decimal point), and two places to theright of the decimal point, it will contain the formatting string "%4.2f". Thetable of formatting codes is provided in the section Formatting strings ofthe SL-GMS Quick Reference.

The following example shows the SL-GML commands required to producea white horizontal axis. The axis has black major tick marks two units longbelow the axis, white minor tick marks one unit long which lie below theaxis, and white raster text labels positioned below each major tick mark.

Portion of Graph template for axis template objectstemp: model

ecolor 7 // black lineestyle 1 // solid lineewidth 2.0// thick linexline: line 0 0 1 1// axis line templatexmajor: line 0 -2 0 0// major tick templateewidth 1.0// thin linexminor: line 0 -1 0 0// minor tick templatetcolor 7 // white textfont 5 // text font 5prec 0 // raster textalign 2 1// center aligned textxlabel: text "%g" 0 -3// general-purpose fmt

endmodel// Create the GraphAxisxaxis: graphaxis temp.xline temp.xmajor temp.xminor\

temp.xlabel

NOTE: The tick marks and tick label are defined relative to Point (0, 0).


Graphs

Grid GraphAxes

The GraphAxis object is also used to construct a background grid forGraphs. The grid is constructed by creating a GraphAxis object with only amajortick object. For example

x_grid: graphaxis nil \temp.x_grid_tick\nil\nil

Note that there is no axis line, no minortick, and no axis label. Dynamics forthis GraphAxis depend upon the minimum and maximum valuelimits of thex axis and the majorspacing variable.

Date and time GraphAxes

Date and time labeled GraphAxes have been added to SL Graphs.GraphAxis objects can be labeled with:

• seconds

• minutes

• hours

• days of the week

• months

• quarters

• years

A flexible scheme has been worked out which permits the template design-er to completely specify the format which is to appear as labels on majortick marks. The template designer simply places a format specification intothe Text template object for the GraphAxis. The template designer thenspecifies a minimum and maximum range.

The values for the minimum and maximum ranges take two forms — onefor date and one for time.


Graphs

The date format requires integer numbers for values. Values are interpret-ed as two, three, or four digits for the year (yy), two digits for the month(mm), and two digits for the day (dd):

[yy]yymmdd

EXAMPLEThe Fourth of July in 1776 would be represented as:

17760704

and the same day in 1990 would be represented as:

19900704

or

900704

The ability to specify the year as two digits unfortunately sets a lower limiton date-labeled GraphAxes, however, the upper range for dates shouldextend to 9999 (safely into the future). Dates with two-digit years with yygreater than 50 imply 19yy, while dates with yy less than or equal to 50imply 20yy. The date calculation handles most vagaries of the Julian calen-dar correctly — skipping leap years every 400 years — however, the miss-ing 12 days in September 1752 cause a problem and throw off the dateGraphAxes day of week calculation into centuries prior to 1752.

The time format requires real numbers for values. Values are interpretedas two digits of hour (hh), two digits for minutes (mm), two digits for sec-onds (ss), and fractions of a second (ff) after the decimal point:

hhmmss.ff

EXAMPLENoon is:

120000.00

and one-tenth of a second before midnight is:

235959.9

Times can be output in 12 or 24 hour notation, and an AM/PM notation canbe included. Since base 60 is used for minutes and hours, values for sec-onds and minutes 60 or greater are modulo 60, that is, 60 becomes 0, 61


Graphs

becomes 1, 62 becomes 2, and so on. Similarly, values for hours greaterthan 23 are converted to modulo 24.

NOTE: Dates and times must not be preceded with a 0 (zero); if they are,the value is interpreted as octal (base 8).

It is also possible to control the number of digits displayed, for example,not displaying fractions of seconds. Major tick spacing for times must alsobe a real number.

Ten different types of GraphAxes exist: one numeric type and ninedate/time types. Each type specifies the spacing that is to be used whenthe GraphAxis is labeled. The spacing for numeric GraphAxes is real num-ber spacing. The spacing on a date GraphAxis is always integer and ismeasured in days, months, four quarters, and so on (the complete list ispresented below). The spacing on time GraphAxes is always integer, andis measured in seconds.

The base unit of spacing for a date GraphAxis is days, however, it is possi-ble to use two different day bases: a seven-day week and a five-day (Mon-day through Friday) week. Even when a month or year GraphAxis is used,it is important that the five or seven day week base be included, whichevercorresponds to the data used.

The ~numeric GraphAxes type is the default, and is used for labelingGraphAxes unless one of the other nine formats is specified. Formats arespecified by using a type string to begin the format string in the Text labeltemplate object. The type strings are:

~numeric The default type, real number spacing

~daily Day labels, seven-day week spacing

~monthly Month labels, seven-day week spacing

~quarterly Four quarters in a year, seven-day week spacing

~yearly Year labels, seven-day week spacing

~workdaily Day labels, work-week (five days) spacing

~wdmonthly Month labels, work-week spacing

~wdquarterly Quarter labels, work-week spacing


Graphs

~wdyearly Year labels, work -weeks spacing

~time Time, seconds spacing

The type strings are followed by format description strings. By concatenat-ing an integer to these format description strings, the number of charactersdisplayed can be controlled. For example, using the string ~dayname3 lim-its the display of day names to three characters (Mon, Tue, and so on). Theformat description strings are:

~daynumber Day of the month

~dayname Day of the week (Monday, Tuesday, and so on.)

~monthnumber Month of the year by number (1-12)

~monthname Month of the year by name

~quarternumber Quarter of the year

~yearnumber The year

~yearnumber2 The last two digits of the year

~hour Hour part of the time (12 hour clock)

~12hour Hour part of the time (12 hour clock)

~24hour Hour part of the time (24 hour clock)

~minute Minute part of the time

~second Second part of time

~realsecond Seconds with fractional part (to two decimal places)

~ampm am/pm notation (lower case)

~AMPM AM/PM notation (upper case)

The type strings and format description strings are combined to describehow the GraphAxes labels are to appear. Other characters not matchingthe type or format description strings appear unchanged in the label output.


Graphs

EXAMPLETo display hours, minutes, and seconds, separated by colons, with anAM/PM notation on the following line, the string:

"~time ~hour:~minute:~second\n~AMPM"

produces a tick label that looks like:

3:15:23PM

for three fifteen in the afternoon. The colons appear in the output betweenthe formatted hour, minute, and seconds.

The demo/graphs subdirectory contains two examples of date/timeGraphAxes. The "xstockvol.m1" Model has an x GraphAxis labeled byworkdays and months. (To produce dual labels, two overlapping GraphAx-es are used.) The template for this Graph is named "stock2vol1.g" and isin the GRAPHS subdirectory. The Text template objects used to producethis x GraphAxis are shown below:

x_axis_label_day: text "~workdaily ~daynumber" 0 -2.0x_axis_label_mon: text "~wdmonthly ~monthname3" 0 -3.5

These template objects are included in the command that creates theGraphAxes:

// X Date Axis: using "weekdaily" and "wdmonthly" axesx1_axis: graphaxis temp.x_axis_line\

temp.x_axis_majortick\temp.x_axis_minortick\temp.x_axis_label_day

x1_axis coordlimits 0. -0.5 80. -0.5x1_axis majorspacing 7.0x1_axis minorspacing 1.0x1_axis dynprop\

(date_min (= *\(valuelimits date_min -(date_total_days - 1))\(majorspacing date_space_major)\

))


Graphs

// Month Axisx2_axis: graphaxis temp.x_axis_line\

temp.x_axis_minortick\nil\temp.x_axis_label_mon

x2_axis coordlimits 0. -0.5 80. -0.5x2_axis majorspacing 1.0x2_axis dynprop\

(date_min (= *\(valuelimits date_min -(date_total_days - 1))\

))

Three variables to be renamed control the minimum, maximum, and labelspacing on this Graph. The date_space_major variable is renamed as theconstant 7, which places date labels every seven days. The date_min vari-able sets the beginning date for the xstockvol.m1 example. date_min hasbeen renamed to the constant 880104, corresponding to the date of thebeginning data in the data file. The maximum is defined by renamingdate_total_days to 365. This takes advantage of a feature within SL-GMD:in the example above, (date_total_days - 1) is preceded by a minus sign(-).

NOTE: If the maximum for a valuelimits action is a negative number, it istreated as a delta value; it is added to the minimum value toproduce the maximum valuelimit.

In the example, the maximum valuelimit will be date_min + 364. In otherwords, a negative maximum valuelimit works as a range.

The values used for plotting a GraphTrace against a date/time GraphAxismust also be modified. Just as plotting a GraphTrace against a logarithmicGraphAxis requires using the log( ) function as an argument to the plotda-ta action, a function is required to convert time or date values into thescaled values used by the date/time GraphAxes. SL-GMS provides the fol-lowing conversion functions for GraphTraces and GraphAxes displayingdate and time values.


Graphs

Date and time conversion functionsgms_udate_delta_in_days (date1, date2)gms_udate_delta_in_wdays (date1_date2)gms_udate_add_days (date, number_of_days)gms_udate4_add_days (date, number_of_days)gms_udate_add_wdays (date, number_of_workdays)gms_udate4_add_wdays (date, number_of_workdays)gms_utime_delta_in_secs (time1)gms_utime_in_secs (time1, time2)gms_secs_in_utime (seconds)gms_utime_add (time1, time2)gms_utime_add_secs (time, seconds)gms_utime_delta (time1, time2)gms_current_utime( )gms_current_udate( )gms_current_udate4( )gms_gettimeofday ( )

More information about specific conversion functions is provided in thesection Date and time functions recognized in DynProps of the SL-GMSQuick Reference. Use of specific conversion functions is demonstrated inthe next example.


Graphs

EXAMPLEIn a GraphTrace plotted against a GraphAxis in the x dimension, a conver-sion function is used to convert the first argument to the plotdata action.The following SL-GML commands are taken from the stock2vol1.g tem-plate (located in the demo/graphs/GRAPHS subdirectory) and demon-strate how a conversion routine is used.

The functions listed above are intended to be used in dynamic descriptions— specifically, as arguments to the plotdata action. They also may becalled from an application.

trace1_close: graphtrace 365\nil\temp.close_mark

trace1_close coordlimits 0. 21. 80. 61.trace1_close dynprop\

(hlc1_min (= *\(xvaluelimits 0 (date_total_days - 1))\(yvaluelimits hlc1_min hlc1_max)\(plotreset)\

))\(hlc1_close (= *\

(plotreset)\(plotdata\

gms_utime_delta(date_data,date_min)\hlc1_close)\

))


Graphs

Non-Graphical components of GraphAxis objects

Associated with each GraphAxis object are several values which controlthe way in which the axis is drawn. One set of values determines the rangefor the axis; a second set establishes the coordinate space in which theaxis will be drawn; another value sets the spacing between major tickmarks; and a final value sets the spacing between the minor tick marks.

name valuelimits x_min_value x_max_valuename coordlimits xmin ymin xmax ymaxname majorspacing x_tickmajorname minorspacing x_tickminor

The name field is the name of a GraphTrace object that was created withthe graphtrace command.

The valuelimits data field specifies the data values at the endpoints of theaxis. Labels will be drawn along the axis depending upon these limit val-ues. The valuelimits will correspond to the horizontal or vertical valuelim-its for the GraphTraces plotted against this GraphAxis.

The coordlimits set the endpoints of the axisline. The template axisline isonly copied, and the points used when making the template axisline do notaffect the positioning of the GraphAxis. Only the attributes (color, style,width) of the axisline template are used in the GraphAxis. Because plottingand clearing GraphTraces may affect the GraphAxis, it is good practice tooffset the GraphAxis slightly (.5) from the coordlimit area used by theGraphTraces. For example, part of a thick GraphAxis line will be erasedthe first time a plotclear action, associated with a GraphTrace dynamicdescription, occurs.

The majorspacing value specifies the distance between the major tickmarks drawn along the axis. The units used correspond to the data valuesused in valuelimits.

The minorspacing values provide the spacing between minor tick marks,using the same units (i.e., taken from the range given in valuelimits).

As explained in Renaming the GraphAxis variables on page 4-4, the majorand minor tick mark spacing should evenly divide the range set by the val-uelimits.


Graphs

EXAMPLExaxis valuelimits 0.0 125.0xaxis coordlimits 0. -.5 75. -.5xaxis majorspacing 25.0xaxis minorspacing 5.0

In the example above, one major tick mark was drawn every 25.0 unitsalong the axis, with one minor tick mark every 5.0 units along the axis. Alabel is placed under each major tick mark, as shown below:

Figure 4-5: GraphAxis object with variables renamed to constants

These GraphAxis values may be changed dynamically to implement axisrescaling by attaching a DynProp to the Graph Axis, which changes theminimum and maximum values, along with the tickspacing values. Forexample, a GraphAxis named xaxis might have the following dynamicdescription associated with it:

xaxis dynprop\(x_min_value (= * \


Values assigned for the dummy variables (either through the ObjectRenamed Variables option of the Dynamics Pull-Down Menu in SL-GMS-Draw or values assigned at run time by the application program) to the val-ues listed below result in the following axis:

x_max_value :: 250.x_tickmajor :: 50.x_tickminor :: 25.x_min_value :: 0.

Figure 4-6: GraphAxis object with variables renamed to variables


Graphs

To create more flexible GraphAxis objects, the parameters for valuelimits,majorspacing, and minorspacing are associated with formal (dummy)variables, allowing the GraphAxis to be dynamically rescaled.

GraphTrace objects

The GraphTrace object allows the display of a series of data values with anSL-GMS Polyline, Marker, or both. An example (template) Polyline and/orMarker are used during the creation of a GraphTrace object. An unlimitednumber of GraphTraces may appear within a single Graph type.

The template objects used in the creation of GraphTrace (or GraphAxis)objects are part of a local SubModel. The attributes of the template objectsare copied when the template objects are used. The template objectsthemselves are never displayed because they are parts in a SubModel thatis not instanced. (SubModels are never displayed unless the SubModel isreferred to by an Instance.)

A GraphTrace object is defined with the following SL-GML command:

name: graphtrace maxtracelength traceline tracemarker

The name identifies the object to SL-GML, in the same manner that nameswork in SL-GMS. The command graphtrace is recognized by SL-GML as"create a GraphTrace object."

The maxtracelength,3 or history, is the number of Points to keep in thisGraphTrace object. As a GraphTrace object is updated, the plotted Pointsare added to the object. Only maxtracelength number of Points is kept,and, when a Point is added when there are already maxtracelength num-ber of Points, the oldest plotted Point is discarded and that part of the traceis erased.

The traceline is the name of a Polyline that has the attributes desired inthe GraphTrace object. The tracemarker is a Marker that has theattributes desired in the GraphTrace object. If a GraphTrace without aPolyline is needed, rather than using the traceline object, the keyword nilis used in place of the name of a Polyline. Or the tracemarker name canbe nil and only a Polyline will mark the plotted Points. The same tracelineor tracemarker objects can be used in more than one GraphTrace object.

3. The maximum tracelength can range from 0 to the maximum value which can be represented by an unsigned short.


Graphs

These objects are used as templates only, and are not "consumed" whenthe GraphTrace is built.

The following example shows the SL-GML commands required to draw asolid, single-width, green trace with blue markers. Comments to theSL-GML commands follow the double slashes (//).

EXAMPLE// Set up a local SubModel with trace// template objects.graph_ex: model

temp: modelecolor 2 // green lineestyle 1 // solid line styleewidth 1.0 // normal line widthtr_line: line 0 0 1 1// trace line template

// with dummy end pointsmcolor 4 // blue marker colormstyle 3 // asterisk marker stylemsize 1.0 // normal-size markerstr_marker: mark 0 0// trace marker template

// with dummy pointendm // end local submodel

// Create a GraphTrace with a history of 10 pointstrace1: graphtrace 10 temp.tr_line temp.tr_marker// Create a second GraphTrace with red markers onlytemp.tr_marker mcolor 1trace2: graphtrace 20 nil temp.tr_marker// GraphTrace using different colorstemp.tr_line ecolor 3// yellow trace linetemp.tr_marker mcolor 5// magenta trace markerstrace3: graphtrace 6 temp.tr_line temp.tr_marker// GraphTrace using dashed line and no markerstemp.tr_line estyle 2// dashed linetrace4: graphtrace 15 temp.tr_line nil

Later, the graphtrace command and the creation of the template objectswill be shown in the context of a Graph template.


Graphs

Non-Graphical components of GraphTraces Associated with each GraphTrace object are several values which controlthe way in which data are plotted. One set of values determines the rangeof data that will be accepted, and another establishes the limits within theGraph template Model space within which the data will be plotted.

The following SL-GML example shows the commands used to initializethese fields:

EXAMPLEname xvaluelimits x_min_value x_max_valuename yvaluelimits y_min_value y_max_valuename coordlimits xmin ymin xmax ymax

The xvaluelimits and yvaluelimits data fields specify the minimum andmaximum x and y data values which are plotted on the Graph. Data valueswhich fall outside these limits are constrained so that they are plotted with-in the valuelimits for this GraphTrace. For example, if the maximum x valueis 100, an x value greater than 100 is treated as if it were 100. These valuelimits normally correspond to the limits defined for the GraphAxis objects.

The coordlimits (coordinate limits) data field specifies the minimum andmaximum x and y SL-GMS World Coordinates for the GraphTrace. (TheSL-GMS coordinate systems are explained in the section Coordinate sys-tems on page 8-1.) These values establish a rectangular area that all plot-ted Points will appear within, and are used to map the data values intoSL-GMS World Coordinates.

EXAMPLEtrace1 xvaluelimits 0. 125.trace1 yvaluelimits 0. 500.trace1 coordlimits 0. 0. 75. 75.

In the example above, the data Point (0., 0.) would be plotted at GraphPoint (0., 0.) and the data Point (125., 500.) would be plotted at GraphPoint (75., 75.). Points in between these values are scaled appropriately,based upon the values used for valuelimits and coordlimits.

When a Graph template Model is constructed, the entire work area can beutilized. The Graph template can be reduced in size by scaling when it is


Graphs

positioned by instancing it within another Model. Even though the Graphtemplate has been scaled and positioned within another Model, the coordi-nates used within the Graph Model are the same as when the Graph wascreated. Thus, the Graph template designer is not concerned with theeventual position of a Graph in a Model when choosing the coordlimits. Thecoordlimits are picked while creating the Graph template, and should corre-spond to the appearance and aspect that the final Graph will have, not itseventual position in other Models or screens.

It should be noted that scaling of Graph template Models adds overheadthat is better avoided. Each Point in a scaled Graph template must betransformed (which involves floating point arithmetic), so it is best to designGraph templates with the coordlimits established corresponding to theeventual size of the instanced Graph. For example, if the user plans to fitfour Graphs on a screen, each Graph template should fit in one quarter ofthe screen (leaving room for the labels and tick marks) for best system per-formance.

The coordlimits are always set after the GraphTrace object is created,and remain the same within the Graph template Model. The valuelimits fora GraphTrace can be adjusted through the use of dynamic descriptionsand renamed variables. The valuelimits establish a range of x data valuesand y data values that will be plotted within the area set by the coordlimits.The valuelimits should correspond to the range (value limit) used for theaxes.

To create truly flexible Graph templates, it is now necessary to be able toadjust the ranges used on the axes, as well as the ranges for the x y data.The valuelimits for an axis can be assigned, using a dynamic description,to be formal (dummy) variables. These dummy variables are renamedwhen an Instance of the Graph is made. The actions affecting GraphTraceobjects are described next.

Creating GraphTrace dynamics

A single DynProp must be specified for each GraphTrace, in order to asso-ciate actual data variables with the GraphTrace. Usually, the x and y datavalues for a plotted Point will be specified by different variables. In order toplot a single Graph Point, the following dynamic description could be used:

trace1 dynprop \(trace1_x_value (= *\


Graphs

(plotdata trace1_x_value trace1_y_value)))

The plotdata action keyword instructs the GraphTrace object to plot a newdata Point (with x and y values specified by the data variablestrace1_x_value and trace1_y_value) whenever either of the variablestrace1_x_value or trace1_y_value changes.

The application program is responsible for ensuring that both variable val-ues are correct before updating the GraphTrace. Updating the GraphTracewhen only one variable value has been received causes the GraphTrace touse the old value of the other variable — which almost certainly will causeundesired results. The gmsVarChanged( ) function should be called onboth GraphTrace variables at the same time.

In addition to plotdata, there are seven other actions that apply to Graph-Trace objects. The xvaluelimits and yvaluelimits actions can be associat-ed with a GraphTrace so that these data ranges can be set to constantvalues after the Graph Model has been instanced.

EXAMPLEThe following dynamic description associates the values x_min_value andx_max_value to the range for xvaluelimits, and y_min_value andy_max_value to the range for yvaluelimits. The following dynprop replac-es the dynamic description shown earlier for trace1.


Graphs

Dynamics used for a single incrementing GraphTracetrace1 dynprop\

(x_min_value (= *$tracelength num_points)\(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\plotreset)\

))\(trace1_x_value (= *\(plotdata trace1_x_value trace1_y_value)$)$trace1_color (= *\

(ecolor trace1_color)$)

After instancing the Model where trace1 appears, these dummyvariables must be renamed as constants. (Renaming variablescan be done from a SL-GMS drawing editor; the SL-GML syntaxis shown here as an example.)

EXAMPLEgr_inst renamedvars

x_min_value :: 0.\x_max_value :: 100.\y_min_value :: 75.\y_max_value :: 125.

These valuelimits would be appropriate when used with GraphAxis objectshaving the same ranges, that is, from 0 to 100. on the x axis, and from 75.to 125. on the y axis.

It is also possible to rename these dummy variables as variables. The val-ue of these variables when the x_min_value variable is changed willestablish the valuelimits used with this GraphTrace. These valuelimits canbe modified by changing the values of the associated variables.

Other aspects of GraphTrace objects can be changed dynamically. Thetracelength action can be used to set the number of Points kept in the


Graphs

GraphTrace. The plotreset action removes all of the Points kept in theGraphTrace

object. The plotclear action erases the rectangular region described bythe coordlimits.

There are two plot shift actions. The plot shift actions are used in trendGraphs to shift each Point in the GraphTrace over when a new Point isadded. If there are already tracelength number of Points in the Graph-Trace, the oldest Point is discarded. The GraphTrace is shifted in the hori-zontal (x) direction by plotshiftx, and in the vertical (y) direction byplotshifty. The value that follows these actions determines which directionand the amount the Points will be shifted. Essentially, the value followingthe action is added to either the x values (in plotshiftx) or the y values (inplotshifty) in all the Point pairs, then a new Point is plotted. This has thedesired effect of shifting the GraphTrace. The following dynprop definesactions appropriate for a trend Graph.

Dynamics for single trend-style GraphTracetrace1 dynprop\

(x_min_value (= *\(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(tracelength trace1_length)\(plotreset)\(plotclear)\

))\(x_shift_value (= *\

(plotclear)\(plotshiftx x_shift_val)\// Shifts trend data(plotdata x_start trace1_y_value)\

))\(trace1_color (= *\


In the above example, a plotclear4 action was used to erase allthe Points before the plotshiftx action shifted the Points.


Graphs

When two GraphTraces are in a Graph template Model, thesecond GraphTrace object’s dynamic description does not havea plotclear action. The following dynamic descriptions are fortwo GraphTrace objects used in ordinary (non-trend) Graphs.

Dynamics for two GraphTraces; only one "plotclear" action used

trace1 dynprop$x_min_value (= *\

(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(tracelength trace1_length)\(plotreset)\(plotclear)\// Plotclear on first

))\(trace1_x_value (= *\

(plotdata trace1_x_value trace1_y_value)$)$trace1_color (= *\



(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(tracelength trace2_length)\(plotreset)\// No plotclear here


(plotdata trace2_x_value trace2_y_value)$)\(trace2_color (= *\

4. The majority of the Graphs in the Standard Graph Library contain a background rectangle which is redrawn whenever a Point is plotted. Redrawing the background rectangle erases the rectangular region described by the coordlimits. Therefore, the Graphs with a background rectangle do not use the plotclear action.


Graphs


The next set of dynamic descriptions is appropriate for a pair ofGraphTrace objects that will be loaded with an array of data. Inarray-load GraphTrace objects, all the Points are replaced eachtime the data are updated.

Two GraphTraces loaded with arraystrace1 dynprop\

(x_min_value (= *$xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(tracelength trace1_length)\(plotreset)\(plotclear)\


(plotreset)\// Discard old points(plotclear)\// Clear coordlimit area(plotdata trace1_x_value trace1_y_value)\

))\(trace1_color (= *\

(ecolor line_color1)$)


(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(tracelength trace2_length)\(plotreset)\

))\trace2_x_value (= *\

(plotreset)\// Discard old points(plotdata trace2_x_value trace2_y_value)\

))\


Graphs

(trace2_color (= *\(ecolor trace2_color)\

))

Graph template structure

The following example shows the structure of a general Graph template. Adiscussion about each component follows.

// Define the Graph typegraphtype: model

// Define local SubModel for templatestemplates: model

// Define templates for axes, labels, tracesxaxisline:line ...xmajortick:line ...xminortick:line ...xticklabel:text ...yaxisline:line ...ymajortick:line ...yminortick:line ...yticklabel:text ...traceline:line ...tracemarker:mark ...

endm// define Graph componentsheader: text ...xlabel: text ...ylabel: text ...// Create two GraphAxesxaxis: graphaxis ...yaxis: graphaxis ...// Create the GraphTracestrace1: graphtrace ...trace2: graphtrace ...// Initialize GraphAxis Non-Graphic componentsxaxis valuelimits ...


Graphs

xaxis coordlimits ...xaxis majorspacing ...xaxis minorspacing ...yaxis valuelimits ...yaxis coordlimits ...yaxis majorspacing ...yaxis minorspacing ...

*** continued on next page ***// Initialize GraphTrace Non-Graphic componentstrace1 xvaluelimits ...trace1 yvaluelimits ...trace1 coordlimits ...trace2 xvaluelimits ...trace2 yvaluelimits ...trace2 coordlimits ...// Specify GraphAxis dynamicsxaxis dynprop (x_min_value (= *\


yaxis dynprop (y_min_value (= *\(valuelimits y_min_value y_max_value)\(majorspacing y_tickmajor)\(minorspacing y_tickminor)))

// Specify GraphTrace dynamicstrace1 dynprop (x1_value (= *\

(plotdata x1_value y1_value)))trace2 dynprop (x2_value (= *\

(plotdata x2_value y2_value)))endm

The Model named graphtype is the Graph template. One Graph templateis required for each type of Graph (xy plot, trend, scatter plot) used by theapplication.

The SubModel named templates includes the definition of the GraphAxisand GraphTrace template objects. These objects are used to provideSL-GMS with descriptions of the appearance and relative location of vari-


Graphs

ous Graph components. Because the template objects are defined in alocal SubModel, they are not drawn when the Graph is displayed.

The components of the Graph are defined (in the graphtype Model), initial-ized, and linked to process variables. Any number of GraphTrace objects,GraphAxis objects, Graph labels, and other SL-GMS objects may beincluded in the Graph template. The DynProp which accompanies eachGraphTrace object makes the association to the process variables. Option-al dynamics may be specified for GraphAxis objects (to support rescaling,clutter control, and so on). Other objects can be added to the Graph tem-plates, such as

percent-filled Rectangles, and animated using dynamic descriptions. Thevariables defined in the Graph template’s dynamic descriptions are formal(or dummy) variable names which may be replaced with actual variablenames when the Graph type is instanced. The Object Renamed Variablesoption of SL-GMSDraw’s Dynamics Pull-Down Menu is used to renameformal variables in Instances of Graph Models.

Example Graph template Model

Graph: model// ===============================================// Define templates for Graph components// ===============================================

temp: model// templates for x, y axesecolor 7estyle 1ewidth 2.0xaline: line 0 0 1 0yaline: line 0 0 0 1// tick marks relative to (0, 0)xtmajor: line 0 -2 0 0ytmajor: line -2 0 0 0ewidth 1.0xtminor: line 0 -1 0 0ytminor: line -1 0 0 0// axis labelstcolor 7


Graphs

font 5prec 0path 1height 2.0size 0 0align 2 1xtlabel: text "%g" 0 -3align 3 3ytlabel: text "%g" -3 0// template for trace linesestyle 1ewidth 1.0ecolor 1traceline: line 0 0 1 1// template for trace markersmstyle 3msize 2.0mcolor 1tracemark: mark 0 0

endm // end template SubModel// Define Graph axesxaxis: graphaxis temp.xaline temp.xtmajor\

temp.xtminor temp.xtlabelxaxis coordlimits 0.0 -.5 30.0 -.5xaxis dynprop\

(x_min_value (= * \(valuelimits x_min_value x_max_value) \(majorspacing x_tickmajor) \(minorspacing x_tickminor) \

))yaxis: graphaxis temp.yaline temp.ytmajor\

temp.ytminor temp.ytlabelyaxis coordlimits -.5 0.0 -.5 22.0yaxis dynprop\

(y_min_value (= * \(valuelimits y_min_value y_max_value)\(majorspacing y_tickmajor)\


Graphs

(minorspacing y_tickminor)\))

// Define trace with Linestrace1: graphtrace 25 temp.traceline niltrace1 coordlimits 0.0 0.0 30. 22.trace1 dynprop\

(x_min_value (= * $tracelength trace1_length) \(xvaluelimits x_min_value x_max_value) \(yvaluelimits y_min_value y_max_value) \(plotreset)\(plotclear)\

)) \(trace1_x_value (= * \

(plotdata trace1_x_value trace1_y_value)$) $trace1_color (= *\


// Define trace with markerstrace2: graphtrace 25 nil temp.tracemarktrace2 coordlimits 0.0 0.0 30. 22.trace2 dynprop\

(x_min_value (= *\(tracelength trace2_length)\(xvaluelimits x_min_value x_max_value)\(yvaluelimits y_min_value y_max_value)\(plotreset)\


(plotdata trace2_x_value trace2_y_value)$)$trace2_mcolor (= *\

(mcolor trace2_mcolor) $)

endm


5

Version 6.2a- 26 M

GISMOs

Introduction

Objects with input dynamics and optional display dynamics are called GIS-MOs. SL-GMS GISMOs (Graphical Interactive Screen ManagementObjects) provide a means of directly manipulating application data, display-ing data, and defining other aspects of interactive behavior. GISMOs areused in application screens to:

• allow a user to display another screen (or enter another State1)via an input Event, such as a mouse click or pressing a functionkey;

• provide a highlight for selection feedback;

• affect and reflect the status of an associated variable.

NOTE: GISMOs can be activated with both the middle and right mousebutton. To use the middle mouse button to activate a GISMO,the Workstation option, G_WS_NOPASTE, must be set ingmsWinFlags( ).2

In addition to specifying a list of actions to be performed whenever an inputevent occurs (input dynamics), the attributes of the elements that comprisea GISMO are also able to change in response to changes in one or moreapplication variables (output dynamics).

A large number of ready-to-use, predefined GISMOs are provided in theSL-GMS GISMO Library and described completely in Appendix A. GIS-MOs may be instanced multiple times on multiple screens. Each time aGISMO is replicated (instanced), the variables associated with it may bechanged using the standard RenamedVars functionality. Renaming vari-ables on page 3-55 contains a description of the Rename Vars functional-ity.

1. States are discussed in Chapter 6.2. Refer to the SL-GMS® Function Reference.


GISMOs

GISMO Construction

GISMO DynProps are generally placed on the GISMO Model,3 although theDynProp may also be placed on any Model part such as a Group or an indi-vidual object. The DynProp attached to a GISMO generally consists oftwo logical parts:

1. input dynamics following the pound-sign (#) which call functions4

to manipulate SL-GMS internal or application program vari-able(s) and are performed when the GISMO is selected, and

2. output dynamics which include highlighting action(s) to be per-formed when the GISMO is selected. Typically these highlight-ing Actions are driven by the change in the SL-GMS internal orapplication program variable(s).

3. Placing a DynProp on a Model Object is described in the section Adding dynamics to a Model object on page 3-44.

4. Simple actions can be included here but they are typically not used in this context.

call function inresponse toinput event

do Action(s)in response tochange in value ofSL-GMS internalor applicationprogram variable(s)

SL-GMS internalor applicationprogram variable(s)

changed value

*

GISMO DynProp

set value

Figure 5-1: General structure of a GISMO DynProp


GISMOs

The syntax of a GISMO DynProp is:

Figure 5-2: Syntax of a typical GISMO DynProp

Often, the input-event function calls used in GISMO DynProps are from theSL-GMS GISMO Action Function Library:

call <SL-GMS GISMO Action Function>

Alternatively, a user-defined function may be used. The SL-GMS GISMOAction Functions provide optimized, special-purpose actions for behaviorsthat are often used. An SL-GMS GISMO Action Function is used exactly the same way as anyvalid SL-GMS action keyword, such as fcolor, vis, movex, and so on.The GISMO designer can think of the SL-GMS GISMO Action Functions asextensions to actions valid in DynProps. For example, the function gms_hilite_percent1( ) isreally an extension to the move Action — it performs move given a variableand a range. The only difference between the SL-GMS GISMO Action Func-tions and action keywords is that SL-GMS GISMO Action Functions arefunction calls.

A complete list of the SL-GMS GISMO Action Functions is provided in thesection SL-GMS GISMO Action Functions on page A-81.

SL-GMSDraw Syntax SL-GML Syntax

# (#\call to (call to

input-event function input-event function)\. . . (...))

* (*\action <argument> (action <argument>)\. . . (...))


GISMOs

NOTE: Application programs not using gmsMainInit( ) must have a callto gmsInitGismos( ) in order to have the GISMO ActionFunctions recognized as action keywords in DynProps.

Typically, the input-event functions calls used in GISMO DynProps providevariable manipulation capabilities (usually following a gms_*_array( ),gms_*_var( ), or gms_*_selobj( ) naming convention).

The actions used in the display dynamics portion of GISMO DynProps aregenerally functions which describe highlighting behaviors (usually followinga gms_hilite_*( )-naming convention).

An object can be highlighted by changing its edge width and color ("edge"highlighting) or by changing the fill color of its interior ("fill" highlighting).Other kinds of highlighting include making visible a companion object toone that is always displayed ("vis" highlighting) or selecting between twodifferent representations of an object ("flip" highlighting).

Additional types of highlighting may be defined by the user, but the typesprovided with the distributed SL-GMS GISMO Library cover most uses.Other highlighting behavior can be supplied either by adding to the set ofsupporting functions or by defining the highlighting in terms of actionsattached to DynProps.

For example, the DynProp shown below works by setting and testing theSL-GMS internal variable _ _button_hilite:5

#call gms_flash(callback)

*call gms_hilite_color(&__button_hilite, hc, uc)

The gms_flash( ) function sets the value of _ _button_hilite to 1 on a loca-tor press and the gms_hilite_color( ) function responds to the value of_ _button_hilite. If _ _button_hilite is set to 1, gms_hilite_color( ) per-forms fill highlighting with hc. Next, gms_flash( ) resets _ _button_hiliteto 0 on a locator release and gms_hilite_color( ) performs fill highlighting

5. Only two underscores (_ _) are in front of button_hilite. These are part of the variable name. The space between each underscore is for illustrative purposes only, it is not part of the variable name.


GISMOs

with uc. Because _ _button_hilite is called by reference (and operator),the value of _ _button_hilite is actually changed.

The SL-GMS GISMO Action Functions work with variables which fall intothree general categories:

1. an array,

2. a single value, or

3. a pointer to an object.

Highlight Functions

Among the SL-GMS GISMO Action Functions are the gms_hilite_*( ) func-tions which provide an extension to standard SL-GMS Actions performedon any object using DynProps.

In a formal SL-GMS GISMO, the highlighting must often be controlled byan application variable, in many cases simply a Boolean variable. In addi-tion, it may even be desirable to parameterize the highlighting colors inorder to allow global changes.

A common DynProp to control such highlighting might look like:

variable= 1 (highlight)

fcolor hicolortcolor hicolor

= 0 (unhighlight)fcolor uncolortcolor uncolor

Constructing such descriptions in DynProps is not a complex task, but ifmany such objects are going to be in an application it can be more efficient— particularly in terms of memory space used — to replace lists of actionswith a function that performs the same action.

The following equivalent function, provided in SL-GMS and used in a Dyn-Prop, provides essentially the same functionality without the overhead oneach DynProp:

*call gms_hilite_color(&variable, hicolor, uncolor)


GISMOs

In the function, the variable is passed along with the highlight color and theunhighlight color; the object graphics are changed whenever gmsDynUp-date( ) is called.

The example above is simple, but many of the most common types of GIS-MOs require a Group of objects to be operated upon, not just a singleobject. For example, a CHECK GROUP GISMO is usually constructed asa collection of individual buttons, each being highlighted or unhighlightedaccording to

a Boolean variable contained in an array, where each element correspondsto a member of the Group.

The gms_hilite_color( ) function, shown in the above example, is designedso that the object on which the function is being performed (the objectwhich is being DynUpdated) may be either an individual object or a collec-tion of objects (either a Group or a Model). If it is a collection of objects,the variable passed is assumed to be an array variable, and each elementof the array is applied to each member of the Group.

The calling syntax for the gms_hilite_*( ) functions is described in the sec-tion SL-GMS GISMO Action Functions on page A-81.


GISMOs

Sample construction of a GISMO

Any SL-GMS graphical object can have input dynamics attached to it, andbe made into a GISMO. For this example a light switch, shown in Figure5-3:, is created.

Figure 5-3: Light switch


GISMOs

The background of the light switch contains a total of six objects. There is alarge rectangle with a smaller rectangle centered inside it. The edge colorof the two rectangles are black. There are also two copies of a circle with aline through it representing screws. The edge color of the circle and theline through it are also black.

Figure 5-4: Background pieces of the light switch

largerectangle small

rectangle

circle with a black line

circle with a black line

ecolor = 7fcolor = 10 ecolor = 7

fcolor = 24

fcolor of circle = 24

fcolor of circle = 24


GISMOs

The background with all of the objects in the correct position is shown inFigure 5-5:.

Figure 5-5: Assembled background of the light switch


GISMOs

The GISMO part of the light switch is composed of two Groups of fourobjects each (two rectangles and two lines). The first two objects are alarger rectangle that has the smaller rectangle on top of it, as shown inFigure 5-6:.

Figure 5-6: First part of GISMO

smallrectangle

fcolor 4ecolor 17

largerectangle

fcolor 17ecolor 7

before after


GISMOs

Next, two lines are created from the top edges of the large rectangle to thetop edge of the smaller rectangle, as shown in Figure 5-7:.

Figure 5-7: Two lines added to switch object

The four objects in Figure 5-7: (the large and small rectangle, and the twolines) are selected and made into a Group.6 The Group then has the name"off_state" attached to it.7

6. The four objects are selected, and then the Group option of the Object Pull-Down Menu is selected. Refer to the SL-GMS®Draw User’s Guide for more information.

7. Refer to the SL-GMS®Draw User’s Guide for information on attaching a name to an object.

lineecolor = 4

lineecolor = 4line


GISMOs

A copy is made of the "off_state" object. The new copy is named"on_state", and is rotated 180 degrees, so it appears as shown in Figure5-8:.

Figure 5-8: "off_state" and "on_state" objects

The "off_state" object is placed on top of the "on_state" object. The"on_state" object8 is selected, then the "off_state" object, and the twoobjects are made into a Group. The following input dynamics are attachedto the Group.

#call gms_cycle_var(callback, &var)

*call gms_hilite_cycle(&var)

The above DynProp calls the gms_cycle_var( ) GISMO action functionwhenever the "off_state"/"on_state" Group is selected. Thegms_cycle_var( ) function cycles var based upon the number of parts in theselected object. The "off_state"/"on_state" Group has two objects in it,therefore, the variable var is cycled between the values of 0 and 1.

8. An object can be selected by name by clicking the Object Pull-Down Menu and selecting the By Name option of the Select submenu.

"off_state" "on_state"


GISMOs

The gms_hilite_cycle( ) function highlights an object in a Group or partusing visibility. The object whose part index is the same as the value ofvar is made visible. Other objects in the part (which could be a Group) aremade invisible.

In a Group, the order of the objects is dependent on what order the objectswere selected before the objects were grouped. In the case of the"off_state"/"on_state" Group, the "on_state" object was selected first,therefore, it is index 0. The "off_state" object was selected second, there-fore, it is index 1.

The "off_state"/"on_state" Group is centered on top of the small rectanglein the light switch background, as shown in Figure 5-9:.

Figure 5-9: Placing the "off_state"/"on_state" Group on the background

light switch background

"off_state""on_state"

Group


GISMOs

To see how the light switch GISMO action functions work, place anInstance of the light switch into a Model. Add a filled Circle to the Model.Attach the following dynamics to the filled Circle.

var= 1fcolor 7= 0fcolor 3

The above dynamics state "whenever the value of var equals one changethe fill color of the filled circle to the color index 7 (black), and when thevalue of var equals zero, change the fill color of the filled circle to the colorindex 3 (yellow)".

Test the Model by selecting Preview Options on the Dynamics Pull-DownMenu. Select Edit Data File in the Dynamics Pull-Down Menu, and type thefollowing line into the Edit Dynamics Window.

var 1

The line shown above sets the initial value of var equal to one. When var isequal to one the fill color of the filled circle is black (color index 7). Click the"switch" part of the light switch. The "off_state" Group is made invisible,and the "on_state" Group is made visible. In addition, the value of var is setequal to 0, and the fill color of the filled circle is yellow (color index 3).

Each time the "switch" part of the light switch is clicked, the visibility of the"on_state" and "off_state" parts in the Group are toggled. In addition, thevalue of var is cycled between the values of one and zero.


GISMOs

Toggle Group

Figure 5-10: Examples of BUTTON GROUP type GISMOs

A GISMO Toggle Group is a group of objects cooperating with each otherin a prescribed manner. Toggle groups come in two types:

• RADIO — only one object (or none) in the group can be "on"(e.g., selected, highlighted and active) at any one time

• CHECK — any, all, or none in the group can be "on" at any onetime

Any set of objects can be grouped together to create a toggle group witheither radio or check behavior. Several GISMO models are provided in theGISMO library to help construct a toggle GISMO group. These "GISMOhelpers" are shown below:

Figure 5-11: "GISMO helper" buttons

0

1

2


GISMOs

Each "GISMO helper" button is stripped of its input dynamics (and strictlyspeaking, by itself is not a GISMO) but can still have renamed variableswhich control its outward appearance. The radio or check behavior is pro-vided by grouping the "GISMO helper" SubModels together and attaching aDynProp to the Group.

Constructing a "GISMO helper"For this example the md_button SubModel will be used. The md_buttonis one of the "GISMO helpers" with the Motif diamond look.

The appearance of the md_button SubModel is created with two objectscalled state_0 and state_1. Each of these objects is a Group that containsa Filled Polygon object and two Polyline objects. The state_0 object con-trols the appearance of the button when it is unselected. The state_1object controls the appearance of the button when it has been selected.

The state_0 object is a Group that consists of a Filled Polygon object,named plate_0, and two Polyline objects, named lower_0 and upper_0,created with the SL-GML code shown below. Only the fill color (fcolor),edge color (ecolor), and edge style (estyle) variables will be shown, sincethese variables differentiate the appearance of the different objects.

state_0: groupfcolor 13ecolor 0estyle 0plate_0: poly 0 2 2 4 4 2 2 0. filled 1fcolor 0ecolor 15estyle 1lower_0: line 0 2 2 0 4 2ecolor 12upper_0: line 0 2 2 4 4 2

endg


GISMOs

Figure 5-12: Parts of the "state_0" Group from the "md_button" GISMO

There is no DynProp attached.

The state_1 object is a Group that consists of a Filled Polygon object,named plate_1, and two Polyline objects, named upper_1 and lower_1,created as shown below. Only the fill color (fcolor), edge color (ecolor),and edge style (estyle) variables will be shown, since these variables dif-ferentiate the appearance of the different objects. The state_1 Group isnormally invisible (vis 0).

vis 0state_1: group

fcolor 14ecolor 0estyle 0plate_1: poly 2 0 0 2 2 4 4 2. filled 1fcolor 0ecolor 15estyle 1upper_1: line 0 2 2 4 4 2ecolor 12lower_1: line 0 2 2 0 4 2

endg

upper_0 lower_0 plate_0

state_0


GISMOs

Figure 5-13: Parts of the "state_1" Group from the "md_button" GISMO

There is no DynProp attached.

There is a Text object that is created as shown below:

text "md_button" 3 0

The following DynProp is attached to the Text object.

DynProp for the Text object

SL-GMSDraw Syntax Description

*stext button_label "%s"theight text_height

when either the button_label or the text_height variable is initialized or changed, replace the text string "md_button" with the text string assigned to the button_label variable and the height of the Text (theight) will be equal to the value assigned to text_height


state_1


GISMOs

A DynProp is put on the Model itself (not any individual part of the Model).

The md_button Model does not contain any input dynamics. The state_1and the state_0 objects are not grouped together because this Model will beused as a SubModel and will be grouped with other Instances of this Sub-Model to produce a BUTTON GROUP type GISMO.

RADIO GROUP GISMORADIO GROUP GISMOs are created by grouping a set of objects togetherand attaching the radio behavior to them. The md_button "GISMO helper"will be used for this example. The md_button SubModel is instanced in aModel and the variables are renamed. For this example, three Instanceswill be placed in the Working View and their variables renamed as follows:

RenamedVars for Instance #1

button_label :: "0"edge_width :: 3text_height :: 2





DynProp for the md_button Model


*ewidth edge_width

whenever the edge_width variable is initialized or changed, the edge width (ewidth) of the Filled Polygon and Polyline objects will be equal to the value assigned to edge_width


GISMOs

Figure 5-14: Three Instances before and after renaming variables

The three Instances are then grouped together. The order of the groupedobjects is important; they should be selected in sequence when grouped(or ordered using the commands in the Order Pull-Down Menu), so thatthey accurately reflect the value of the array or variable associated with theGISMO. For this example, the Instances will be selected from top to bot-tom ("0", "1", and "2").

md_button

md_button

md_button

0

1

2

BEFORE AFTER


GISMOs

Figure 5-15: Using an array to control a Radio Group GISMO

A RADIO GROUP GISMO can use an array or an index variable to controlGISMO highlighting and application behavior. For an array variable(arrayvar in the example below), the function which highlights the GISMOmay be made to affect the attributes of a Group of SL-GMS objects.

The DynProp shown below is attached to the Group of three Instances.These input dynamics produce a RADIO GROUP GISMO driven by anarray variable.

DynProp for the Group


#callgms_radio_array(callback,&arrayvar, 0)

when the GISMO is selected call the function gms_radio_array( )

*call gms_hilite_vis(&arrayvar)

call the function gms_hilite_vis( ) and pass it the address of the variable arrayvar; this will highlight the appropriate part of the GISMO

GISMO arrayvar

0

0

1

0

1

2


GISMOs

The gms_radio_array( ) function associates the array variable, arrayvar,with a set of radio buttons (the Group of three Instances of md_button). Itsets the value of no more than one element of the array to 1 (selected) andsets all the remaining elements to 0 (unselected). The gms_radio_array()function is explained on page A-94.

The gms_hilite_vis( ) function is used for highlighting because in themd_button SubModel, the state_0 object (unselected) is normally visibleand the state_1 object (selected) is normally invisible. Thegms_hilite_vis( ) function will change the visibility of each member of aGroup containing two objects. The visibility9 of the first object alwaysstarts at 1. The visibility of the second object is set to 1 or 0, dependingupon the value of the associated array variable (arrayvar in the exampleabove). In the RADIO GROUP GISMO described above, there are threeInstances (members) of the md_button SubModel in the Group and each ofthese Instances of md_button has two objects; state_0 and state_1. Thisis why the state_0 and the state_1 objects were not grouped together. Ifthey were grouped together, the gms_hilite_vis() function would not workproperly.

9. An object is visible if its visibility is set to 1. It is invisible if its visibility is set to 0.


GISMOs

A RADIO GROUP GISMO can also use an index variable (indexvar in thefollowing example). The value of the index variable determines whichobject in a GISMO is highlighted (index is 0 relative).

Figure 5-16: Using a single variable to control a Radio Group GISMO

The DynProp shown below is attached to the Group of three Instances.These input dynamics produce a RADIO GROUP GISMO driven by anindex variable.

The gms_radio_var( ) function associates an index variable (indexvar inthe example above) with a set of radio buttons (the Group of three Instanc-es of md_button). The function sets the value of the index variable to the



#callgms_radio_var(callback,&indexvar, 0)

when the GISMO is selected call the function gms_radio_var( )

*call gms_hilite_vis_var(&indexvar)

call the function gms_hilite_vis_var( ) and pass it the address of the variable indexvar; this will highlight the appropriate part of the GISMO

GISMO indexvar

20

1

2


GISMOs

index of the selected object. The gms_radio_var( ) function is described onpages A-25 and A-95.

The gms_hilite_vis_var( ) function highlights by changing the visibility ofeach member of a Group (each of the three Instances of md_buttongrouped together) containing two objects (e.g., state_1 and state_0). Thevisibility of the first object always starts at 1. The visibility of the secondobject is set to 1 or 0, depending upon the value of the index variable(indexvar). The gms_hilite_vis_var( ) function is described on page A-92.

CHECK GROUP GISMOCHECK GROUP GISMOs are created by grouping a set of objects togetherand attaching the check behavior to them. For this example thems_button SubModel will be used. ms_button is one of the "GISMO help-ers". The ms_button SubModel is built and grouped into a set of objectssimilar to the md_button SubModel (pages 5-16 through 5-20 describe themd_button SubModel and its grouping into a set of objects).

A CHECK GROUP GISMO uses an array variable to control GISMO high-lighting and application behavior. For an array variable (arrayvar in theexample below), the function which highlights the GISMO may be made toaffect the attributes of a Group of SL-GMS objects. Unlike a RADIOGROUP GISMO, more than one member of the Group can be highlightedat any one time (i.e., more than one element of arrayvar can be set to 1).

Figure 5-17: An array variable used to control a CHECK GROUP GISMO

GISMO arrayvar

1

0

1

0

1

2


GISMOs

The DynProp shown below is attached to the Group of three Instances.These input dynamics produce a CHECK GROUP GISMO driven by anarray variable.

The gms_toggle_array( ) function associates the array variable, arrayvar,with a set of check buttons (the Group of three Instances of ms_button). Itsets the value of each element of the array to 1 (selected) or 0 (unselect-ed). The gms_toggle_array( ) function is explained in greater detail onpage A-106.

The gms_hilite_vis( ) function (refer to page 5-22) performs the same forthe CHECK GROUP GISMO as it does for the RADIO GROUP GISMOusing an array variable.

BUTTON GROUP type GISMO highlightingThe m_button, ma_down, ma_left, ma_right and ma_up "GISMO helpers"are all built similar to md_button and ms_button. They all consist of twogroups, state_0 and state_1, with state_0 normally visible and state_1 nor-mally invisible. Therefore, the gms_hilite_vis( ) or gms_hilite_vis_var( )functions would be used for all of these "GISMO helpers" to provide high-lighting. Other types of highlighting can be used with the BUTTONGROUP type GISMOs to correspond with the type of objects beinggrouped. For example, the radio3 (RADIO GROUP) and toggle3 (CHECKGROUP) GISMOs are each a group of three Filled Text Rectangles that use



#callgms_toggle_array(callback,&arrayvar)

when the GISMO is selected call the function gms_toggle_array( )


call the function gms_hilite_vis( ) and pass it the address of the variable arrayvar; this will highlight the appropriate parts of the GISMO


GISMOs

"edge" highlighting by calling the gms_hilite_edge( ) function. Page A-25provides further information about RADIO GROUP GISMOs and their high-lighting types. Page A-32 provides further information about CHECKGROUP GISMOs.

Using GISMOs

To use an SL-GMS GISMO, an Instance of the GISMO SubModel is placedin the Working View using SL-GMSDraw and its variables are renamed byselecting the Object Renamed Variables option of the Dynamics Pull-DownMenu. To place an Instance of an SL-GMS GISMO into the Working Viewusing SL-GMSDraw select the Available SubModels option of the PalettesPull-Down Menu to bring up the Available Submodels window.10 Select theGISMO from the listing in the Available Submodels window and make anInstance of the GISMO SubModel.

Appendix A, starting on page A-1, provides information about renamingGISMO variables for each of the different type of GISMOs.

Any GISMO in the SL-GMS GISMO Library can be customized by changingits graphical characteristics with SL-GMSDraw. Functional behavior canalso be modified by defining user callback functions and calling themdirectly in the DynProp. Any additional user callback functions must bedeclared to SL-GMS with the gmsAddUserFctn( ) call.

Alternatively, if the range of GISMO behaviors provided via the SL-GMSGISMO Action Functions (listed beginning on page A-81) is not sufficient, auser can provide an enhanced set of functions to perform more specificbehavior. These enhanced functions are accessed in the same manner asthe other user-defined functions available in SL-GMS.

In summary,

• using RenamedVars on Instances of GISMOs in the SL-GMSGISMO Library allows for each Instance to have differentvariables and values control the highlighting and applicationbehavior;

• altering the DynProps of the GISMOs in the SL-GMS GISMOLibrary allows for changing the type of GISMO highlighting;

10. The SL-GMS®Draw Tutorial provides examples on using SubModels.


GISMOs

• creating user-defined functions (to supplement the SL-GMSGISMO Action Functions) and using them in the DynProps ofGISMOs allows for customizations of GISMO behavior.

The GISMO Library

To allow users of SL-GMS to build dynamic graphics screens easily, alarge number of ready-to-use, predefined GISMOs are provided in severalsubdirectories of the demo directory.

These GISMOs can be used, unaltered, to control many different kinds ofdata by selecting the desired GISMO from a list of SubModels. The GIS-MOs can also be customized. A table detailing the contents of theSL-GMS GISMO Library is provided on the following pages.


GISMOs

The SL-GMS GISMO Library

GISMOCategory GISMO Model

NamesFunctional Behavior

On-lineExamples See Page

BUTTON CALL f_callm_callma_callmd_callms_call

calls an application callback function with no highlighting

airportscockpitcolordefexamplesgismossltraderstructdemotutor3tutor4viewtest

A-4

DATSCREEN f_dscrnm_dscrnmd_dscrnms_dscrn

displays a new screen; activates the screen’s .dat file for dynamics

diversedynactionsexamplesgraphsprocessstatestutor1

A-7

POPUP f_popupm_popupma_popup

displays a popup menu or dialog box

colordefstates

A-10


GISMOs

BUTTON(continued)

QUIT f_quitm_quit

exits application program

ccpdemo1cockpitdiversedynactionsexamplesfplangismosgmsdemogmsrungraphsnetworkprocessradarsltraderstatestutor3tutor4viewtest

A-13

RETURN f_returnm_return

returns to previous screen

examplesgismosprocesssltraderstatestutor1

A-15

SCREEN f_scrnm_scrnmd_scrnms_scrn

displays a new screen

gismosstates

A-17

STATE f_statem_statemd_statems_state

invoke a State of a specified State class

process A-20

The SL-GMS GISMO Library(continued)

GISMOCategory GISMO

Model Names

Functional Behavior



GISMOs

BUTTON GROUP

RADIO TOGGLE (button helper)

m_buttonma_downma_leftma_rightma_upmd_button

Grouped in a GISMO GROUP under a DynProp with radio behavior

gismos 5-16

CHECK TOGGLE (button helper)

ms_button Grouped in a GISMO GROUP under a DynProp with check behavior

gismos 5-24

RADIO GROUP

radio3 calls an application callback function with "radio" highlighting (only one GISMO element highlighted at a time)

gismos A-25

CHECK GROUP

toggle3 calls an application callback function with "check" highlighting (any GISMO element toggled on or off)

gismos A-32


GISMOCategory GISMO

Model Names

Functional Behavior



GISMOs

SPECIAL PURPOSE

CYCLE cycle1cycle2

calls an application callback function with a variable cycled through a set of values

gismos A-37

FILL- PERCENT

f_fillm_fill

calls an application callback function with a variable manipulated through a range of values

colordefgismos

A-40

SCROLLBOX(SINGLE and MULTIPLE SELECTION)

m_sboxsm_sboxm

scroll lines of text; allow selection of a single line (m_sboxs) or multiple lines (m_sboxm); optionally call user function(s) upon scrolling and/or selection

gismosgmsrun

A-44


GISMOCategory GISMO

Model Names

Functional Behavior



GISMOs

SPECIAL PURPOSE(continued)

SLIDER f_slidem_slidehm_slidev

calls an application callback function with a variable manipulated through a range of values

gismosradar

A-55

TEXTENTRY ARRAY

calls an application callback function with arrays of fields, type integer, float, or string

gismos A-59

TEXTENTRY VAR

f_textvm_textvtextentry

calls an application callback function with individual fields, type integer, float, or string

examplesgismossltradertutor4

A-67

NON STANDARD

COLORCELLS

colorcellscolarr4

calls an application callback function with a color index variable equal to the color index of the object picked

gismos A-76


GISMOCategory GISMO

Model Names

Functional Behavior



6

Version 6.2a- 26 M

The Enhanced State Management System

Introduction

SL-GMS contains a library of new State Classes. These State Classes pro-vide standard ways to manage various aspects of a real-time dynamicgraphics application, including:

• initialization

• window/View/Model operations

• data source manipulation

• dialog handling

• zoom/pan/layering control

The SL-GMS State Classes are described in the SL-GMS® State ClassLibrary Reference and in the SL-GMS® Enhanced State Management.


7

Version 6.2a- 26 M

Event Handling

Introduction

This chapter takes a close look at how Events are processed, both withinSL-SMS and outside of it. It describes the functions used to set up Eventhandlers for input Events and timer Events.

Event Handling in SL-SMS

In SL-SMS, all Events are dispatched automatically to Event-handler meth-ods defined by State classes, so very little programming is required. In sit-uations where some special functionality is desired, State class methodsfor handling Events may be defined, as described in SL-GMS® State ClassLibrary Reference.

Within SL-SMS, Events are dispatched to State class methods, to GISMOaction functions, or to user-defined functions. The sequence of Event pro-cessing is as follows:

1. SL-SMS determines in which State Instance the Event occurred,based upon the State Instance’s Workstation/Window and View.

2. If the State Instance’s gismoflag is set to G_ON, SL-SMS looksin the State Instance’s Models to determine if an object has beenselected. If the gismoflag is set to G_OFF, the Event is passedto the State class method for that type of Event.

3. If an object has been selected, and if it has input dynamics (i.e.,it is a GISMO) its GISMO action function or user-defined func-tion is called.

Native Control Objects are another way into SL-SMS to simplify event han-dling. Control objects intercept Events directly from Motif and Windows,and translate the Events either into State messages or into variable chang-es.

The SL-GMS® State Class Library Reference provides a discussion ofevent processing in SL-SMS. More information about GISMO action func-tions is provided in Appendix A.


Event Handling

Event handling is illustrated in Figure 7-1.

Figure 7-1: Event-handling

Event

Event

SL-SMS

StateGISMO

Dispatcher

EventDispatcher

Processormethods

System

(Event handlers)

NativeControlObject

Event

gmsWsAddEvent( )


Event Handling

Event codes

The following are the Event codes permitted in the second argument of thegmsWsEventFctn( ) function. These codes are defined in the include file"gmscodes.h".

.

gmsWsEventFctn( ) — Valid Codes for "eventcode" Argument

Event Type Codes DescriptionLocator Events

G_LOC_PRESS Locator pressG_LOC_RELEASE Locator releaseG_LOC_MOTION Locator motion

Character Events

G_KEY_FILTER any key pressG_KEY_PRESS any key pressG_KEY_RELEASE any key release

Window Events

G_WIN_EXPOSE Window exposureG_WIN_RESIZE Window resizeG_WIN_FOCUS_IN Window focus inG_WIN_FOCUS_OUT Window focus outG_WIN_ENTER Window enterG_WIN_LEAVE Window leaveG_WIN_MAP Window mapG_WIN_UNMAP Window unmapG_WIN_DESTROY Window destroy

Other Events G_MSG_CLIENT ???G_USER_EVENT ???


Event Handling

Event modifier codes

In addition to the Event codes listed above, SL-GMS provides Event modi-fier codes. Event modifiers are the buttons or keys held down at the timeof an Event. Event modifiers provide additional information about Locatorand Keyboard Events. These Event modifier codes are contained in"gmscodes.h". These codes are bitwise AND’d with the Event Codes list-ed in the table, gmsWsEventFctn( ) — Valid Codes for "eventcode" Argu-ment. Examples of the use of Event codes are provided in the sectionUsing the event query functions — examples.

Event Modifier Codes

Code DescriptionG_LOC_BUTTON_1 Mouse button 1G_LOC_BUTTON_2 Mouse button 2G_LOC_BUTTON_3 Mouse button 3G_LOC_BUTTON_4 Mouse button 4G_LOC_BUTTON_5 Mouse button 5G_LOC_BUTTON_LEFT (syn. for G_LOC_BUTTON_1)G_LOC_BUTTON_MIDDLE (syn. for G_LOC_BUTTON_2)G_LOC_BUTTON_RIGHT (syn. for G_LOC_BUTTON_3)G_DOUBLE_CLICK Mouse button double-clickG_SHIFT_KEY <SHIFT> keyG_LOCK_KEY <SHIFT LOCK> keyG_CONTROL_KEY <CONTROL> keyG_MOD1_KEY Workstation-dependent modifier key 1G_MOD2_KEY Workstation-dependent modifier key 2G_MOD3_KEY Workstation-dependent modifier key 3G_MOD4_KEY Workstation-dependent modifier key 4G_MOD5_KEY Workstation-dependent modifier key 5G_BPAD_BUTTON_0 Bitpad button 1G_BPAD_BUTTON_1 Bitpad button 2G_BPAD_BUTTON_2 Bitpad button 3G_BPAD_BUTTON_3 Bitpad button 4


Event Handling

SL-GMS supports reporting of mouse "double-click" events on both Win-dows and Unix (X Window System) platforms. The report takes the form ofan additional "modifier" flag for G_LOC_PRESS and G_LOC_RELEASEevents: G_DOUBLE_CLICK, defined in gmscodes.h.

This cross-platform support is implemented using a "best of both worlds"(as opposed to "lowest common denominator") approach.

For example, both Windows and X support programmatic query of theuser’s current "double click time". Only Windows provides a "double clickproximity" filter, so SL-GMS mimics that behavior on X. Windows pro-grams using the traditional win32 API for double-click only receive thoseevents for the left (or "select") button, so SL-GMS avoids that API in orderto report double-clicks on any mouse button. (This means that Windowsapplications which create their own windows for SL-GMS must NOTinclude the "CS_DBLCLKS" identifier when initializing the style field of thewindow class structure.)

Neither system directly supports any kind of notification that a mouserelease event is associated with a double-click; SL-GMS adds theG_DOUBLE_CLICK flag to G_LOC_RELEASE events if the previousG_LOC_PRESS was a double-click and if the release occurs within a radi-us twice as large as that used to identify the double-click G_LOC_PRESS.

Assuming that an application has enabled both G_LOC_PRESS andG_LOC_RELEASE events, it will see the double-click reported as asequence of four locator events:

G_LOC_PRESSG_LOC_RELEASEG_LOC_PRESS(modifier will include G_DOUBLE_CLICK)G_LOC_RELEASE(modifier will include G_DOUBLE_CLICK)

On Windows, the time limit for a double-click is controlled by the user viathe Control Panel. On X systems, the time limit defaults to 500 millisec-onds but can be changed before application startup via the X Resource"multiClickTime" (which many environments use by default but which userscan add to their environment using "xrdb -merge".)

Finally, note that G_LOC_PRESS and G_LOC_RELEASE events areSL-GMS "highlevel workstation" events and as such do not apply to thoseevents which occur inside NCOs ("native control objects"). Proper dou-ble-click handling for those objects is NCO-specific.


Event Handling

State class event-handlers and events

Any State class event-handler functions (except the KeyEvent callbackswhich return an idLinkRef — as shown below) must return int and take asingle argument, the Event:

intcallback (event)

id event; /* an Event object */

Inside the State class Event-handler method, it is often desirable to obtainmore information about the Event. If it is a Locator Event, in which Viewdid it occur? If it is a Keyboard Event, which key was pressed? SL-GMSprovides Event Query functions for this purpose.

Each Event object is a subclass of the G_WsEvent class. The G_WsEventobject contains a pointer to the Workstation on which this Event occurred,its Event code, and a time stamp. Additional information about the Eventis contained in each subclass. The actual class of the Event dependsupon the type of information required by the callback function. There arefour classes of events.

• G_LocEvent — contains information concerning mouse cursorlocation

• G_KeyEvent — contains information concerning single andmultiple key presses

• G_StrEvent — contains the character string entered and theText Edit object used to enter the string

• G_WinEvent — window extent

A KEY_FILTER callback must return a idLinkRef containing the KeyEventobject. KEY_PRESS and KEY_RELEASE callbacks return an int indicatingthe key which was pressed or released.


Event Handling

Using the event query functions — examples

Following are some examples showing different uses of the Event query functions gmsQEvButtons( ), gmsQEvTrigger( ),gmsQEvKeysym( ), gmsQEvStringC( ), and gmsQEvModifiers( ). Thesefunctions are used together inside an Event handler to determine whichcombination of buttons and keys have been pressed.

Example 1The user presses the LEFT mouse button, moves the mouse, and releasesthe LEFT mouse button.

In the G_LOC_PRESS Event-handler:

In the G_LOC_MOTION Event-handler:

In the G_LOC_RELEASE Event-handler:

Function Returns

gmsQEvTrigger( ) G_LOC_BUTTON_LEFT

gmsQEvButtons( ) G_LOC_BUTTON_LEFT

gmsQEvModifiers( ) 0

Function Returns

gmsQEvTrigger( ) 0


gmsQEvModifiers( ) G_LOC_BUTTON_LEFT

Function Returns



gmsQEvModifiers( ) G_LOC_BUTTON_LEFT


Event Handling

Example 2While holding down the <CONTROL> key, the user presses the LEFTmouse button, moves the mouse, and releases the LEFT mouse button.




Function Returns



gmsQEvModifiers( ) G_CONTROL_KEY

Function Returns

gmsQEvTrigger( ) 0


gmsQEvModifiers( ) G_LOC_BUTTON_LEFT and G_CONTROL_KEY

Function Returns



gmsQEvModifiers( ) G_LOC_BUTTON_LEFT and G_CONTROL_KEY


Event Handling

Example 3While holding down the <SHIFT> key and the MIDDLE mouse button, theuser presses the LEFT mouse button, moves the mouse, and releases theLEFT mouse button.




Function Returns


gmsQEvButtons( ) G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE

gmsQEvModifiers( ) G_LOC_BUTTON_MIDDLE and G_SHIFT_KEY

Function Returns

gmsQEvTrigger( ) 0


gmsQEvModifiers( ) G_SHIFT_KEY and G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE

Function Returns



gmsQEvModifiers( ) G_SHIFT_KEY and G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE


Event Handling

Example 4The user presses the "a" key, then releases it.

In the G_KEY_PRESS Event-handler:

In the G_KEY_RELEASE Event-handler:

Example 5While holding down the <SHIFT> key and the MIDDLE mouse button, theuser presses the "A" key then releases the "A" key.

In the G_KEY_PRESS Event-handler:

In the G_KEY_RELEASE Event-handler:

Function Returns

gmsQEvKeysym( ) 0

gmsQEvStringC( ) G_SUCCESSFUL, buffer[0] = a


Function Returns

gmsQEvKeysym( ) 0



Function Returns

gmsQEvKeysym( ) 0

gmsQEvStringC( ) G_SUCCESSFUL,buffer[0] = a

gmsQEvModifiers( ) G_SHIFT_KEY and G_LOC_BUTTON_MIDDLE

Function Returns

gmsQEvKeysym( ) 0


Event Handling


gmsQEvModifiers( ) G_SHIFT_KEY and G_LOC_BUTTON_MIDDLE

Function Returns


Event Handling

Simulating Events

Several functions are available in the SL-GMS API to support user cre-ation, modification, query and addition of SL-GMS events to the "high levelworkstation" event queue.

To create an event, use gmsEvent( ):

idgmsEvent (event_type, workst, destroyCB)

intevent_type;id workst;int(*destroyCB)();

The first argument is an integer code for the desired event type, defined in$GMS_HOME/lib/gmscodes.h. Currently supported event types fall intofour groups and include:

G_LOC_PRESS/* locator events */G_LOC_RELEASEG_LOC_MOTION

G_KEY_PRESS/* keyboard events */G_KEY_RELEASE

G_WIN_EXPOSE/* window events */G_WIN_EXPOSE_RECTG_WIN_RESIZEG_WIN_FOCUS_ING_WIN_FOCUS_OUTG_WIN_ENTERG_WIN_LEAVEG_WIN_MAPG_WIN_UNMAPG_WIN_DESTROY

G_MSG_CLIENT/* message events */G_USER_EVENT


Event Handling

The second argument is an SL-GMS workstation object.

The third argument is a pointer to an optional "destroy callback" functionfor SL-GMS to call when it has finished processing the event. If NULL or ifwhen called the callback returns 0, SL-GMS will deallocate the event.

If successful, gmsEvent( ) returns a typed event object; otherwise it returnsNULL.

When an event is ready to be added to the workstation queue,usegmsWsAddEvent( ):

intgmsWsAddEvent (workst, event)

id workst;id event;

To prepare an event for processing by gmsWsAddEvent( ), type-specificdata usually needs to be attached to the event. For instance, locatorevents need a Point object, keyboard events need a key, window eventsneed an extent, and message events should have data. The API for settingthese attributes, in alphabetical order, is as follows (refer to the SL-GMS®Function Reference for additional information on these functions).

/* set action for message events */intgmsEvAction (event, action)

id event;intaction;

/* set data for message events */intgmsEvData (event, data)

id event;longdata;

/* set extent for window events */intgmsEvExtent (event, extent)


Event Handling

id event;idLinkRefext_list;

/* set keysym for keyboard events */intgmsEvKeysym (event, keysym)

id event;unsigned longkeysym;

/* set modifier keys for keyboard or locatorevents */

intgmsEvModifiers (event, modifiers)

id event;unsigned int modifiers;

/* set object for keyboard or locator events */intgmsEvObject (event, object)

id event;id object;

/* set point for locator events */intgmsEvPoint (event, point)

id event;id point;

/* set "char *" string for keyboard events */intgmsEvStringC (event, char_str)

id event;char*char_str;

/* set "string object" for keyboard events */int


Event Handling

gmsEvStringSO (event, str_obj)id event;id str_obj;

/* set timestamp for any event */intgmsEvTime (event, sec, usec)

id event;unsigned longsec, usec;

/* set trigger button for locator events */intgmsEvTrigger (event, trigger)

id event;inttrigger;

/* set event type for any event */intgmsEvType (event, type)

id event;inttype;

/* set view for keyboard or locator events */intgmsEvView (event, view)

id event;id view;

/* set workst for any event */intgmsEvWorkst (event, workst)

id event;id workst;

In addition to the foregoing "set" functions, query functions are provided asfollows:


Event Handling

/* query action for message events */intgmsQEvAction (event)

id event;

/* query buttons for locator events */intgmsQEvButtons (event)

id event;

/* query data for message events */intgmsQEvData (event)

id event;

/* query extent for window events */idLinkRefgmsQEvExtent (event)

id event;

/* query keysym for keyboard events */unsigned longgmsQEvKeysym (event)

id event;

/* query modifier keys for keyboard or locatorevents */

intgmsQEvModifiers (event)

id event;

/* query object for keyboard or locator events*/

idgmsQEvObject (event)

id event;


Event Handling

/* query point for locator events */

idgmsQEvPoint (event)

id event;

/* query "char *" string for keyboard events */intgmsQEvStringC (event, buffer, buffer_size,

needed_size)id event;char*buffer;intbuffer_size;/* byte size including '\0' */int*needed_size;/* byte size including '\0' */

/* query "string object" for keyboard events*/

intgmsQEvStringSO (event, buffer)

id event;id buffer;

/* query timestamp for any event */intgmsQEvTime (event, sec, usec)

id event;unsigned long*sec,

*usec;

/* query trigger button for locator events */intgmsQEvTrigger (event)

id event;

/* query event type for any event */intgmsQEvType (event)

id event;


Event Handling

/* query view for keyboard or locator events */idgmsQEvView (event)

id event;

/* query view index for keyboard or locatorevents */

intgmsQEvViewIndex (event)

id event;

/* query workst for any event */idgmsQEvWorkst (event)

id event;


8

Version 6.2a- 26 M

Display of Models

Overview

The WinModState controls the display of a Model in a window. The Win-ModState also provides attributes which control the way in which the Mod-el is displayed in the window when the window is created or resized.

The WinModState invokes a hierarchy of standard subStates, each ofwhich manages a specific resource such as a Model, View, or Window.Like all aggregate States, the WinModState directs application messagesit receives to its subStates. For example, an application can set the win-dow frame components, the name of the Model to display, or the size andposition of the Window on the Screen by sending messages directly to theWinModState. Refer to the SL-GMS® State Class Library Reference.

Coordinate systems

There are several coordinate systems used in the display of Models on adisplay screen. Mapping between these coordinate systems allows repre-sentation of Points as real numbers that apply to the application designrather than numbers constrained to an arbitrary scale. The table belowsummarizes the different coordinate systems. The individual coordinatesystems are described in the following sections.

Coordinate System Use Range Description

World Coordinates (WC)

Specification of Points in Models

(-32,768., -32,768.) to (32,767., 32,767.)

page 8-4

Normalized Device Coordinates (NDC)

Specification of Points on an idealized device-surface

0.0 to 1.0 page 8-5


Display of Models

SL-GMS Internal Coordinates (IC)Using integers for internal representation of Points allows SL-GMS applica-tions to run faster because of the performance advantage of integers overfloating-point numbers. The Internal Coordinate limits range from:

(-2,147,483,648, -2,147,483,648) to (2,147,483,647, 2,147,483,647).

World Coordinates are converted to Internal Coordinates by multiplyingeach World Coordinate by the World Coordinate Scale Factor (WCSC),which is 65,536 by default.

For example, the World Coordinates (55.7, 21.064) are converted to(3,650,355, 1,380,450) for internal use (assuming the default value of65,536 for the World Coordinate Scale Factor). The World CoordinateScale Factor can be changed using the gmsWCScale( ) function.

Normalized Screen Coordinates (NSC)

used for window size and position

0.0 to 1.0 page 8-8

Normalized Window Coordinates (NWC)

specification of the anchor point used to position the window on the display screen

0.0 to 1.0 page 8-10

Device Coordinates (DC->IPC)

Device-dependent specification of Points

platform dependent page 8-3

SL-GMS Internal Coordinates (IC)

SL-GMS-internal use for performance optimization

(-2,147,483,648, -2,147,483,648) to (2,147,483,647, 2,147,483,647)

page 8-2

Coordinate System Use Range Description


Display of Models

Normalized Device Coordinates (NDC) are also converted to Internal Coor-dinates by multiplying each NDC by the Normalized Device CoordinateScale Factor (NDCSF), which is 100 times the WCSF by default. The Nor-malized Device Coordinate Scale Factor can be changed using thegmsNDCScale( ) function.

Device CoordinatesDevice Coordinates are coordinates used by the actual physical displaydevice, and are usually in pixels. SL-GMS automatically maps NormalizedDevice Coordinates to Device Coordinates.

Specifying coordinates to SL-GMF functionsOften in SL-GMF, parallel functions are provided to allow for two approach-es to coordinate specification: as a number or as a Point object. Whennumbers are specified, the user must keep track of which coordinate sys-tem the function call requires, and SL-GMS multiplies the coordinates byone of two scaling factors: the WCSF or the NDCSF. When a Point objectis specified, the Point object must be created using a function such asgmsNPXY( ). Of course, the function which creates the Point expects acertain coordinate system (WC, NDC). However, once the Point is creat-ed, it is comprised of SL-GMS Internal Coordinates (IC) and can be used tospecify equivalent WC and NDC spaces.


Display of Models

Displaying a Model

Graphical Models are defined within a Cartesian World Coordinate System(WCS) with any user-specified scale. World Coordinate Space is centeredat the origin, (0., 0.), and extends both positively and negatively out to lim-its related to the World Coordinate Scale Factor (WCSF) (65,536 bydefault).1 The default WCS limits are (-32,768., -32,768.) to (32,767.,32,767.). World Coordinates are multiplied within SL-GMS by the WorldCoordinate Scale Factor and converted into 32-bit integers for internal rep-resentation.

Figure 8-1: shows a Model with a default size of 72 x 54 WC units, with itslower-left corner at (0., 0.).

Figure 8-1: A Model in World Coordinate space

1. 0x10,000 = 164 = 216 = 65,536

WC-window (WC) (0., 0.) (72., 54.)World Coordinate Space (WC)

(-32.768., -32.768.) (32.767., 32.767.)

Model


Display of Models

ViewsModels are displayed in a View within a window. The View is defined bytwo extents; a World Coordinate (WC) extent, and a Normalized DeviceCoordinates (NDC) extent, as shown in Figure 8-2:.

Figure 8-2: Mapping a Model into a View object

The WC-extent of the View determines the portion of the World Coordinatespace to display. Only those portions of a Model that fit within the View’sWC-extent are displayed. For instance, in Figure 8-2:, the WC-extent of theView is the same as the WC units of the Model, (0.0, 0.0) (72.0, 54.0),therefore, the entire Model is displayed in the View.

Figure 8-3: on page 8-6 illustrates two Views, each displaying the sameModel. In "View1" the WC-extent of the View is the same as the WC-extentof the Model, (0.0, 0.0) (72.0, 54.0), therefore, the entire Model is dis-played in the View. However, in "View2", the WC-extent of the View is only(0.0, 0.0) (36.0, 27.0), therefore, only the portion of the Model whose Points fall with-in that extent are displayed in the View.

Model Extent (WC) (0., 0.) (72., 54.)World Coordinate Space (WC)

(-32.768., -32.768.) (32.767., 32.767.)

Model

View

(0., 0.) (0.72, 0.54) NDC-extent(0., 0.) (72., 54.) WC-extent Normalized

DeviceCoordinateSpace(NDC)

intended to be(0.0, 0.0) to (1.0, 1.0)


Display of Models

Figure 8-3: Two different View WC-extents

The size of the View’s WC-extent is set using the view_wc_extentattribute of the WinModState. The default value of the view_wc_extent is(0.0, 0.0) to (72.0, 54.0).

The View is described by two extents; World Coordinates (WC) and Nor-malized Device Coordinates (NDC). If the NDSCF is 100 times the WCSF,then 100 WC units is equivalent to 1.0 NDC units, and 0 WC units is repre-sented as 0.0 NDC units. The size of the View in NDC is set using theview_ndc_extent attribute of the WinModState, and the default Viewstarts at (0., 0.) and goes to (0.72, 0.54) NDC units. It should be notedthat these coordinates are exactly 1/100 the size of the View’s default WCextent, which runs from (0., 0.) to (72., 54.), because the default NDCSF is100 times the WCSF . When the NDCSF is set to anything other than 100times the WCSF , then the NDC coordinates will not be 1/100 the size ofView’s WC extent, and SL-GMS has to perform an extra transformationwhen the View is displayed.

NOTE: The View’s WC coordinates do not have to correspond to 100times the View’s NDC coordinates; only the aspect ratiosbetween the View’s WC extent and the View’s NDC extent muststay the same.

tank1

tank2

(0., 0.)

(72.0, 54.0)

tank1

tank2

(0., 0.)

(72.0, 54.0)

(36.0, 0.)

tank1

(0., 0.)

(36.0, 27.0)

Model

View1 View2


Display of Models

The aspect ratio, the ratio of width to height, must be exactly the same inthe View’s WC and NDC extents. If the aspect ratio is not the samebetween the View’s WC-extent and the View’s NDC-extent, objects dis-played in this View are scaled unevenly and appear distorted.Thekeep_aspect_flag attribute of the WinModState is set equal to one if theaspect ratio of the View’s WC-extent and the View’s NDC-extent are to bemaintained when the window is resized.

WindowsThe window is positioned, and sized on the display device using differentattributes of the WinModState. Each of the attributes of the WinModStateare further defined in the SL-GMS® State Class Library Reference manual.

Figure 8-4: illustrates the mapping of a Model in World Coordinate spaceinto a View, and then into the window.

Figure 8-4: Mappling of a Model into a window

WC-window (WC) (0., 0.) (72., 54.)World Coordinate Space (WC)

(-32.768., -32.768.) (32.767., 32.767.)

display device (pixels)

windowModel

Model

View(0., 0.) (0.72, 0.54) NDC-e(0., 0.) (72., 54.) WC-exte

Device Coordinate Space (DC)


Display of Models

Specifying the size of the windowThe size of the window is specified using the win_size attributeof the WinModState. The win_size attribute specifies the widthand height of either the window frame and drawing area, or thewindow drawing area by itself, in Normalized ScreenCoordinates. Normalized Screen Coordinates (NSC) are realvalues that range from 0.0 to 1.0, as illustrated in Figure 8-6:.

The following example creates a window, frame not included,which takes 40 percent of the screen width and displays theModel "mymodel". The size of the window should have a 4 to 3aspect ratio, meaning the height should be 3/4 of the width,therefore the window height is 30% of the screen width.

STINVOKE("my_winmodst", G_WINMODSTATE_CLASSNAME,"std_top_backplane","model_name", "mymodel","frame_type", "e","win_size", "0.4 0.3",NULL);

Figure 8-6: illustrates the size of the window (created in theexample above) on the display screen.

Figure 8-5: A "win_size" equal to (0.4, 0.3)

window

1.00.0

Normalizedwin_size equal to (0.4, 0.3)

1.0

NSC

display screen

ScreenCoordinates(NSC)

Model

0.3

0.40.0


Display of Models

If the width and the height of the window are not specified, theWinModState uses the World Coordinates extent of the Viewand the mapping factor to make up the window dimensions.

If the World Coordinates extent is not available, theWinModState gets it by loading the Model and approximatingthe View extent from the Model dimensions.

The mapping_factor attribute specifies the relationshipbetween the World Coordinates used in the Model and theNormalized Screen Coordinates used to position and size theWindow. The mapping_factor indicates the number of WorldCoordinate units that can be displayed along the width of theScreen. The default value for the mapping factor is 100.0. Withthis mapping_factor, a full-screen Window would display aModel with a World Coordinate width of 100.0 units, and a Modelwith the default width of 72.0 WC units would take 72% of thewidth of the screen.

Setting the location of the windowThe win_position attribute of the WinModState defines thelocation on the screen of the window frame corner specified bythe win_position_offset attribute. The win_position location isspecified using Normalized Screen Coordinates (NSC). Thedefault window position is at the lower-left corner of the screen.

The following example creates a window whose lower-left corneris located at the middle of the bottom edge of the screen anddisplays the Model "mymodel".

STINVOKE("my_winmodst", G_WINMODSTATE_CLASSNAME,std_top_backplane","model_name", "mymodel","win_position", "0.5 0.0", "win_position_offset", "0.00.0",NULL);

Figure 8-6: on page 8-10 illustrates the placement of the window(created in the above example) on the display screen.


Display of Models

Figure 8-6: A "win_position" equal to (0.5, 0.0)

Unless specified otherwise, the win_position_offset attributehas for the default value the lower-left corner of the windowframe. At times, it may be necessary to position the window byits upper-left corner or to center the window around a point onthe screen. The win_position_offset is provided for thispurpose.

The win_position_offset attribute specifies an anchor point inthe window. The anchor point is the point by which the window ispositioned on the screen. The point is specified in NormalizedWindow Coordinates. Normalized Window Coordinates (NWC)are real numbers in the range of 0.0 to 1.0, as shown in Figure8-7:.

windowModel

1.00.0 Normalized win_position equal to (0.5, 0.0)

1.0

NSC

display screen

ScreenCoordinates(NSC)


Display of Models

Figure 8-7: Normalized Window Coordinates (NWC)

The x-coordinate of the win_position_offset attribute isspecified as a percentage of the width of the window frameranging from 0.0% (use the value 0.0 for the leftmost edge of thewindow frame) to 100.0% (use the value 1.0 for the rightmostedge of the window frame).

The y-coordinate of the win_position_offset attribute isspecified as a percentage of the height of the window frameranging from 0.0% (use the value 0.0 for the bottom edge of thewindow frame) to 100.0% (use the value 1.0 for the top edge ofthe window frame).

Several examples are shown in Figure 8-8:. The anchor point isrepresented by the black dot.

Model

0.0 1.0

1.0

NormalizedWindowCoordinates(NWC)

window

NWC


Display of Models

Figure 8-8: Some common "win_positin_offset" values

Other common values are:

(0.0, 1.0) = upper-left corner(1.0, 1.0) = upper-right corner(0.5, 1.0) = middle of top edge(1.0, 0.5) = middle of right edge(0.5, 0.0) = middle of bottom edge

The default value is set to (0.0, 0.0) so that the position of thelower-left corner of the window frame is specified by thecoordinates of the win_position attribute.

Setting the name of the ModelThe model_name attribute of the WinModState specifies the name of theModel to display in the View. The model_name attribute is the onlyattribute that needs to be specified. This attribute is enough for the Win-ModState to calculate the size and position of the window and the drawingarea.

Model Model

ModelModel

(0.0, 0.0) (1.0, 0.0)

(0.0, 0.5) (0.5, 0.5)


Display of Models

The following example creates a window and displays the Model"mymodel".

STINVOKE("my_winmodst", G_WINMODSTATE_CLASSNAME,std_top_backplane","model_name", "mymodel",NULL);

Panning and zoomingPanning or zooming over a Model is best conceived as a series ofWC-extents being progressively redefined and mapped successively intothe same View. When panning, the WC-extent remains the same size, butits position is changed. When zooming, the WC-extent changes size.

Panning and zooming is handled by the ViewMgrState. The applicationinvokes an Instance of the ViewMgrState as a substate of the WinMod-State that is displaying the Model. State messages are sent to the View-MgrState to control the zooming and panning. The ViewMgrState sectionof the SL-GMS State Class Library Reference manual describes the variousaction methods that are available to control zooming and panning.

The following example sends the "zoomrect" message to the View-MgrState. The zoomrect method prompts the user to select (using the leftmouse button) the two corners of a rectangle extent. The view_wcextentis then adjusted to the extent defined by the rectangle.

STMSG(viewmgr_statename, "zoomrect", " ");

Externally created windowsModels can also be displayed in a window that is externally created (i.e., ina window that is created by the application and not by SL-GMS). The appli-cation creates the window and then sends the "app_window_handle","app_subwindow_handle", and "model_name" messages to the WinMod-State.

Several examples of creating an external window and displaying a Model init, are described in the SL-GMS Examples Manual. Two of the examplescan be found in the Framework Enhancement on page E-8 and Appendix D— Detailed Analysis: myproject_motif.


9

Version 6.2a- 26 M

Text

Introduction

In SL-GMS, Text is rendered according to its precision, font index withinthat precision and, if appropriate, workstation class. Although most work-station types support only the first two, SL-GMS currently supports threedistinct precisions: 0, 1, and 2. The thirteen fonts of the default precision,precision 0, are the ones used by SL-GMS, if not overridden by a "font-def.dat" entry. See the section, Specifying alternative and additional fontson page 9-5, for a description of usage of the "fontdef.dat" font configura-tion file.

Figure 9-1: shows PostScript printer output for each font index of the thir-teen default precision 0 fonts used by the PostScriptWs layer of SL-GMS.

Figure 9-1: Default Precision 0 SL-GMS Fonts

Font 1: Helvetica Medium Regular

Font 2: Courier Bold Regular

Font 3: Courier Medium Regular

Font 4: Times Medium Regular

Font 5: Courier Medium Oblique

Font 6: Times Bold Regular

Font 7: Helvetica Bold Regular

Font 8: Helvetica Medium Oblique

Font 9: Times Bold Italic

Font 10: Times Medium Italic

Font 11: Helvetica Bold Oblique

Font 12: Courier Bold Oblique

(Font 13: Symbol Medium Regular) αβχδεφγηιϕκλ


Text

A Text object’s precision determines its behavior. The following tablesummarizes the behavior of the three Text precisions.

Text sizing behaviorThe height attribute of a Text object, transformed into device coordinates,determines the font size that SL-GMS will use. The "ink extent height ofthe capital letter ’A’" provides the reference measurement that SL-GMSuses to portably size text.

Precision 1 fonts are completely scalable and behave identically acrossplatforms. Precision 0 fonts are platform dependent and may or may notbe scalable. If the font is not scalable, then SL-GMS must choose amongone or more fixed sizes. The size selected will be the largest size avail-able that is smaller than or equal to the desired size. If the desired size issmaller than the smallest available, the smallest available will be used.

For example, suppose that the non-scalable Courier Bold 20 fontexactly matches the desired height for a label’s text. If the user resizesthe window to half its former height, SL-GMS searches first in the CourierBold family for a font of size 10. If a size 9 is found, but no size 10 isfound, the size Courier Bold 9 font is used.

Text Precisions in SL-GMS

Precision Description

0 This the default precision. It uses workstation-dependent fonts. SL-GMS assumes that the font will not support rotation or separate scaling of X and Y components.

1 This precision uses workstation-independent "Hershey" fonts. All SL-GMS transformations are applied to the text.

2 This precision uses workstation-dependent fonts. All SL-GMS transformations are applied to the text.


Text

Default Fonts

SL-GMS supports many workstation classes and attempts to provide aconsistent font interface across all platforms, graphics packages, and out-put devices. Since it is not possible to guarantee that text will appearexactly the same when applications are moved from workstation to work-station, SL-GMS provides workstation-dependent default definitions for thenon-PostScript workstation types that match as closely as possible with thedefault PostScript fonts.

Figure 9-2: lists the default names for the SL-supported workstation class-es.

Figure 9-2: Default Precision 0 fonts across Workstation classes

Index PostScript X Windows NT

1 Helvetica helvetica-medium-r Arial

2 Courier-Bold courier-bold-r Courier New-Bold

3 Courier courier-medium-r Courier New

4 Times-Roman times-medium-r Times New Roman

5 Courier-Oblique courier-medium-o Courier New-Italic

6 Times-Bold times-bold-r Times New Roman-Bold

7 Helvetica-Bold helvetica-bold-r Arial-Bold

8 Helvetica-Oblique helvetica-medium-o Arial-Italic

9 Times-BoldItalic times-bold-i Times New Roman-Bold-Italic

10 Times-Italic times-medium-i Times New Roman-Italic

11 Helvetica-BoldOblique helvetica-bold-o Arial-Bold-Italic

12 Courier-BoldOblique courier-bold-o Courier New-Bold-Italic

13 Symbol symbol-medium-r Symbol


Text

Precision 1 fontsPrecision 1 text is rendered by SL-GMS using Hershey text fonts. Theyare public domain vector text created by A.V. Hershey and distributed bythe National Bureau of Standards, Report No. NBS SP-424.

SL-GMS provides 18 Hershey fonts1 in the "$GMS_HOME/lib" directory as"*.fnt" files. By default, no precision 1 fonts are operative. To make pre-cision 1 fonts operative, they must be specified in the "fontdef.dat" file. Fig-ure 9-3: shows the set of Hershey fonts with the names as used in the"fontdef.dat".

Figure 9-3: Precision 1 Hershey text fonts

1. The less-than (<), greater-than (>), underscore (_), and bracket ([ ]) characters have been added to the Simple Roman fonts. The underscore character has been added to the Cartographic Roman font.

"fontdef.dat" Names

SimpRom

CompRom

DupRom

CartRom

CompCyr

CompGreek

CompItal

CompScr

GothEng

GothGerm

GothItal

SimpGreek

SimpScr

Symbol1

Symbol2

Symbol3

TripItal


Text

See the section, Specifying alternative and additional fonts on page 9-5 forhow to specify fonts using the "fontdef.dat" file. Figure 9-4: shows anexample of the specification of Hershey fonts in a "fontdef.dat" file.

Specifying alternative and additional fonts

Users of SL-GMS may override the default precision 0 fonts and specifyadditional fonts of any supported precision through the use of a "font-def.dat" file.

SL-GMS reads at most one "fontdef.dat" file, searching first in the currentdirectory, then in directories added via application program calls to thefunction, gmsAddLibPath( ), and finally, in the "$GMS_HOME/lib" directo-ry. The "$GMS_HOME/lib" directory holds a default "fontdef.dat" file, whichspecifies four Hershey fonts used by some SL-provided demos.

The actual format of a "fontdef.dat" entry is platform-dependent, althoughHershey fonts are specified identically across platforms. Refer to the sub-sections below that discuss characteristics of specific workstations.

A sample "fontdef.dat" file defining four precision 1 fonts is shown in Figure9-4:.

Figure 9-4: An example of SL-GMS "fontdef.dat" entries

The following explains the parts of the font specification:

Workstation Class Name allows fonts to be specified differently for differ-ent Workstations; e.g., use "default" for screen and "PostScriptWs" forprinter output.

default hershey 1 SimpRom /* prec 1, index 1 */

Font NameSL-GMS Font IndexFont PrecisionWorkstation Class Name

default hershey 2 CompRom /* prec 1, index 2 */default hershey 3 DupRom /* prec 1, index 3 */default hershey 4 CartRom /* prec 1, index 4 */

Comment


Text

Font Precision specifies a workstation-dependent name that corresponds to precision 0, 1, or 2. This entry is usually "raster" for precision 0, "hershey" for precision 1, and "vector" for precision 2.

Font Index specifies the index within the workstation’s table of fonts for the indicated precision. Thus, index 3 might be separately used for "default raster", "default hershey", and "PostScriptWs".

Font Name specifies the platform-dependent name of the font. Refer to the subsections below that discuss characteristics of specific workstations.

/*Comment*/ specifies comments which can be placed anywhere in theline; they conform to the C programming language style, where commentstrings are enclosed in "/*" and "*/". Any number of comments are allowedin a single line, but a comment may not span more than one line.

The following subsections give the detailed "fontdef.dat" specifications forplatforms supported by SL-GMS.

X Window System

Figure 9-5: Example "fontdef.dat" for the X Window System

Many platforms supported by SL-GMS use the X Window System, whichcontinues to evolve new font technologies with each release. Forinstance, the X Logical Font Description (XLFD) was introduced withRelease 4 of X Version 11. Support for scalable fonts and internationalfont sets were major additions to Release 5.

default raster 11 9x15default raster 12 -linotype-helvetica-medium-r-normal--0-0-0-0-p-iso8859-1default raster 13 -adobe-helvetica-medium-r-normal--*-*-0-0-p-iso8859-1default raster 13 adobe-times



Text

A "fontdef.dat" entry for a precision 0 font may specify either "default" or"XWs" as the Workstation Class Name and must currently specify "raster"for Font Precision.

The Font Name field format depends on whether a single font or a font setis being specified. This section discusses single-font environments; seeXFontSet platforms on page 9-7 for details specific to font set specification.

The XLFD standard, Version 1.4, defines a "well-formed XLFD pattern" asa string containing fourteen (14) hyphens, one of which is the first charac-ter of the pattern.

A Font Name is either a well-formed XLFD pattern or it is not. If it is not,SL-GMS simply prepends and appends asterisk (*) wildcard characters tothe pattern and uses the XListFonts( ) facility to build the list of font namesavailable for that index. Ideally, the list of Font Names varies only by size,because this is how they are sorted and accessed.

If the Font Name field for a particular entry is a well-formed XLFD pattern,no wildcards are added by SL-GMS. User-specified wildcards are pro-cessed by XListFonts( ). Scalable fonts must be explicitly specified usingzeros ("-0-") in the XLFD fields for PIXEL_SIZE, POINT_SIZE, andAVERAGE_WIDTH.

XFontSet platforms

Figure 9-6: Sample "fontdef.dat" for a Japanese Sun Workstation

SL-GMS is now available on a number of platforms which make use of theinternationalization input/output technologies introduced with Release 5 of

XWs raster 1 -adobe-helvetica-medium-r-normal--*-*-*-*-p-*-iso8859-1,\-misc-fixed-mediuum-r-normal--14-130-75-75-c-70-jisx0201.1976-0, \-misc-fixed-medium-r-normal--14-130-75-75-c-140-jisx0208.1983-0

XWs raster 14 -sun-gothic-medium-r-normal--16-140-75-75-c-*-*-0XWs raster 15 -sun-minchou-medium-r-normal--*-*-75-75-c-*-*-0XWs raster 16 -morisawa-gothic medium bbb-medium-r-normal-sans-0-0-0-0-m-0-*-0XWs raster 17 -linotype-helvetica-medium-r-normal--0-0-0-0-p-0-iso8859-1,\

-morisawa-gothic medium bbb-medium-r-normal-sans-0-0-0-0-m-0-*-0XWs raster 18 -linotype-helvetica-medium-r-normal--0-0-0-0-p-0-iso8859-1,\

-morisawa-gothic medium bbb-medium-r-normal-sans-0-0-0-0-m-0-jisx0201.1976-0,\-morisawa-gothic medium bbb-medium-r-normal-sans-0-0-0-0-m-0-jisx0208.1983-0


Text

X Version 11. The XFontSet technology forms the basis of international-ized text output and is also used by the X Input Method (XIM) facilities.

The essential feature of an X font set is that it contains one font for eachcharacter set required to support the current locale. SL-GMS adds therequirement that at least one "ASCII-capable" character set be included(even if not required by the locale) for use by the text-sizing algorithms.The "ink extent height of ’A’" determines the size selected for the"ASCII-capable" font; font sizes for the other character sets are then cho-sen to match as closely as possible.

A "fontdef.dat" entry for font sets consists of one or more comma-separat-ed "well-formed XLFD patterns". Escaped newlines (a backslash "\" fol-lowed immediately by the end-of-line character) may be used ifconvenient. An asterisk (*) wildcard as the first character in the XLFDfield for CHARSET_REGISTRY may enable a single pattern to specify font-set parts for multiple character sets.

The default SL-GMS font sets combine the single-font environment's"iso8859-1" default font with a simple, single-sized locale-dependent fontfor each character set. The sample "fontdef.dat" entry for "XWs raster 1",shown Figure 9-6:, is equivalent to the SL-GMS default for a typical Japa-nese locale requiring fonts for "jisx0201.1976-0" and "jisx0208.1983-0".

Some variation in Xlib’s rendering of ASCII text has been noted acrossplatforms when multiple "ASCII-capable" character sets are active: in somecases the "iso8859-1" font is used; in others the local "ASCII-capable" fontis used. The latter case may call for extensive "fontdef.dat" specification ifASCII text rendering is important.

Earlier localized versions of SL-GMS used locale- and platform-specificproprietary technologies to support localized text output, and by defaultfonts 14 and 15 (Figure 9-6:) were used to display localized text whiledefault fonts of index 1 to 13 were properly used for ASCII only. XFontSetplatforms support display of localized text using any font index, and nodefaults are provided for fonts 14 or 15.

The sample "XWs raster 14" and "XWs raster 15" entries emulate thedefault behavior of SL-GMS under Sun's obsolete Japanese LanguageEnvironment. The sample entries for "XWs raster 16", "XWs raster 17",and "XWs raster 18" illustrate the specification of font sets using scalable(Sun-specific) Japanese fonts. Note that the specifications for indices 17and 18 are equivalent.


Text

Windows NT

Figure 9-7: Example "fontdef.dat" for a Windows NT system

TrueType fonts are supplied with Windows NT. An SL-GMS NT Font Nameis composed of the font family name and an optional list of one or morestyle modifiers separated by the "-" character. Figure 9-7: shows a sample"fontdef.dat" for a Windows NT system.

default raster 1 Times New Romandefault raster 2 Times New Roman-Italicdefault raster 3 Times New Roman-Bolddefault raster 4 Times New Roman-Bold-Italicdefault raster 5 Algeriandefault raster 6 Algerian-Italicdefault raster 7 Courier Newdefault raster 8 Courier New-Italicdefault raster 9 Courier New-Bolddefault raster 10 Courier New-Bold-Italicdefault raster 11 Symboldefault raster 12 Symbol-Bold



Text

The table below lists the TrueType font family names appropriate for usethe "fontdef.dat" file.

The following table lists the set of Font style modifiers.

SL-GMS Font name field entries for Windows NT

Arial

Britannic Bold

Colonna MT

Courier New

Desdemona

Footlight MT Light

Impact

Kino MT

Matura MT Script Capitals

MS LineDraw

MT Extra

Playbill

Symbol

Times New Roman

Wide Latin

Wingdings

Font style modifier

Bold

Italic

Strikeout

Underscore


Text

The font style modifiers are not case-sensitive and may be applied in anyorder to a given font definition.

Figure 9-8: provides an example of an SL-GMS Font Name appropriate toWindows NT.

Figure 9-8: An example of a Windows NT SL-GMS font name

Note that the "fontdef.dat" file employed on a Windows NT system shouldlist only TrueType fonts. Any non-TrueType font listed in "fontdef.dat" willbe replaced with the default SL-GMS font, Arial.

Currently, when specifying TrueType fonts, the "Workstation Class Name"field must be "default" and the "Font Type" field must be "raster"2 for thedefinition to be recognized. The word "raster" specifies precision 0 text.Precision 0 text is implemented using TrueType fonts, not raster fonts.

The gmsTPrec0RotFlag( ) function allows the user to enable or disablerotation for precision 0 (TrueType) text. Refer to the SL-GMS® FunctionReference. The "tprec0_rot_flag" message can also be sent to the Stan-dardTopState to enable or disable rotation for precision 0 text. Refer to theSL-GMS® State Class Library Reference.

Using the fontdef programThe fontdef program is provided with SL-GMS (Windows NTonly) in the work\fonts directory. The fontdef programenumerates all of the installed TrueType fonts on a givensystem. When the output is redirected to a file, it generates afont definition file that contains all available fonts.

2. The term "raster" has been inherited from previous text display solutions and currently does not indicate that the font used is necessarily manifested physically as a true raster (bit map) font.

Times New Roman-Bold-Italic-Strikeout-Underscore

Family Name Style Modifiers


Text

To run the program type:

fontdef [index starting_index]["fonts_to_be_ignored"..] > filename

starting_index = optional number specifying thefirst index to start the list. Ifnone is specified, then 14 is usedas the default.

"fonts_to_be_ignored" = optional list of font familynames, separated with spaces, thatwill be excluded from the generatedoutput file. A font name thatcontains spaces must be enclosed bydouble quotes (e.g., "Arial Black")

For example, to generate a "fontdef.dat" file in the currentdirectory that will start with index 14 and will not include anyArial or Arial Black fonts, type the following:

fontdef index 14 Arial "Arial Black" > fontdef.dat

NOTE: The "fontdef.dat" file created above must be moved either to the$GMS_HOME\lib directory or the working directory for yourapplication.

One of the thirteen default fonts can be overridden by adding anentry for the desired font index to the "fontdef.dat" file.


Text

PostScript Workstation

Figure 9-9: Example "fontdef.dat" for a PostScript workstation

For the PostScript Workstation, the Workstation Class Name field in the"fontdef.dat" file must be specified as "PostScriptWs". The Font Precisionfield must be "raster". Note that the word "raster" specifies precision 0(non-rotatable) text and does not accurately describe the implementation ofprecision 0 text. Precision 0 text is implemented using PostScript and notraster fonts.

PostScriptWs raster 1 HelveticaPostScriptWs raster 2 Helvetica-ObliquePostScriptWs raster 3 Helvetica-BoldPostScriptWs raster 4 CourierPostScriptWs raster 5 Courier-BoldPostScriptWs raster 6 Courier-ObliquePostScriptWs raster 7 Times-RomanPostScriptWs raster 8 Times-BoldPostScriptWs raster 9 Times-BoldItalicPostScriptWs raster 10 Symbol



Text

PostScript output

PostScript output is provided for any of the three types of Text and is usedexclusively on PostScript printers and display devices. SL-GMS translatesText in SL-GMS Model files into the PostScript font that is the nearestmatch to the fonts listed in Appendix A of the PostScript Language Refer-ence Manual from Adobe Systems, Incorporated.

Figure 9-10: and Figure 9-11: show the PostScript font mapping for all fontindex-precision pairs.

Coordinates and ModesFor PostScript itself:

• The standard mode is portrait, with (x, y) = (0, 0) at the lowerleft corner.

• The standard page size is 8 1/2 x 11 inches.

• The standard coordinates are 72 points per inch, which yields amaximum of 612 x 792 points per page.

For SL-GMS: The coordinate ranges to be considered when specifying xand y displacement for Models that are to be output by a PostScript printerare:

• For portrait mode: 0-5400 for x and 0-7200 for y.

• For landscape mode: 0-7200 for x and 0-5400 for y.(Landscape mode is the default for SL-GMS.)

The above ranges are the "nominal" ranges for SL-GMS and provide a uni-form margin of half an inch around the PostScript printout. In the optionsdescribed below in the PostScript Options table, the values of N are to bewithin those ranges.

NOTE: In the PostScript file itself, the coordinate ranges actually usedare in a default range of ten times those numbers with a defaultscale factor of 0.1 for both x and y. This permits takingadvantage of the 300 dots per inch precision of a typicalPostScript printer while using only integers.


Text

Figure 9-10: PostScript output for fonts with precision 0 or 2

Figure 9-11: PostScript output for fonts with precision 1

Font 1: Helvetica Medium Regular

Font 2: Courier Bold Regular

Font 3: Courier Medium Regular

Font 4: Times Medium Regular

Font 5: Courier Medium Oblique

Font 6: Times Bold Regular

Font 7: Helvetica Bold Regular

Font 8: Helvetica Medium Oblique

Font 9: Times Bold Italic

Font 10: Times Medium Italic

Font 11: Helvetica Bold Oblique

Font 12: Courier Bold Oblique

(Font 13: Symbol Medium Regular) αβχδεφγηιϕκλ


Text

Initiating PostScript from an SL-GMS applicationTo print a View (with its Models) from an application, the function gmsPs-ViewWrite( ) should be used (the SL-GMS Function Reference providesinformation about this function). The function gmsPsWsProcArgs( )3 isthe SL-GMS function used to set PostScript options from an application.To print multiple Views, the function gmsPsLViewWrite( ) should be used,in conjunction with the -a option set4 with gmsPsWsProcArgs( ).

For example, the following code fragment could be used to print a Post-Script 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")

For non-C programming languages or situations where the argc-argvmechanism is inconvenient or simply unavailable, the function,gmsPsWsProcArgsStr(argstr), can be used instead of gmsPsWsPro-cArgs( ).

3. All PostScript options are reset before processing the gmsPsWsProcArgs( ) function. This will override any calls to the gmsPsSetParams( ) function, if they are made before the gmsPsWsProcArgs( ) function call.

4. The 0x4 bit of ps_flags can also be set using the gmsPsSetParams( ) function or passing -pf0x4 to the gmsPsWsProcArgs( ) function.


Text

argstr is of type char*, where the character string contains space-separat-ed arguments. Quotes attempting to combine words into one argumentare not accounted for.

For example, the following two calls result in the same print output to aPostScript file with -op, -c, and -s options:

gmPsWsProcArgsStr("-pop -pctest_print -ps50")

is the same as...

gmsPsWsProcArgs(argc, argv)

with:

argc = 3argv[0] = "-pop"argv[1] = "-pctest_print"argv[2] = "-ps50"

Polyline point limitPostScript interpreters vary in terms of the maximum number ofpoints they can process in one polyline. Some can handle only200, most 1500 (the SL-GMS default if not overridden) and somemore. The gmsPsPolyMaxPoints( ) function(refer to theSL-GMS® Function Reference for more information) is providedto inform SL-GMS of the limit for a particular PostScriptinterpreter. Polylines that are larger than the interpreter’s limitare "broken" into smaller segments when printed.

For example, the following code fragment could be used toinform SL-GMS that the printer’s upper limit for the number ofpoints 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";


Text

p_argv[2] = "-pf8";gmsPsWsProcArgs(p_argc, p_argv);gmsPsPolyMaxPoints(200);gmsPsLViewWrite(gmsQEvWorkst(gmsQGismoEvent( )),

views, "test")


10

Version 6.2a- 26 M

Color

Introduction

SL-GMS provides a consistent set of functions for the allocation and man-agement of colors on a variety of platforms. Because color capabilitiesvary depending upon hardware and windowing systems, slightly differentcolor-handling behavior can be expected across platforms.

Every SL-GMS application requires, and allocates, 16 colors per Worksta-tion. SL-GMS processes do not share the system colormap.

Colors are standardized across all platforms. This means that if a "color-def.dat" file is not read by SL-GMS (for whatever reason), the SL-GMSindices 0 through 15 have the same red, green, and blue values, irrespec-tive of the type of SL-GMS Workstation, whether it be X, Windows, or Post-Script.

SL-GMS handles all six of the X visual types (DirectColor, TrueColor,PseudoColor, StaticColor, GreyScale, and StaticGrey). SL-GMS deter-mines the type of visual best suited to its needs, according to a set of inter-nal guidelines plus those given to it in the form of flags(G_WS_LOOKUP_COLORS).

Monochrome displays

On monochrome displays, SL-GMS uses fill styles in place of fill colors.


Color

Changing SL-GMSDraw’s color palette

SL-GMSDraw’s default color palette in the Color Attribute Control Panelcontains 32 colors. The colors are defined in the file "colordef.dat".

The color panel in the Default Graphic Properties window displays 32 col-ors at a time. If more colors are defined in the “colordef.dat” file, the usercan scroll to select a color.

Color definition filesColor definitions can be specified in the "colordef.dat" file distributed in thelib directory. This file associates a color index with the color’s red, green,and blue values and an optional bitplane writemask. The index1 must bean integer between 0 and 231, and the RGB values must be real numbersbetween 0 and 1 (which represent percentages of total saturation). Thebitplane writemask is an integer in either binary or hexadecimal form. Therest of the line is treated as a comment (i.e., it is ignored).

The format for an entry in the "colordef.dat" file is:

<index> <red> <green> <blue> <bitplane_mask>comment

Example0 1 1 1 White1 0.9191 0 0 Red22 0 0.8714 0.2857 SpringGreen33 1 1 0 Yellow4 0.2879 0.4945 0.9067 SteelBlue35 0.593 0 0.6421 Magenta36 0.0541 0.9599 0.9185 Cyan27 0 0 0 Black8 0.7054 0.8031 0.7972 LightCyan39 1 0.6374 0.3474 Tan110 0.6648 1 0.6694 PaleGreen1 /* commando*/

1. The maximum number of colors that can be defined is platform-dependent. Some systems support color indexes, 0 to 27-1; other systems allow 0 to 215-1.


Color

The fifth field can be either a bitplane mask or a comment. If it containsonly the digits 0 and 1, it is taken to be a binary bitplane mask (e.g.,111000000). If it contains only characters drawn from the list ofhexadecimal digits,

0123456789abcdefABCDEFxX,

it is taken to be a hexadecimal bitplane mask. Otherwise, it is treated as acomment ("White" in the example, above).

If a bitplane mask is included in the fifth field, theG_WS_PLANE_MASKING bit needs to be set. The SL-GMS® FunctionReference describes the workstation options.

In addition, if the first non-blank character in a line is not a number, theentire line is treated as a comment.

Comments in the style of C programming language (i.e., strings enclosedin "/*" and "*/") are allowed in the file "colordef.dat". Any number of com-ments are allowed in a single line, but a comment may not span more thanone line.

During its startup sequence, SL-GMS looks for a "colordef.dat" file in thecurrent working directory. If no "colordef.dat" file is found, SL-GMS nextlooks in any directories added to the search path (usinggmsAddLibPath( )). If no "colordef.dat" file is found, SL-GMS uses itsown default "colordef.dat" file located in the lib directory.

The color definitions in SL-GMSDraw cannot be modified from withinSL-GMSDraw. To modify the color definitions, the editor must be exitedand then restarted in a directory with the desired "colordef.dat" file.

Creating a "colordef.dat" fileAn example program, called colordef in the demo directory, can be usedto create a "colordef.dat" file. The "README" file in the colordef directoryprovides instructions for running the program.

NOTE: The "colordef.dat" file is read only once, during initialization. Thismeans that, in order to re-read a "colordef.dat" file that has beenmodified, the application must be restarted.


Color

Using colors above index 31The color panel in the Default Graphic Properties window displays 32 col-ors at a time. A scrollbar appears to the right of the color panel if more than32 colors are defined in the "colordef.dat" file.

PostScript colors

Translation of screen colors to PostScript output is accomplished with the"pscolordef.dat" file. The default "pscolordef.dat" file is distributed in thelib directory and provides a straight mapping of screen colors to PostScriptoutput. A screen color, defined by an index number, can be translated to adifferent color for PostScript output by editing the "pscolordef.dat" file witha standard text editor and changing the RGB entries for the desired screencolor index.

Reverse video

Normally, SL-GMS applications, including SL-GMSDraw, use colors 0 and7 for their background and foreground colors, respectively. Usually color 0is white and color 7 is black. To reverse these two colors (or to choose dif-ferent colors for foreground and background) the colors 0 and 7 must beredefined.

Example0 0.0 0.0 0.0 // black7 1.0 1.0 1.0 // white

Grey-scale

Grey-scaling is accomplished using a special file, "colordef.grey", which isprovided in the lib directory. In order to use "colordef.grey", the file mustbe copied to the current working directory and renamed to "colordef.dat".


Color

AutoCAD colors

The SL-GMS utility dxf2g2 converts AutoCAD ".dxf" (Data Exchange For-mat) files to SL-GMS ".g" (ASCII) Model files. Several options can be add-ed to the dxf2g command line. The -cf option affects color processing.

Colors are processed in one of two ways:

1. When -cf is not specified (default), each AutoCAD color number(1-255) is converted in accordance with the entries 33-167 in"colordef.acad". When SL-GMSDraw is used to display a Modelmade without -cf, the "colordef.dat" file for SL-GMSDraw mustbe a copy of "colordef.acad".

2. Specifying -cf is equivalent to saying, "Only the SL-GMS colorsare available for display; use them in the best way." In thiscase, each AutoCAD color number is converted to an indexbetween 0 and 31, so that the selected color is the "best fit" toone of the standard SL-GMSDraw colors. In this case, the reg-ular SL-GMS 32-color "colordef.dat" file will work satisfactorily.

The file "colordef.acad" distributed in the lib directory contains 168 RGBentries as follows:

2. The section AutoCAD dxf2g ".dxf" file converter on page D-4 provides a complete description of the conversion of ".dxf" files.

Index Contents

0-31 Standard SL-GMS colors

32 White

33-41 AutoCAD colors 1-9

42-51 AutoCAD colors 10-19 and 20-29


...... ...............



Color

If the display hardware is capable of simultaneously displaying the neces-sary number of colors, "colordef.acad" may be set up as the "colordef.dat"file before using SL-GMSDraw to display Models created from ".dxf" fileswith the commands:

UNIX systems:

cd <$GMS_HOME>/lib

mv colordef.dat colordef.hold

cp colordef.acad colordef.dat

Windows systems:

cd <$GMS_HOME>/lib

rename colordef.dat colordef.hold

copy colordef.acad colordef.dat

NOTE: In VAX/VMS systems, the preferred editor is SL-DRAW2. TheSL-GMSDraw editor is not available on VAX/VMS systems.

VAX/VMS systems:

set default gms$home:[lib]

rename colordef.dat colordef.hold

copy colordef.acad colordef.dat

These steps would be necessary only when the -cf option is not exercised,in which case SL-GMSDraw will need the extra colors.

If the regular 32-color SL-GMS "colordef.dat" file is retained and an attemptis made to display a Model converted without the -cf option set, it is proba-ble that no display will occur at all.

162-167 AutoCAD colors 250-255

Index Contents


Color

Common Desktop Environment (CDE) colors

A "colordef.cde" file, included in the lib directory, enables SL-GMS applica-tions to share colors with the Common Desktop Environment(CDE). TheRGB values defined in the "colordef.cde" file match the sixteen static col-ors used by the CDE.

In order to share colors with the CDE, rename the "colordef.cde" file in thelib directory to "colordef.dat". In addition, the G_WS_LOOKUP_COLORSoption must be enabled in an application in order to have SL-GMS sharecolors with the CDE. Add the following call to the application:

gmsWsDefaultOpts(G_WS_LOOKUP_COLORS);

Additional information about the gmsWsDefaultOpts( ) function, and theG_WS_LOOKUP_COLORS option is provided in the section Worksta-tion/Window — object in SL-GMS Function Reference.


11

Version 6.2a- 26 M

Performance

Introduction

The display and monitoring of application system activity often requiresvery critical timing constraints. To meet these constraints the developermust optimize all aspects of data collection, processing, and display.SL-GMS provides a number of services that assist the developer toachieve exceptionally high performance in loading, displaying, and updat-ing graphical screen displays. Some of these services are described inthis chapter, along with advice on additional user and developer strategiesthat can be implemented to optimize the application of SL-GMS.

Optimization techniques are divided into those appropriate for users ofSL-GMS tools and those appropriate for programmers who are extendingthe tools for custom applications. Performance issues important to usersinvolve Model creation using SL-GMSDraw and file usage. Issues impor-tant to programmers involve the optimum definition of variables, optimizingdynamic Model elements, developer-defined functions, and, generally,reduction of unnecessary calculations and displays.

Optimization by users

Model creationSignificant performance improvement can be achieved if SubModels arecreated with the exact size and orientation required in the top-level Mod-el. Run-time execution is saved because the top-level Model avoids theapplication of scaling and rotation transformations on its SubModels.Thus, SubModel objects such as Rectangles, Circles, and Arcs that are thecorrect scale will display faster in the top-level Model. Similarly, eachrotation of a SubModel adds overhead time because a rotation matrix mustbe applied to the SubModel for each distinct orientation.

Since SubModels are incorporated (instanced) many times in varioustop-level Models, a very large return in performance is achieved by con-centrating effort on optimizing performance of SubModels.


Performance

It is recommended that the Apply Transform option of the ObjectPull-Down Menu in SL-GMSDraw or the xtran command in SL-GML beused after building Models that are to be loaded as SubModels at run time.This combines transformations accumulated during editing and appliesthem to the Points defining graphical objects.

The Apply Transform advantage is limited in its application, however, dueto the way certain objects are defined. The Apply Transform has noeffect in the following cases:

• Unequal scaling of Text, Text Rectangles, Circles, Pies, Sectors,and Three-point Sectors

• Rotation of Rectangles

In these cases, whenever possible, try to construct the object so that theApply Transform operation can be used. For example, if a rectangle is tobe rotated, create the rectangle as a closed polygon with four points.

File usageSL-GMS screen Models are typically stored in a standard binary "<model-name>.m1" file by the M1 filer. In many cases the standard ASCII ("<mod-elname>.g") form is used for device-independent archival purposes andsuch uses as text-based editing. The faster ".m1" form is typically used atrun time in customer applications. The binary "<modelname>.m1" file wasdesigned for use with SL-GMS development tools such as the SL-GMS-Draw Graphical Editor and SL-GML Command Language. In the ".m1" fileeach graphical element is stored as a separate entity; therefore, parsingand reconstruction must be done as the file is read into memory.

To achieve maximum possible screen-load performance of a top-levelModel at run time, the M2 or contiguous filer is provided. The M2 filer pro-duces a "<modelname>.m2" file in which screen-Model information isstored as an exact memory image of its internal form. Using the M2 filer,the entire screen-Model input is accomplished in one quick read, ratherthan parsed and reconnected as it is with the normal ".m1" filer. A goodpractice is to free ".m2" Models when no longer needed to make best useof time and memory.

The following table shows a comparison of load times between the M1 filerand the M2 filer for top-level Models with and without SubModels.


Performance

Invoking the M2 filerThe M2 filer provides a set of functions parallel to those provided for theM1 filer. The functions to load and save ".m2" Models are gmsM2Get( )and gmsM2Save( ). They are documented in the SL-GMS® Function Ref-erence. The corresponding SL-GML commands to load and save ".m2"Models are m2get and m2save. They are listed in the chapter SL-GMLReference of the SL-GMS Quick Reference. Information about converting".m2" files to other formats is provided in Appendix D.

With ".m1" files, the format of the information stored is independent of theinternal memory representation when read in. This allows the internalstructure of SL-GMS objects to change (for optimization, rework, and soon) with no effect on the external file representation.

The ".m2" format, on the other hand, is basically a memory image of theModel object. Even a minor internal change to the object data structuresmakes the Models saved using the ".m2" format obsolete.

NOTE: SL Corporation does not guarantee the upward-compatibility of".m2" files. Either an ".m1" or ".g" (preferred) version of allModels must be maintained for upward compatibility.

M1 FILER vs. M2 FILERPERFORMANCE COMPARISON: Model Loading Times for Sun Sparc 2 System

FILES: Top-level Models with and without SubModels

Top-level Model Pathname Sub-

Model Count

M1 Filer M2 Filer

(ms) (ms)

I. Loading Models with no SubModels:

$GMS_HOME/demo/zoompan/zpmap3 0 252.45 72.60

$GMS_HOME/demo/network/SUBMODS/usa_map 0 136.30 24.84

$GMS_HOME/demo/gmsdemo/netmanage 0 245.26 54.60

II. Loading Models with SubModels:

$GMS_HOME/demo/graphs/xcustom 2 180.79 109.13

$GMS_HOME/demo/minidraw/topmenu 22 169.43 131.43

$GMS_HOME/demo/draw2/topmenu 51 347.90 231.71


Performance

Once read in, there is almost no difference in the internal memory used byModels read from ".m1" or ".m2" files. The ".m2" form uses slightly lessinternal memory because "<modelname>.m2" is really one allocatedchunk, rather than an aggregation of pieces, allocated with the malloc( ) C function. The Models are identical in every other way once read in fromeither type of file.

NOTE: Currently, SL-GMSDraw operates only on ".m1" files. An ".m1"file must be converted to ".m2" format using the m1m2 shellscript.

The State Management System (SL-SMS) always tries to load an ".m2" file.By default, a Model search is performed on each directory specified bygmsAddLibPath( ), searching first for ".m2" files and then ".m1" files beforemoving to the next directory. The function gmsStM2Flag( ) may be used tochange the Model search behavior for a given State.

Double bufferingThere are two types of double buffering available with SL-GMS:full-window and individual-object. Full-windowed double buffering

requires programmatic changes. Individual-object double buffering is pro-vided to allow users to selectively double buffer only a portion of a Work-station/Window for performance reasons. This type of double buffering isdone in SL-GMSDraw, when the objects are created, by selecting double-buffer in the Object Flags window of SL-GMSDraw for the object to be dou-ble buffered. The Object Flags window is displayed by selecting the Flagsoption in the Properties submenu of the Object Pull-Down Menu.

The speed of a double-buffered redraw is proportional to the number of pix-els to be transferred to the screen within the rectangular double-bufferedregion. By double buffering only the objects that exhibit annoying flash-ing, the area to be double buffered is reduced and the Model can be ani-mated smoothly and in the fastest manner.

Object substitutionIn many cases additional performance can be achieved by substitutingfaster-displaying objects for slower. For example, on X workstations, wideLines in a Model can be replaced with an equivalent long, thin, filled Rect-


Performance

angle. In those cases where wide Lines have been included in the Model,the long, thin Rectangles display faster than wide lines.

Optimization by programmers

Definition of variablesProgrammers know that the choice of variables and how they are struc-tured affect efficiency of memory usage and speed of execution. In choos-ing variable definition types, the following should be considered specificallyin relation to SL-GMS.

Array variablesPerformance can be improved by the use of array variables.Many of the standard SL-GMS GISMO Action Functions, suchas gms_radio_array( ), gms_toggle_array( ), andgms_textload_array( ), operate on array variables to load aGroup of Text objects very quickly, as an array of text strings.The SL-GMS GISMO Action Functions are examples ofuser-defined actions.

More information is provided in the section Dynamics driven byarray variables on page 3-52.

Scoping VariableIn general, try to limit the use of variables to the screen state inwhich they are used. The use of State variable definitionsdecreases the time to define and create variables becauseSL-GMS collects VarDefs into their own State variable definitiontable. Since the hash tables are smaller, variable definitions,dynamic initialization of Models, and variable updates are faster.Performance is also enhanced if the application is using thedesign approach where each Model is freed when it is not beingdisplayed. Rather than removing the VarDef links beforefreeing the Model, gmsStFreeAllVarDefs( ) can be called tosimply throw away all the variables associated with that Model.Any remaining Models do not have to be re-linked to a variablelist because they are linked to their own local variables.

Developer-maintained Variable Definition tables


Performance

The following functions allow variables to be defined anddesignated as changed without having to do look-ups in thehash tables.

Defining a variable without placing it in a hash table:

vardef = gmsVarDefineNoTable(varname, varaddr,vartype, count, size);

To mark (for update) all objects that refer to a variable:

gmsVarDefChanged(vardef);

As with the gmsVarChanged( ) call, the actual update is notperformed until the gmsDynUpdate( ) and gmsUpdate( ) callsare made.

The gmsVarDefineNoTable( ) function must be used inconjunction with gmsVarInitFctn( ). Since no look-up tables arecreated, the user can no longer search for a variable by its nameor address. Therefore, the VarDef objects must be maintainedby the user and gmsVarDefChanged( ) must be used toindicate when a variable has changed. These functions require abit more programming to maintain the VarDef objects, butincrease performance for dynamic initialization and dynamicupdate.

In many cases, the simplest SL-GMS design (all the variablesdefined as global) performs quite well. Applications which have alarge number of variables, or need to scope variables, can usethe State variable-definition approach or a combination ofglobally- and State-defined variables. In cases where there arestrict performance requirements, or where the application designfacilitates the maintenance of the VarDef objects,gmsVarDefineNoTable( ) and/or gmsVarDefChanged( ) maybe used.


Performance

Developer-maintained Variable Definition tables attached to ModelsVariable Definition Tables support limited forms of dynamics innon-replicated SubModels.1 Variable Definition Tables mayalso be used as an alternative to State Variable Definitions orRenamed Variables.

Variable Definition Tables are generally used in these types ofapplications:

• applications which must use dynamic descriptions innon-replicated SubModels

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

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

The function gmsModDynInitVarDefTable( ) must be used ona non-replicated SubModel if that SubModel contains dynamicsdescriptions. The function gmsDynInit( ) does not workcorrectly in this situation. Only limited forms of dynamicsdescriptions work correctly on a non-replicated SubModel, evenwhen Variable Definition Tables are used. A description ofthese limitations is provided in the section SuppressingSubModel replication on page 11-15.

Applications having a strong correlation between data-drivingstructures and Model Instances may use Variable DefinitionTables as an alternative to State Variable Definitions (createdthrough gmsStVarDefine( )).

The Variable Definition names in a Variable Definition Table arelocal in scope to a single top-level Model or Model Instance. Ifan application uses a separate structure to contain the datadriving the dynamics in each Model Instance in a top-levelModel, Variable Definition Tables provide a convenient

1. The section Suppressing SubModel replication on page 11-15 provides further information about non-replicated SubModels and the dynamics associated with them.


Performance

mechanism for binding the data in those structures to the ModelInstances. Renamed Variables are not needed in the ModelInstances because the names in each Variable Definition Tableare local in scope to each Model Instance.

A Variable Definition Table can also be used on a top-levelModel without interfering with any Variable Definition Tables onModel Instances in that Model. Variable Definition Tablesshould not be used on Model Instances contained in SubModels.

The function gmsModDynInitVarDefTable( ) initializes thedynamic descriptions of all parts in the given Model. It alsocreates and stores a Variable Definition Table in the Model. Ifthe Model already contains a Variable Definition Table, thattable will be destroyed.

The Variable Definitions in the Variable Definition Table arereferenced only by Variable References contained in the Model.Unlike Variable Definitions in global or State tables, VariableDefinitions in a Variable Definition Table contained in a Modelcannot be used by any other Model.

The gmsModDynInitVarDefTable( ) function can be used toinitialize dynamics descriptions on SubModels prior to theirreplication. If this is done, there is no need to perform theinitialization on the replicates. When a SubModel is replicated,its Variable Definition Table is also replicated.

Once gmsModDynInitVarDefTable( ) has been called on atop-level Model, any gmsDynInit( ) call on that Model has noeffect. The presence of a Variable Definition Table in a top-levelModel blocks the effect of gmsDynInit( ) on that Model.

Once gmsModDynInitVarDefTable( ) has been called on aSubModel, any gmsDynInit( ) call on parents of that SubModelhas no effect on the SubModel.

The blocking effect is local; SubModels which do not contain aVariable Definition Table are processed normally bygmsDynInit( ) calls on parents of the SubModel.


Performance

Optimized dynamicsOptimized dynamics allow an application to set internal global flags thatimprove the object-updating performance of DynProps. By this techniquean application can significantly streamline the dynamic update and displayprocess.

However, if only a small percentage of the total number of objects is to bechanged between updates, usage of optimized dynamics can be slowerthan using regular dynamics.

Certain functions control SL-GMS internal flags that are used to implementoptimized dynamic Model features. Some of these functions control theuse of optimized dynamics, while others affect the way that the update anddisplay processes occur. The syntax for the functions and more detailabout the use of these functions is described in the Dynamics — optimiza-tion section in the SL-GMS Function Reference.


Performance

The following table lists use of these functions.

Optimizing DynProps with developer-defined functionsThe dynamic descriptions which are contained in a DynProp that is storedon an SL-GMS Graphical primitive are stored both externally in ".m1" or".m2" files and internally in run-time memory. These descriptions are a setof objects which are interpreted at run time. The external dynamic string

Function Calls Used with Optimized Dynamics

Function Call Description

gmsAutoUpdateMode(G_ON) cause gmsDynUpdate(nil) and gmsUpdate(nil) to be done after each Event is processed in gmsMainLoop( )(default: G_ON)

gmsAllVarsChanged( ) indicate that all variables have changed between each update

gmsUseShadowMode(G_OFF) disable use of Shadow to erase objects when attributes are changed; appropriate only if the application never needs erasure, uses double buffering, or clears and redraws screens with each update(default: G_OFF)

gmsExtentMode(G_OFF) disable extent calculation on objects that are not detectable; this makes the update pass quicker, but disables clipping (default: G_ON)

gmsNoFlagsMode(G_ON) disable setting of internal display flags used by SL-GMS during update pass(default: G_OFF)

gmsDynUpdArrayFlag(obj,G_ON) sets an object’s dynarray flag used by SL-GMS to optimize dynamics for objects which reference array values. (default: G_OFF)


Performance

form is used only when creating and editing the dynamic description in aSL-GMS Drawing Editor or when storing it in the SL-GML ".g" ASCII form.

The interpretation of the dynamic string is quite fast and generally introduc-es very little overhead into a properly constructed screen. However, anyfunctionality of a dynamic description that can be shifted to the time whenthe object is compiled, linked, or loaded, saves real-time execution andspeeds up operation of the model. Thus, the performance of dynamicModels that involve many instances of expression handling, conditionaldynamic descriptions, or actions can be improved significantly by creatingspecial optimization functions. Such functions are invoked using the callaction within the dynamic description. The resulting optimization providesthe following performance advantages:

• smaller ".m1" and ".m2" Model files

• faster retrieval of these files at run time

• faster interpretation of the dynamics during thegmsDynUpdate( ) phase

For example, a standard conditional dynamics specification might be:

x= 0

tcolor 5bcolor 4ecolor 1

x= 1

tcolor 4bcolor 3ecolor 0

and can be simplified to:

x= 0

call user_set_color(__self, 5, 4, 1)x

= 1call user_set_color(__self, 4, 3, 0)


Performance

where the user_set_color( ) function looks like:

intuser_set_color (object, tc, bc, ec)

id object;int tc, bc, ec;

{gmsTColor(object, tc);gmsBColor(object, bc);gmsEColor(object, ec);return 1;

}

The above conditional DynProp can be optimized even further by providinga function to do everything, including the conditional comparison:

*call user_set_hilite(__self, x)

where the user_set_hilite( ) function looks like:

intuser_set_hilite(object,variable)

id object;int variable;

{switch (variable) {

case 0:gmsTColor(object, 5);gmsBColor(object, 4);gmsEColor(object, 1);break;

case 1:gmsTColor(object, 4);gmsBColor(object, 3);gmsEColor(object, 0);break;

default:break;


Performance

}return 1;

}

The user_set_hilite( ) function checks x and makes the appropriate calls tohighlight or unhighlight the object, _self.

The example highlighting function above is invoked from an unconditionalaction list — essential for achieving maximum possible performance. Lessinformation is read from the file and the execution is done in a compiledfunction, rather than interpreted.

User-defined functions are further described in the section User-definedfunctions on page 3-35.

NOTE: These user-defined functions are needed only to achievemaximum performance. In most cases, the normal DynPropinterpretation is sufficiently fast, especially when used inconjunction with Array Dynamics.

Structuring DynProps for optimizationDynProps for objects are created using a SL-GMS Drawing Editor. Thevalues used to drive dynamic actions are calculated by the application pro-gram. Optimized dynamics are created only for DynProps that use directactions without expressions or interpolations. Direct actions uncondition-ally occur every time SL-GMS performs an update. Expressions are anarithmetic or logical operation surrounded by parentheses that are permit-ted in ordinary dynamic descriptions.

The following is an example of a direct dynamic description that can beconverted to optimized dynamics:

*rotate anglefcolor fcol_1

Conditional dynamics that cannot be converted:

angle_2= -30.:-90.

rotate angle_2


Performance

fcol_2= -30:-90

fcolor 1:6

Direct dynamics with an expression that cannot be converted:

*rotate (angle_1 * 3.14159)

Variables must be defined with gmsVarDefine( ) before the gmsDynInit( )function is called. The type of the variable as defined by gmsVarDefine( )must match the type of action as defined in the section Dynamic actions ofthe SL-GMS Quick Reference. If the variable type, as defined by gmsVarDefine( ), does not match the type of variable for the action, thedynamic description silently fails to be converted into an optimized dynamicdescription.

Disabling use of Shadow objectsEach time a change is made to an object that requires the object’s erasure,a Shadow object is created. A Shadow object represents an object’spre-change position and is used to erase the object. The use of Shadowsis transparent to the application.

In applications where the entire View is cleared and redrawn with eachupdate, for example, when double buffering is used, the creation of Shad-ow objects introduces unnecessary overhead. Calling the gmsUseShad-owMode( ) function with G_OFF prevents the creation of Shadowsthroughout SL-GMS.

Disabling calculation of extentsEach time an object is transformed, a new extent for the object must becalculated. The extent is used to determine whether the entire objectappears in the View, or if part of the object must be clipped. (Most graph-ics windowing systems clip objects that would otherwise be drawn outsideof the window.) The extent is also used to determine which object is thetarget of Locator (mouse) input by the gmsFindObject( ) function.

Calling the gmsExtentMode( ) function with G_OFF prevents the calcula-tion of extents for non-detectable objects only. If moving objects in Vieware made non-detectable, moving these objects does not cause new


Performance

extents to be calculated when this function is called with G_ON. Eliminat-ing calculation of extents results in quicker update and display passes, ifmany objects have extents that are changing.

Font pre-loadingTo minimize raster text overhead during the first display of a Model, it isimportant that the correct raster fonts be pre-loaded into SL-GMS.

In general, applications linked with packages other than X automaticallyhave text fonts pre-loaded by SL-GMS. In SL-GMS applications linked withX, a font is not loaded until the first time it is used.

Suppressing SubModel replicationSubModels are replicated by Model Instances which reference them. Ifeach Model Instance does not have a unique replicate of the template Sub-Model, modifications to the appearance of the SubModel by one ModelInstance will affect the appearance of all other Model Instances referencingthat SubModel.

The functions gmsSubModReplicateMode( ) and gmsModNonRepli-cate( ) control the replication behavior of a SubModel.

The function gmsModNonReplicate( ) sets or clears the non-replicationflag on a SubModel. By default, this flag is not set on a SubModel when itis created. When the flag is not set on a SubModel, the SubModel's repli-cation behavior is defined by the global flag set by the function gmsSub-ModReplicateMode( ). When the non-replication flag is set on aSubModel, the global flag is overridden and the SubModel is not replicatedby a Model Instance.

Usually, the non-replicated flag is set only on SubModels having no anima-tion or dynamics. Since the SubModel is never modified, Model Instancesreferencing that SubModel do not conflict with one another.

Non-replicated SubModels can be used with dynamics in limited circum-stances. Further information about these limitations is provided in the sec-tion Dynamics in Non-Replicated SubModels on page 11-16.


Performance

Non-replicated SubModels have the following advantages:

• less memory is consumed, since the SubModel has no replicates

• top-level Models with Model Instances referencing anon-replicated SubModel are initialized more quickly, since theModel Instances do not have to replicate the SubModel

Currently, the status of the non-replication flag on a SubModel cannot besaved in a ".m1" or ".g" file. This means the non-replication flag must beset at run time. In order to set the non-replication flag at run time, the Sub-Model must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ).

To gain full control over the replication behavior of SubModels, the applica-tion 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);

Dynamics in Non-Replicated SubModelsModel Instances referencing a non-replicated SubModel mustshare a single copy of this SubModel in memory. Because ofthis, certain types of animation do not function correctly innon-replicated SubModels. It is not possible for a part within anon-replicated SubModel to erase itself directly. However, it ispossible for a part to be erased indirectly by using a backgroundRectangle with a redraw action.

The following types of dynamics actions cause erasure:

• transformations: move, scale, rotate, and so on

• visibility: vis, vispart

• edge styles and widths: estyle, ewidth

• fill interior: finter


Performance

• fill style: fstyle

• on Polygons only, fill direction: fdir. The fdir action workscorrectly on Rectangles, which do not perform erasure.

• on Polygons only, fill percent: fpercent. The fpercent actionworks correctly on Rectangles, which do not performerasure.

• on Text only, text attributes: stext, talign, tfont, theight,tpath, and tprec. These work correctly in Text Rectangles,which do not perform erasure.

If these dynamics actions are applied to a part in anon-replicated SubModel, the part should be marked noerase toprevent any possibility of erasure. Background Rectangles withredraw actions can be used to simulate erasure.

In a replicated SubModel, SL-GMS uses object-specific flags to mark those objects which must be redrawn. In anon-replicated SubModel, this is not possible. Because of this, any part in a non-replicated SubModel which is animatedmust be explicitly forced to be redrawn using a redraw action.For example, submodel1 contains a Text Rectangle with thefollowing dynamics description:

*

fcolor fcolor_var

stext stext_var "%d"

If submodel1 were to be used as a non-replicated SubModel, this dynam-ics description would have to be modified to include a redraw action:

*

fcolor fcolor_var

stext stext_var "%d"

redraw


Performance

The following information should be noted for non-replicated SubModels:

• animated objects in a non-replicated SubModel should not bedetectable.

• input dynamics (those specified with the "#" symbol) cannot beused in non-replicated SubModels.

• GraphTrace objects cannot be used in non-replicatedSubModels; if a single non-replicated GraphTrace is sharedamong several Model Instances, the Model Instances willconflict with one another as they attempt to store data in theGraphTrace through the plotdata action

• software double buffering does not work correctly on individualparts within a non-replicated SubModel; the dbflag should notbe set on these objects.

• only unconditional dynamics actions can be used within anon-replicated SubModel.

• replicated SubModels evaluate their dynamics descriptionsduring the execution of gmsDynUpdate( ), non-replicatedSubModels defer the evaluation of dynamics descriptions untilgmsUpdate( ) is executed.

Freeing unused SubModelsThe function gmsModPermanent( ) is used to set or clear the permanentflag on a Model. By default, this flag is not set on a Model when it is creat-ed. The permanent flag affects only the behavior of Models which areSubModels. When the permanent flag is not set, a SubModel is freedwhen the last Model Instance referencing that SubModel is freed. This isdone to prevent accumulation of SubModels in memory.

Setting the permanent flag on a SubModel may improve performance.When the last Model Instance referencing a given SubModel is freed, thatSubModel is freed. If another Model Instance is loaded or created and itreferences the same SubModel (by name), the SubModel must be reloadedfrom disk. When the permanent flag is set, performance is improved byretaining the SubModel in memory, instead of reloading the SubModel fromdisk.


Performance

The permanent flag is typically set on a SubModel which is instanced inseveral top-level Models. This can decrease the amount of time needed toload a top-level Model because the SubModel will already be in memory.

If the permanent flag is set on a SubModel, the SubModel can be freedonly by explicitly calling gmsObjFree( ). The SubModel is not automatical-ly freed when the last Model Instance referencing that SubModel is freed.

Currently, the status of the permanent flag on a SubModel cannot besaved in a ".m1" or ".g" file. This means that the permanent flag must beset at run time. In order to set the permanent flag at run time, the Sub-Model 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);

SubModel cacheUsing a SubModel cache can improve the performance of an applicationwhich repeatedly creates and frees several Model Instances which refer tothe same SubModel. The overhead required to replicate the SubModel andfree the replicates is reduced. However, the application may consumemore memory, since the replicates are no longer automatically freed withthe 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 theseattributes at run time, the SubModel must be pre-loaded usinggmsMXGet( ) or gmsM2XGet( ):

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

A SubModel cache is automatically destroyed when the original SubModel(the template for the replicates) is freed. The functiongmsModPermanent( ) must be used to prevent submodel1 from being


Performance

automatically freed when the last Model Instance referencing submodel1is freed:

gmsModPermanent(submodel1, G_ON);

The function gmsModCacheCapacity( ) is then called to set the capacityof the SubModel cache to a number smaller than or equal to the maximumnumber of replicates predicted to exist in memory. This number can bedetermined by computing or estimating the number of Model Instanceswhich will be referencing submodel1 at the same time. The closer thecache capacity is to the actual number of replicates which will exist inmemory, the greater the optimization. In this example, it has been deter-mined that no more than 100 Model Instances will reference submodel1 atthe same time:

gmsModCacheCapacity(submodel1, 100);

SubModel replication can be either batched or incremental. To batch SubModel replication, gmsModCacheCount( ) is called immedi-ately after the gmsModCacheCapacity( ) call. This call will create 100replicates of submodel1 and store them in the cache:

gmsModCacheCount(submodel1, 100);

To perform incremental SubModel replication, the application omits thegmsModCacheCount( ) call. As Model Instances referencing submodel1are created or loaded from disk, replicates of submodel1 are created. Thecount of the SubModel cache will increase, but will never exceed thecapacity. If the number of replicates needed is less than the capacity, thecount will remain smaller than the capacity.


12

Version 6.2a- 26 M

The Graphical Modeling Language

Introduction

SL-GML permits quick access to all libgms functions. As a complement toSL-GMSDraw, it is equally flexible in creating screens from Graphical Prim-itives and is sometimes indispensable for refining graphical Models, usinga simple graphical description language. SL-GML interprets commandsread from a file or entered at a keyboard.1

Figure 12-1: The SL-GML interpreter displaying the Model "cogen"

1. The chapter SL-GML Reference of the SL-GMS Quick Reference provides a further description of the valid commands and usage for a ".g" file.

<gms> gml ready> model get cogen

73.5546.9

10.0731.6

52.9519.0

28.6946.4

42.6493.8

70.2550.0

446.3880.4 0.658.9

273.0983.0360.8

81.785.528.9

998.5

8.8

63.7

966.7

III P4 P3IV

I II P1 P2

11Cogeneration Monitoring System

MWHeat loss

OutputPower

Exchng

Input

N/Hr

Pressure kg/cm

Reading %R Values

1 2 3 4 5 6

%%%

682.5Elec Power

Generator29.85

ReservePump

724.7

Energy Flow Temp

N/Hr lit/mn ’F

Steam

Primary

Return

Heat TransferPrimarySecondaryExchangerReserve

PowerOutputDemandChange

CapacitiesPowerTransferReserve

Energy

N/Hr

Flow

lit/mn

Temp

’F

lit/min

ReserveFlow

ReserveCap

927.7200.0 900.2 129.0

418.1 581.3 78.0143.9

lit/mnTemp

’F

Return

Cycle

764.1

<gms> gml ready> immu<gms> gml ready> _

SL-GMS



In general, SL-GMSDraw is used for editing Model files. However, thereare occasions when it is easier to convert a Model file to an SL-GMLcommand file and use an editor on the command file; for example, tochange a text string that appears in many places in a Model, or to changethe color red to the color green wherever it occurs. Those are instanceswhen making global changes with an editor is easier than editing theModels using a SL-GMS drawing editor.

Once the command files have been changed, they must be reconverted toModel files using SL-GML. When errors are encountered while readingthe command file with SL-GML, the line number where the error occurred isdisplayed.

It is usually advisable to give the command file the same name as that ofthe Model it contains. The name of the command file has no effect on thename of the Model that is saved, rather the name that precedes the modelcommand in the command file determines the name of the Model.



Example1. The following Model containing a single Filled Circle is created

in SL-GMSDraw:

2. The Save As option of the File Pull-Down Menu is selected andthe Model is named "testmod.m1".

3. Click the File Pull-Down Menu and select the GML Script optionof the Export submenu.



4. The ASCII file "testmod.g"2 can then be edited with a standard text editor:

mtran0vis 1detect 1testmod: modelfcolor 4fstyle 1finter 1fdir 0fpercent 100ecolor 7estyle 1ewidth 1fcir2 50 37.5 50 45.5endm

5. The Model can be examined or changed using the SL-GML inter-face by starting SL-GML as described in the section SL-GMLcommand-line options of the SL-GMS Quick Reference and typ-ing the following command at the <gml_ready> prompt:3

2. All coordinates in a ".g" file have a maximum of four significant digits after the decimal point. (fcir2 50 37.5 50 45.5) will be saved as (fcir2 50. 37.5 50. 45.5).

3. If the Model was saved in binary format, it can be loaded directly using the model get command.

<gml_ready> < testmod.g



6. The Model can then be displayed by entering

Converting Model files

SL-GML provides the portability medium for SL-GMS Models. SL-GMLsaves Model files in ".g" format and can convert ".g" files back to ".m1"(binary) files. SL-GML command files (".g" files) can always be transport-ed between different computers.

Steps to Port a Model File Between Different Computers Using SL-GML

Functional Description Steps

Start-up SL-GML on the source computer

1. Invoke SL-GML per the Installation Notes on the source computer

Read in the binary version of the Model

2. Entermodel get modelname

Write out the ASCII version of the Model to a file

3. Entermodelname gsaveThe "modelname.g" command file is created.

Exit SL-GML 4. Enterquit

<gml_ready> update



NOTE: Converting Graph Models to ".g" format causes comments in theGraph template (".g" file) to be lost when the conversion is made.

The m1g and gm1 scripts distributed in the bin directory perform the bina-ry-to-ASCII and ASCII-to-binary conversions described above for a singleor multiple Models.

Transfer the SL-GML command files from the source computer to the destination computer

5. Use the appropriate system command(s) to copy or move the ".g" files from the source to the destination computer

Start-up SL-GML on the destination computer

6. Invoke SL-GML per Installation Notes on the destination computer

Read in the ASCII version of the Model

7. Enter<modelname.gThe "less-than" sign (<) tells SL-GML to read commands from the file that follows. The full file name must be entered, including the ".g" suffix.

Write out the binary version of the Model to a file

8. Entermodelname saveThe "modelname.m1" file is created.

Exit SL-GML 9. Enterquit

Steps to Port a Model File Between Different Computers Using SL-GML

(continued)

Functional Description Steps



Projects

A Project is a collection of Views and their Models. Before SL-SMSevolved, Projects were used when multiple Views and Models were to bedisplayed in the same Workstation/Window. Although Projects can still beused to build an application without programming, it is recommended thatSL-SMS be used to handle multiple Views and Models. More informationabout multiple Views is provided in the section Views on page 8-5. Nor-mally, a Project is created and saved in a SL-GML command file (with thesuffix ".p1"). The Project can then be loaded by an application program atstartup.


A

Version 6.2a- 26 M

SL-GMS GISMO Library Reference

Introduction

This appendix describes the following features of the GISMOs in theSL-GMS GISMO Library:

• standard styles

• Model names

• construction

• action function

• reserved names for DynProps

• appearance variables for DynProps

Standard styles of the SL-GMS GISMO Library

A GISMO has both an appearance (what it looks like) and a functionality(what it does). There are two basic appearance styles in the suppliedSL-GMS GISMO Library:

• "flat" — a two-dimensional look

• "Motif" — a three-dimensional Motif look-alike

A standard set of GISMOs is supplied: the flat look having Model nameswhich begin with "f_"; and the Motif look, which begin with "m_". For con-venience, these are referred to as "f" and "m" styles, respectively.

The "f" style appears flat and is rectangular. It has a two-dimensionalappearance. The variables associated with the fill, edge and text color,the text font, and the edge width are available as RenamedVars for eachInstance of an "f" style GISMO. The size of the GISMO Instance can bechanged by scaling.

The "m" style GISMOs are three-dimensional Motif look-alikes. Their high-lighting is fixed by the Motif standard. In addition to rectangular shapes,

SL-GMS Reference A-1ay 2006

there are also arrow and diamond shape Motif-compatible buttons. The"m" style GISMOs have the same functionality as the "f" style GISMOs.The "m" style GISMOs have fixed fill, edge and text colors and text fonts,but other variables are available as RenamedVars. The ".g" file can beedited to change the color/font, but it is saved as a different Model. Thesize of the GISMO Instance can be changed by scaling.

SL-GMS GISMO Library Model names

Model Name RestrictionsFor compatibility with all supported platforms, supplied library GISMOshave:

• file names (including extension) not exceeding fourteencharacters;

• GISMO Model names which are ten characters or less (allowingfor valid extensions of .g, .m1 and .dat);

• the first letter of the GISMO Model name chosen from the set{a-z};

• remainder of the characters from the set {a-z, 0-9, _ }

For all user-created GISMOs, the characters in the Model name are cho-sen from alphabetic, numeric, or underscore {A-Z, a-z, 0-9, _ }.

Model Naming ConventionThe first part of the GISMO Model name relates to its appearance, whilethe second part (separated by an underscore "_") relates to its function.

The "f" and "m" library GISMOs are named as shown below:

s_ffffffxx (10 characters maximum)

and

sg_ffffffx (10 characters maximum)

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

GISMO construction

This section describes how each GISMO in the SL-GMS GISMO Library isconstructed and the use of the RenamedVars and Program Interface foreach GISMO.

BUTTON BUTTON GISMOs are distributed in both "f" style (flat look) and "m" style(Motif look-alike) versions. To distinguish between form and function, theRenamedVars are conveniently subdivided into appearance RenamedVarsand functionality RenamedVars. Virtually the same set of appearanceRenamedVars applies to all GISMOs with the same look, regardless ofwhat the GISMO actually does. These are summarized in tables at the

Naming Convention of the SL-GMS GISMO Library

symbol example definition

s m_call STYLE index: "f" for "Flat" and "m" for "Motif"

g ma_call GEOMETRY index: • absent — Rectangular shape; Text centered ("f" style);

Text alignment controlled by text_align_x ("m" style);

• present — for "m" style only; text appears to right; a = arrow; d = diamond; s = square

ffffff m_quit Functionality of GISMO; six characters maximum

xx and x m_quit_0 CUSTOMIZATION: distinguish a user-modified GISMO from the library supplied version; any of the fixed attributes which are not available as RenamedVars may be modified (colors, text fonts, etc.)


end of this appendix. The functionality RenamedVars focus on what theGISMO does and are common to either style of GISMO appearance.

CALL GISMOs

Description: call an application callback

DynProps:

Functionality

#call gms_flash( )call gms_call(callback)

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) and gms_call( )

Appearance RenamedVars

Variable Name Style

see Table Af (page A-110) "f" (flat)

see Table Am (page A-111) "m" (Motif look-alike)


Functional Description:

When the CALL GISMO is selected, it calls gms_flash( ) to setthe value of the internal variable __button_hilite.1 This variableis used to highlight the GISMO. The style of highlighting isspecified in the part of the appearance DynProp which tests for__button_hilite set to one (refer to page A-118). In addition, theCALL GISMO invokes the user-defined callback function.

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of the gms_call( ) function isdescribed on page A-81.

Variables:

The CALL GISMO is distributed in both "f" style (flat look) and"m" styles (Motif look-alike versions).

1. There are only two underscores (_) in front of button_hilite. These are part of the variable name. The space between each underscore is for illustrative purposes only; it is not part of the variable name.


Variable Name CALL GISMO

see Table Af (page A-110) f_call

see Table Am (page A-111) m_callma_callmd_callms_call

Functionality RenamedVars

Variable Name Description

button_state renamed to an integer variable; provides highlight control

callback renamed to the user callback function


Example

RenamedVarsSample RenamedVars for the m_call GISMO to call auser-defined function called my_function:

button_label :: "myfunction"

button_state

callback :: my_function

edge_width :: 2

text_align_x :: 2

text_height :: 1.5

PROGRAM INTERFACEThe callback function must expect as an argument a pointer toan integer:

intmy_function (partindex)

int *partindex;/* index of GISMO part picked */

{/* this is a dummy statement; actual function

code belongs here... */printf("*partindex = %d \n", *partindex);return 1;

}

NOTE: partindex is a pointer (i.e., called by reference) so thatmy_function can be written in either C, FORTRAN, or Ada.


The callback function my_function must be declared toSL-GMS with the gmsAddUserFctn( ) call:

.

.int my_arg1p[] = {G_POINTER};..gmsAddUserFctn("my_function", my_function, G_INTEGER,

1, my_arg1p);

DATSCREEN GISMOs

Description: display a new screen; activate the screen’s ".dat"file for dynamics

Dynprop:

Functionality

#call gms_flash( )call gms_datscreen_state_invoke(view_name,model_name,reset_flag,clear_flag)

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) and gms_datscreen_state_invoke( )


The DATSCREEN GISMO calls gms_flash( ) to set the value ofthe internal variable _ _button_hilite. This variable is used to


highlight the GISMO. The style of highlighting is specified in thepart of the appearance DynProp which tests for _ _button_hiliteset to one (refer to page A-118).

The gms_datscreen_state_invoke( ) function deactivates thecurrent State and all SuperStates up to the last State Instancemarked with the gmsStMark( ) function (if there is no markedState Instance, it resets to the Top State) if the reset_flagargument is 1, pushes a new datscreen state with a new Model(model_name) on the state stack, and adds the Model to thenamed View (view_name). If the clear_flag is 1, the currentView is erased before displaying model_name. Setting theclear_flag variable to 0 prevents

the current View from being cleared, and model_name is drawnover the existing Model(s).

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of thegms_datscreen_state_invoke( ) function is described on pageA-83.

Variables:

The DATSCREEN GISMO is distributed in both "f" style (flatlook) and "m" style (Motif look-alike) versions.


Variable Name DATSCREEN GISMO

see Table Af (page A-110) f_dscrn

see Table Am (page A-111) m_dscrnmd_dscrnms_dscrn


Example

RenamedVarsSuppose the following is required in an application:

Clicking on a "GO TO SCREEN #1" button causes thecurrent View to clear and a Model named screen1 to bedisplayed and animated with the data description containedin the file "screen1.dat".

The RenamedVars that are required for a m_dscrn GISMOInstance to satisfy the above requirements are:

button_label :: "GO TO SCREEN #1"

button_state

clear_flag :: 1

edge_width :: 2

model_name :: "screen1"

reset_flag :: 1




clear_flag renamed to an integer constant or variable; 1 = clear the View before displaying Model, 0 = do not clear the View before displaying Model

model_name renamed to a string constant; the Model that is to become visible once this GISMO is selected

reset_flag renamed to an integer constant; setting to 1 deactivates the current State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked State Instance it resets to the Top State)

view_name renamed to a string constant; the View in which to display the specified Model


text_align_x :: 2

text_height :: 1.5

view_name :: ""

Upon each update pass, the contents of the "screen1.dat" fileare read until a blank line is encountered. If "screen1.dat" is notsuccessfully opened, the datscreen State behaves just as thescreen State does.

POPUP GISMOs

Description: display a popup menu or dialog box

DynProps:

Functionality

#call gms_flash( )call gms_popup_state_invoke(view_name,

model_name,reset_flag)

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) and gms_popup_state_invoke( )


The POPUP GISMO calls gms_flash( ) to set the value of theinternal variable _ _button_hilite. This variable is used tohighlight the GISMO. The style of highlighting is specified in the


part of the appearance DynProp which tests for _ _button_hiliteset to one (refer to page A-118).

The gms_popup_state_invoke( ) function deactivates thecurrent State and all SuperStates up to the last State Instancemarked with the gmsStMark( ) function (if there is no markedstate, it resets to the Top State) if the reset_flag argument is 1,pushes a new popup state with a new Model (model_name) onthe state stack, and adds the Model to the named View(view_name).

A popup state makes active a specified Model on top of existingModels, saving the obscured image in raster format for quickre-display when the popup state is deactivated. The POPUPGISMO remains highlighted until the popup state is activated(i.e., until the gms_popup_state_invoke( ) function returns).

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of thegms_popup_state_invoke( ) function is given on page A-93.

Variables:

The POPUP GISMO is distributed in both "f" style (flat look) and"m" style (Motif look-alike) versions.


Variable Name POPUP GISMO

see Table Af (page A-110) f_popup

see Table Am (page A-111) m_popupma_popup





Example


Clicking on a "POP UP MENU #1" button causes a Modelnamed popup1 to display on the screen over the existingModels in the View "v_main".

The RenamedVars that are required for a m_popup GISMOInstance to satisfy the above requirements are:

button_label :: "POP UP MENU #1"

button_state

edge_width :: 2

model_name :: "popup1"

reset_flag :: 1

text_align_x :: 2

text_height :: 1.5

view_name :: "v_main"


reset_flag renamed to an integer constant; setting to 1 deactivates the current State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked State Instance, it resets to the Top State)


Functionality RenamedVars(continued)



QUIT GISMOs

Description: exit an application program

DynProps:

Functionality

#call gms_flash( )call gms_quit( )

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) and gms_quit( )


The QUIT GISMO calls gms_flash( ) to set the value of theinternal variable _ _button_hilite. This variable is used tohighlight the GISMO. The style of highlighting is specified in thepart of the appearance DynProp which tests for _ _button_hiliteset to one (refer to page A-118).

The gms_quit( ) function kills all processes created by SL-SMSand exits SL-GMS gracefully.

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of the gms_quit( ) function isdescribed on page A-94.

Variables:


The QUIT GISMO is distributed in both "f" style (flat look) and"m" style (Motif look-alike) versions.

Example

RenamedVarsSample RenamedVars for an Instance of the m_quit GISMO:

button_label :: "QUIT"

button_state

edge_width :: 2

text_align_x :: 2

text_height :: 1.5


Variable Name QUIT GISMO

see Table Af (page A-110) f_quit

see Table Am (page A-111) m_quit





RETURN GISMOs

Description: return to previous screen

DynProps:

Functionality

#call gms_flash( )call gms_state_pop( )

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) andgms_state_pop( )


The RETURN GISMO calls gms_flash( ) to set the value of theinternal variable _ _button_hilite. This variable is used tohighlight the GISMO. The style of highlighting is specified in thepart of the appearance DynProp which tests for _ _button_hiliteset to one (refer to page A-118).

The gms_state_pop( ) function deactivates the event State (i.e.,the State in which an event occurred) if it exists, otherwise itdeactivates the current State by popping it from the SL-SMSinternal State stack and returns control to the Superstate of thepopup State.


The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of the gms_state_pop( )function is described on page A-99.

Variables:

The RETURN GISMO is distributed in both "f" style (flat look)and "m" style (Motif look-alike) versions.

Example

RenamedVarsSample RenamedVars for an Instance of the m_return GISMO:

button_label :: "RETURN"

button_state

edge_width :: 2

text_align_x :: 2

text_height :: 1.5


Variable Name RETURN GISMO

see Table Af (page A-110) f_return

see Table Am (page A-111) m_return





SCREEN GISMOs

Description: display a new screen

Dynprop:

Functionality

#call gms_flash( )call gms_screen_state_invoke(view_name,

model_name,reset_flag,clear_flag)

Appearance

Refer to page A-112

GISMO action functions: gms_flash( ) andgms_screen_state_invoke( )


The SCREEN GISMO calls gms_flash( ) to set the value of theinternal variable _ _button_hilite. This variable is used tohighlight the GISMO. The style of highlighting is specified in thepart of the appearance DynProp which tests for _ _button_hiliteset to one (refer to page A-118).

The gms_screen_state_invoke( ) function deactivates thecurrent State and all SuperStates up to the last State Instancemarked with the gmsStMark( ) function (if there is no markedstate, it resets to the Top State) if the reset_flag argument is setto 1; pushes a new screen state with a new Model(model_name) on the state stack; adds the Model to the named


View (view_name); and sets the popflag off and the freeflag on.If the clear_flag is 1, the current View is erased beforedisplaying model_name. Setting the clear_flag variable to 0prevents the current View from being cleared, and model_nameis drawn over existing Model(s).

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of thegms_screen_state_invoke( ) function is described on pageA-97.

Variables:

The SCREEN GISMO is distributed in both "f" style (flat look)and "m" style (Motif look-alike) versions.


Variable Name SCREEN GISMO

see Table Af (page A-110) f_scrn

see Table Am (page A-111) m_scrnmd_scrnms_scrn




clear_flag renamed to an integer constant or variable; 1 = clear the View before displaying Model, 0 = do not clear the View before displaying Model



Example


Clicking on a "GO TO SCREEN #2" button causes thecurrent View to clear and a Model named screen2 to bedisplayed.

The RenamedVars that are required for a m_scrn GISMOInstance to satisfy the above requirements are:

button_label :: "GO TO SCREEN #2"

button_state

clear_flag :: 1

edge_width :: 2

model_name :: "screen2"

reset_flag :: 1

text_align_x :: 2

text_height :: 1.5

view_name :: ""

reset_flag renamed to an integer constant; setting to1, deactivates the current State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked State Instance, it resets to the Top State)





STATE GISMOs

Description: invoke a State of a specified State class

DynProps:

Functionality

#call gms_stayon( )call gms_state_invoke(class_name, view_name,

model_name, reset_flag, clear_flag,pop_flag, dat_flag)

Appearance

Refer to page A-112

GISMO action functions: gms_stayon( ) and gms_state_invoke( )


The STATE GISMO calls the gms_stayon( ) function to set thevalue of the internal variable __ button_hilite. This variable isused to highlight the GISMO. The style of highlighting isspecified in the part of the Appearance Dynprop which tests for__button_hilite set to one (refer to page A-118).

The gms_state_invoke( ) function creates a new Instance ofthe State class class_name and installs it in the StateManagement Hierarchy. The other arguments set the variousState Instance attributes as described in the SL-GMS® State Class

Library Reference. The reset_flag, if set to 1, deactivates theevent State (that State in which an event occurred). States arethen de-activated starting at the event State and in order up theState tree until a marked State is encountered and then the


newly-created State Instance is installed as a SubState. If thereis no marked state, it resets to the Top State.

The calling syntax of the gms_stayon( ) function is described onpage A-100. The calling syntax of the gms_state_invoke( )function is described on page A-98.

Variables:

The STATE GISMO is distributed in both "f" style (flat look) and"m" style (Motif look-alike) versions.


Variable Name STATE GISMO

see Table Af (page A-110) f_state

see Table Am (page A-111) m_statemd_statems_state




class_name renamed to a string constant or variable; the name of the State class to invoke

clear_flag renamed to an integer constant or variable; 1 = clear the State's View before displaying Model, 0 = do not clear the State's View before displaying Model

dat_flag renamed to an integer constant or variable; 1 = open and read data from "model_name.dat" file, 0 = do not open a ".dat" file

model_name renamed to a string constant or variable; the Model to display


Example

RenamedVarsSample RenamedVars for an Instance of the m_state GISMO tocreate a button with the label "MYSTATE" that invokes a State ofthe mystate State class with the "mystate" Model displayed ontop of the existing Model in the view "v_main":

button_label :: "MYSTATE" \ model_name :: "mystate"\

class_name :: "mystate" \ pop_flag :: 0 \clear_flag :: 0 \ reset_flag :: 1 \dat_flag :: 0 \ text_align_x :: 2 \edge_width :: 3 \ text_height :: 1.5 \

view_name :: "v_main"

PROGRAM INTERFACEThis is an example of an initialize function — a function thatdefines a customized State. In this case a new State classcalled mystate is created with the gmsStateClass( ) function.The function gmsClassAddMethod( ) is called to designate themethods defined for the mystate class. After the State classmethods are defined, gmsStClassInstall( ) is called to install thenew State class. The State class can be defined only once.The SL-GMS® State Class Library Reference provides additional

pop_flag renamed to an integer constant or variable; the State popflag value

reset_flag renamed to an integer constant; setting to 1, deactivates the event State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked State Instance, it resets to the Top State)





information about initialization functions and activate, deactivate,and update functions.

An initialization function must be written for each of the differentcustomized States invoked by the renaming of the class_namevariable.

/* STATE INITIALIZE FUNCTION */intmystate_initialize ( ){

id stclass;/* build the "mystate" State class */

stclass = gmsStateClass("mystate", 0);gmsClassAddMethod(stclass, "activate",

activate, G_INTEGER, 0);gmsClassAddMethod(stclass, "deactivate",

deactivate, G_INTEGER, 0);gmsClassAddMethod(stclass, "update", update,

G_INTEGER, 0);gmsStClassInstall(stclass);return 1;

}


BUTTON GROUP

A GISMO BUTTON GROUP is a group of toggle buttons or other objectscooperating with each other in a prescribed manner. Toggle buttons comein two types:

• RADIO — only one button (or none) in the group can be "on"(e.g., selected, hilighted and active) at any one time

• CHECK — any, all, or none in the group can be "on" at any onetime

Any set of objects can be grouped together to create a toggle group witheither radio or check button behavior. Several "m" style GISMO modelsare provided in the GISMO library to help construct a toggle GISMO group.These "GISMO helpers" are shown below:

Figure A-1"GISMO helper" buttons

Page 5-16 provides information about constructing "GISMO helpers" andgrouping them together to produce RADIO and CHECK GISMOs.


RADIO GISMOs

Description: manipulate a variable from 0 to 1 to produce"radio" highlighting (only one GISMO element highlighted at atime) and optionally call an application callback

Dynprop:

Functionality:

The array-controlled RADIO GISMO Model DynProp with"fill" highlighting style is:

#call gms_radio_array(callback,&arrayvar

always_on)*call gms_hilite_color(&arrayvar, hc, uc)

The index-controlled RADIO GISMO Model DynProp with"fill" highlighting style is:

#call gms_radio_var(callback,&indexvar,

always_on)*

call gms_hilite_color_var(&indexvar,hc,uc)

The array-controlled RADIO GISMO Model DynProp with"edge" highlighting style is:

#

A

B

C

radio3 (with "A" selected)

1

2

3

3 "GISMO helpers"grouped together


call gms_radio_array(callback, &arrayvar,always_on)

*call gms_hilite_edge(&arrayvar, hc,uc, hw, uw)

The index-controlled RADIO GISMO Model DynProp with"edge" highlighting style is:


always_on)*

call gms_hilite_edge_var(&indexvar,hc,uc,hw,uw)

The array-controlled RADIO GISMO Model DynProp with"vis" highlighting style is:

#call gms_radio_array(callback, &arrayvar,

always_on)*

call gms_hilite_vis(&arrayvar)

The index-controlled RADIO GISMO Model DynProp with"vis" highlighting style is:


always_on)*

call gms_hilite_vis_var(&indexvar)

The array-controlled RADIO GISMO Model DynProp with"flip" highlighting style is:

#call gms_radio_array(callback,&arrayvar,

always_on)*

call gms_hilite_flip(&arrayvar)


The index-controlled RADIO GISMO Model DynProp with"flip" highlighting style is:


always_on)*

call gms_hilite_flip_var(&indexvar)

GISMO action functions: gms_radio_array( ), gms_radio_var( ), gms_hilite_color( ), gms_hilite_color_var( ), gms_hilite_edge( ), gms_hilite_edge_var( ), gms_hilite_vis( ), gms_hilite_vis_var( ), gms_hilite_flip( ), and gms_hilite_flip_var( )


The RADIO GISMO can be controlled by either an array variablein which at maximum only one element at a time is set to 1, or byan index variable which indexes the GISMO part currentlyselected. A RADIO GISMO controlled by an array variable,when selected, calls gms_radio_array( ) to set the elements ofthe variable arrayvar to 1 ("selected") and 0 ("unselected")appropriately and to optionally invoke a user function. A RADIOGISMO controlled by an index variable, when selected, callsgms_radio_var( ) to set the variable indexvar to the index ofthe selected part (indexvar will be set to -1 if none of the radiobuttons are selected) and to optionally invoke a user function.

A special parameter called always_on set to 1, indicates that atleast one radio button must remain on. In addition, radiobuttons are selected (or unselected) either by a loc_releaseEvent (pressing and releasing the mouse button) or a loc_motionEvent (dragging the mouse over the radio buttons) method. Ifalways_on is set to 0, radio buttons can only be selected (orunselected) by a loc_release Event. In addition, all radiobuttons can be unselected at the same time, one does not haveto remain on.


If the callback variable is renamed, the user-defined function isinvoked and passed the index of the selected object, along withthe value set for the variable.

Highlighting is accomplished via the gms_hilite_*( ) functions.Each highlighting style has two gms_hilite_*( ) functions: onefunction expects an array variable with elements set to 1(highlight) or 0 (unhighlight) and one function expects an indexvariable set to non-0 (highlight) or 0 (unhighlight).

For example, the "edge" style highlighting functions availableare:

gms_hilite_edge( )(expects array variable)

gms_hilite_edge_var( )(expects index variable)

The calling syntax of the gms_radio_array( ) function is described on pageA-94. The calling syntax of the gms_radio_var( ) function is described onpage A-95. The calling syntax of the gms_hilite_color( ) function isdescribed on page A-85. The calling syntax of the gms_hilite_color_var( )function is described on page A-86. The calling syntax of thegms_hilite_edge( ) function is described on page A-87. The calling syntaxof the gms_hilite_edge_var( ) function is described on page A-88. Thecalling syntax of the gms_hilite_vis( ) function is described on page A-91.The calling syntax of the gms_hilite_vis_var( ) function is described onpage A-92. The calling syntax of the gms_hilite_flip( ) function isdescribed on page A-88. The calling syntax of the gms_hilite_flip_var( )function is described on page A-89.

Variables:

The radio3 GISMO is array-controlled with "edge" highlighting. Variablesfor the radio3 GISMO are:


Example

RenamedVarsSample RenamedVars for an instance of the radio3 GISMOdriven by the array variable my_array and calling theuser-defined callback function my_function; one of the elementsof the GISMO is always highlighted; the GISMO uses an "edge"

Variablesradio3


always_on generally renamed to a integer constant although may be a variable; set to 1 indicates that at least one radio button must remain on and buttons are selected (or unselected) either by a loc_release Event or a loc_motion Event; set to 0 means that all buttons may be off and buttons are selected (or unselected) by a loc_release Event

arrayvar generally renamed to the array variable which drives the GISMO; the RADIO GISMO maintains this variable with its elements set to 1 (highlighted) or 0 (unhighlighted), corresponding to which objects in the GISMO are highlighted

callback renamed to the user callback function (without quotation marks); renaming is optional

hc renamed to an integer constant or variable; the highlight color

hw renamed to an double constant or variable; the highlight edge width

uc renamed to an integer constant or variable; the unhighlight color

uw renamed to an double constant or variable; the unhighlight edge width


highlighting style with an edge color of 5 and edge width of 3 forhighlighted and an edge color of 7 and an edge width of 1 forunhighlighted:

always_on :: 1

arrayvar :: my_array


hc :: 5

hw :: 3.

uc :: 7

uw :: 1.

arrayvar must be renamed. When arrayvar is renamed, thevalue of arrayvar’s elements are changed directly in memory inresponse to the input event. If both arrayvar and callback arerenamed, the value of arrayvar’s elements is changed directly inmemory and the callback function is then invoked. The callbackfunction might perform some error checking, change the value ofarrayvar’s elements further, or perform a function based uponthe radio button selected (or unselected).

Sample RenamedVars for a RADIO GISMO driven by the indexvariable my_variable and calling the user-defined callbackfunction my_function; one of the elements of the GISMO isalways highlighted; the GISMO uses an "edge" highlighting stylewith an edge color of 5 and edge width of 3 for highlighted andan edge color of 7 and an edge width of 1 for unhighlighted:

always_on :: 1


hc :: 5

hw :: 3.

indexvar :: my_variable

uc :: 7

uw :: 1.

indexvar must be renamed. When indexvar is renamed, thevalue of indexvar is changed directly in memory in response tothe input event. If both indexvar and callback are renamed,the value of indexvar is changed directly in memory and the


callback function is then invoked. The callback function mightperform some error checking, change the value indexvarfurther, or perform a function based upon the radio buttonselected (or unselected).

PROGRAM INTERFACEThe callback function must expect as arguments two pointers toan integer.

intmy_function (partindex, value)

int *partindex;/* index of GISMO part picked or-1(when always_on is 1, theloc_motion method is used forbutton selection, and the mousecursor is not on one of the objectsin the radio group)*/

int *value; /* value of arrayvar[partindex];either 0 or 1 if driven by an array— or —index of GISMO part picked or -1(if all buttons are off), if drivenby an index variable*/


code belongs here... */printf("*partindex = %d; *value = %d\n",

*partindex, *value);return 1;

}

NOTE: partindex and value are pointers (i.e., called by reference) sothat my_function can be written in either C, FORTRAN, or Ada.



.

.int my_arg2p[] = {G_POINTER, G_POINTER};..gmsAddUserFctn("my_function", my_function, G_INTEGER,

2, my_arg2p);

CHECK GISMOs

Description: manipulate a variable from 0 to 1 to produce"check" highlighting (any GISMO element toggled on or off) andoptionally call an application callback

DynProps for functionality and appearance:

Sample GISMO Model DynProps with varied highlighting stylesare shown below. The call to gms_toggle_array( ) provides thefunctionality. The second call in each of the DynProps:

gms_hilite_color( ),

gms_hilite_edge( ),

.

.

.

controls the highlighting appearance of the GISMO.


The CHECK GISMO Model DynProp with "fill" highlighting styleis:

#call gms_toggle_array(callback, &arrayvar)

*call gms_hilite_color(&arrayvar, hicolor, uncolor)

The CHECK GISMO Model DynProp with "edge" highlightingstyle is:


*call gms_hilite_edge(&arrayvar, hicolor,uncolor,

hiwidth, unwidthThe CHECK GISMO Model DynProp with "vis" highlighting styleis:



The CHECK GISMO Model DynProp with "flip" highlighting styleis:


*call gms_hilite_flip(&arrayvar)

GISMO action functions: gms_toggle_array( ),gms_hilite_color( ), gms_hilite_vis( ), gms_hilite_flip( ), andgms_hilite_edge( )



The CHECK GISMO is controlled by an array variable in whichappropriate elements are set to 1 for "selected" and 0 for "notselected." A CHECK GISMO, when selected, callsgms_toggle_array( ) to set the elements of an array variable,arrayvar, to 1 and 0 appropriately and to invoke a user function ifthe callback variable has been renamed.

The callback function receives the index of the selected object,along with the value set for that member of the array variable(arrayvar[index]).

Highlighting is accomplished via the gms_hilite_*( ) functions.The gms_hilite_*( ) functions which expect an array variablewith elements set to 1 (highlight) or 0 (unhighlight) are used inthe DynProps for the CHECK GISMO.

The calling syntax of the gms_toggle_array( ) function isdescribed on page A-106. The calling syntax of thegms_hilite_edge( ) function is described on page A-87. Thecalling syntax of the gms_hilite_color( ) function is described onpage A-85. The calling syntax of the gms_hilite_flip( ) functionis described on page A-88. The calling syntax of thegms_hilite_vis( ) function is described on page A-91.

Variables:

Variables for the toggle3 GISMO are:

Variablestoggle3


arrayvar generally renamed to the array variable which drives the GISMO; the CHECK GISMO maintains this variable with its elements set to 1 (highlighted) or 0 (unhighlighted), corresponding to which objects in the GISMO are highlighted


Example

RenamedVars(the CHECK GISMO in this example uses "flip" highlighting)

Sample RenamedVars for the CHECK GISMO are:

arrayvar :: my_array


arrayvar must be renamed. When arrayvar is renamed, thevalue of arrayvar’s elements is changed directly in memory inresponse to the input event. If both arrayvar and callback arerenamed, the value of arrayvar’s elements is changed directly inmemory and the callback function is then invoked. The callbackfunction might perform some error checking, change the value ofarrayvar’s elements further, or perform a function based uponthe check button(s) selected (or unselected).






Variablestoggle3(continued)



PROGRAM INTERFACEThe callback function must expect as arguments two pointers tointeger:

intmy_function (partindex, value)

int *partindex;/* index of GISMO part picked */int *value; /* value of arrayvar[partindex];

either 0 ("unselected") or 1("selected")*/


code belongs here... */printf("*partindex = %d; *value = %d\n",

*partindex, *value);return 1;

}

NOTE: partindex and value are pointers (i.e., called by reference) sothat my_function can be written in either C, FORTRAN, or Ada.


.


2, my_arg2p);


SPECIAL PURPOSE

CYCLE GISMOs

Description: manipulates a variable cycled through a set ofvalues from 0 to "n-1" where "n" is equivalent to the number ofobjects contained in the Model or Group to which the DynPropshown below is attached; optionally calls an application callback

Dynprop:

#call gms_cycle_var(callback, &variable)

*call gms_hilite_cycle(&variable)

GISMO action functions: gms_cycle_var( ) and gms_hilite_cycle( )


The CYCLE GISMO, when selected, calls the functiongms_cycle_var( ) to cycle the value of variable based upon thenumber of parts in the selected object. The gms_cycle_var( )function cycles the value of variable from 0 to "n-1" where "n" isequivalent to the number of objects contained in the Model orGroup to which the DynProp containing this function is attached.In addition, if the callback variable has been renamed, theuser-defined function is invoked.

The function gms_hilite_cycle( ) is passed the value of variable.This function highlights an object in a Group or part usingvisibility. The object whose part index is the same as the valueof variable is made visible. Other objects in the part (whichcould be a Group) are made invisible. If variable is -1, allobjects in the part or Group are made invisible.


The calling syntax of the gms_cycle_var( ) function is describedon page A-83. The calling syntax of the gms_hilite_cycle( )function is described on page A-87.

Variables:

Variables for the cycle1 and cycle2 GISMOs are:

Example

RenamedVarscallback (callback NOT renamed)

variable :: my_variable(variable renamed)

OR

callback :: my_function(callback renamed)

variable :: my_variable(variable renamed)

variable must be renamed. If only variable is renamed, thevalue of the renamed variable (my_variable in the first exampleabove) is changed directly in memory in response to the inputevent. If both variable and callback are renamed, as in thesecond example, the value of the renamed variable my_variableis changed directly in memory, and the my_function callbackfunction is then invoked. The callback function might perform

Variablescycle1 and cycle2



variable generally renamed to the index variable which drives the GISMO; the CYCLE GISMO maintains this variable as equal to the partindex (zero-relative) of the object currently selected


some error checking, change the value of my_variable further,or perform a function based upon the value of my_variable.

PROGRAM INTERFACEThe callback function must expect as arguments two pointers tointeger.

intmy_function (value, on)

int *value; /* value of the index of GISMO partpicked (zero relative) */

int *on; /* always = 1; meaning that this partof the GISMO is on */


code belongs here... */printf("*value = %d; *on = %d\n", *value, *on);return 1;

}

NOTE: value and on are pointers (i.e., called by reference) so thatmy_function can be written in either C, FORTRAN, or Ada.


.


2, my_arg2p);


FILL-PERCENT GISMOs

Description: manipulates a variable through a range of valuesbetween a maximum and a minimum and optionally calls anapplication callback

DynProps:

Functionality

#call gms_fpercent_var1(callback, &var, min,max)

*call gms_hilite_fpercent1(&var, min, max)

Appearance

Two DynProps are (each DynProp attached to a different part ofthe Model) used to control appearance in the f_fill GISMO.They are:

*fcolor background_color

*ecolor fill_colorfcolor fill_color

The m_fill GISMO has the following DynProp for appearance:


fill_color= *

fcolor fill_colorecolor fill_color

GISMO action functions: gms_fpercent_var1( ) andgms_hilite_fpercent1( )


When selected, the FILL PERCENT GISMO callsgms_fpercent_var1( ) to set the value of var between min andmax. If the callback variable is renamed, the user-definedfunction is invoked and passed the value of the percentageindex. The value of the percentage index is equal to min whenthe Filled Rectangle is empty, the value of max when 100percent full, or some value in between min and max when filledto some other percentage.

The fill-percent of a Rectangle is changed to reflect thepercentage of the value of the variable var in relation to min andmax by calling the gms_hilite_fpercent1( ) function.

The DynProp shown above is attached to a Model or Groupcontaining two or more objects. The first part is the backgroundobject, which is redrawn whenever the fill-percent object isclicked. The second part is the object itself, whose fill-percentis changed to represent the value of the variable var as apercentage between the minimum (the variable min) andmaximum (the variable max).

The calling syntax of the gms_fpercent_var1( ) function isdescribed on page A-85. The calling syntax of thegms_hilite_fpercent1( ) function is given on page A-90.

Variables:

The FILL PERCENT GISMO is distributed in both "flat" (f_fill)and Motif look-alike versions (m_fill). Variables for the f_filland the m_fill GISMO are:


EXAMPLE

RenamedVarsSample RenamedVars for an m_fill GISMO to fill between thevalues of 0.0 and 1000.0, based upon the value of the variablemy_variable, using color 14 as a fill color, and to call themy_function callback:


fill_color :: 14

max :: 1000.0

min :: 0.0

var :: my_variable

var must be renamed. When var is renamed, the value of therenamed variable (my_variable in the example above) ischanged directly in memory in response to the input event. If

Variables f_fill and m_fill


background_color (f_fill only) renamed to an integer constant or variable


fill_color renamed to an integer constant or variable; the fill color

max renamed to a double constant or variable; the maximum value in the range of valid values for var

min renamed to a double constant or variable; the minimum value in the range of valid values for var

var renamed to the variable which drives the GISMO


the callback variable is renamed, the callback function(my_function in the example above) is then invoked. Thecallback function might perform some error checking, changethe value of my_variable further, or perform a function basedupon the value of my_variable.

PROGRAM INTERFACEThe callback function must expect as an argument a pointer to adouble.

intmy_function (value)

double *value;/* value of relative position ofrectangle fill in range of minvalueto maxvalue */


code belongs here... */printf("*value = %g\n", *value);return 1;

}

NOTE: value is a pointer (i.e., called by reference) so that my_functioncan be written in either C, FORTRAN, or Ada.


.


1, my_arg1p);


SCROLLBOX GISMOs

Description: scroll lines of text; m_sboxs allows selection of asingle line of text and m_sboxm allows selection of multiplelines; optionally call user function(s) upon scrolling and/orselection

DynProps:

Functionality:

The m_sboxs and m_sboxm GISMOs are built as severalLocal SubModels within a Model. Each of the different LocalSubModels (m_slider, m_uparrow, m_downarrow andm_textscroll) has a DynProp attached to it that determinesits functionality. The Local SubModels are listed below withtheir associated DynProps.

The only difference in the DynProps for the single (m_sboxs)and multiple (m_sboxm) selection scrollboxes appears in them_textscroll Local SubModel.

m_slider: slide bar to scroll backwards/forwards within string_array

#call gms_text_array_slider_var(callback_slider,

&cursor_index, scrollbox_lines,first_index, last_index)


*call gms_text_array_slider_hilite

(&cursor_index, scrollbox_lines,first_index, last_index)

m_uparrow: arrow to scroll towards the beginning of string_array

#call gms_flash( )call gms_textscroll_lines(&string_array,

&cursor_index, scrollbox_lines, -1)

m_downarrow: arrow to scroll towards the end of string_array

#call gms_flash( )call gms_textscroll_lines(&string_array,

&cursor_index, scrollbox_lines, 1)

m_textscroll: a Group of Filled Text Rectangles used to display the text lines in string_array

m_sboxs GISMO (single selection)

#call gms_radioscroll_var(callback_select,

&cursor_index, &hilite_index, 0, 0)*

call gms_hilitescroll_var(&cursor_index,&hilite_index, hc, uc)

string_array_loaded= 1

call gms_textscroll_array(&string_array,&cursor_index, scrollbox_chars,scrollbox_lines)

m_sboxm GISMO (multiple selection)


#call gms_togglescroll_array(callback_select,

&cursor_index, &hilite_array, 0)*call gms_hilitescroll_array(&cursor_index,

&hilite_array, hc, uc)string_array_loaded

= 1call gms_textscroll_array(&string_array,

&cursor_index, scrollbox_chars,scrollbox_lines)

GISMO action functions: gms_flash( ), gms_text_array_slider_var( ), gms_text_array_slider_hilite( ),gms_textscroll_lines( ), gms_radioscroll_var( ), gms_hilitescroll_var( ),gms_togglescroll_array( ), gms_hilitescroll_array( ), gms_textscroll_array( )


The gms_text_array_slider_var( ) function responds to alocator press on the slider and sets the variable cursor_index tothe index in the string array of the first line in the scrollbox. Ifthe callback_slider variable is renamed, the user-definedcallback function is invoked and passed the address ofcursor_index.

The gms_text_array_slider_hilite( ) function movesthe slider box in response to the value set bygms_text_array_slider_var( ). It also resizes the slider box sothat its size corresponds to the percentage of the string arraywhich is displayed in the scrollbox window.

The gms_textscroll_lines( ) function is used to scroll throughan array of strings displayed in a Group of Text Rectangleobjects either 1 or -1 lines at a time.

The gms_radioscroll_var( ) sets the value of hilite_index inresponse to a locator Event. hilite_index, can be thought of as


an index (offset) into the array of strings. It is the index of thestring in an array of strings that is highlighted when it isdisplayed in a scrollbox.

The gms_hilitescroll_var( ) function highlights one member ofa Group of Text Rectangles. The index of member highlightedis determined, as follows:

part-index = hilite_index – cursor_index

All other members of the Group are unhighlighted.

The gms_togglescroll_array( ) function sets array elementvalues in hilite_array based upon which Text Rectangle wasclicked with the mouse. hilite_array is an array of integers thatspecifies which lines of the array are highlighted. An arrayelement with a value of 1 indicates a highlighted line of text.

The gms_hilitescroll_array( ) function is used to highlightselected lines of text.

The gms_textscroll_array( ) function is used to load a Group ofText Rectangle objects with strings from an array.

The calling syntax of the gms_flash( ) function is described onpage A-84. The calling syntax of the gms_textscroll_lines( )function is described on page A-105. The calling syntax of thegms_text_array_slider_var( ) function is described on pageA-101. The calling syntax of the gms_radioscroll_var( ) functionis described on page A-96. The calling syntax of thegms_hilitescroll_var( ) function is described on page A-93. Thecalling syntax of the gms_togglescroll_array( ) function isdescribed on page A-106. The calling syntax of thegms_text_array_slider_hilite( ) function is described on pageA-101. The calling syntax of the gms_hilitescroll_array( )function is described on page A-92. The calling syntax of thegms_textscroll_array( ) function is described on page A-104.


Variables:

Functionality RenamedVars for m_sboxs and m_sboxm


callback_select renamed to the user callback function (without quotation marks) for gms_radioscroll_var( )(m_sboxs only) and gms_togglescroll_array( ) (m_sboxm only)

callback_slider renamed to the user callback function (without quotation marks) for gms_text_array_slider_var( )

cursor_index renamed to an integer variable; the offset into string_array

hc renamed to an integer constant or variable; the highlight color for the currently-selected line (m_sboxs) or lines (m_sboxm) in the scrollbox

first_index renamed to an integer variable; index of the first element in string_array

hilite_array (m_sboxm only) renamed to an array of integers; an array element value of 1 means the corresponding string in string_array is highlighted

hilite_index (m_sboxs only) renamed to an integer variable; offset into string_array of highlighted object

last_index renamed to an integer variable; index of the last element in string_array

scrollbox_chars renamed to an integer constant or variable; maximum characters per line

scrollbox_lines renamed to an integer constant or variable; the number of Text Rectangles in the Group that makes up the scrollbox


Example

RenamedVars

Sample RenamedVars for an Instance of the m_sboxs GISMO:

callback_select :: my_function_select

callback_slider :: my_function_slider

cursor_index :: 0

first_index :: 0

hc :: 14

hilite_index :: my_hilite_index

last_index :: my_filelength

scrollbox_chars :: 70

scrollbox_lines :: 22

string_array :: my_string_array

string_array_loaded :: 1

uc :: 13

Sample RenamedVars for an Instance of the m_sboxm GISMO:

callback_select :: my_function_select

callback_slider :: my_function_slider

string_array renamed to an array of strings; the data displayed in the scrollbox

string_array_loaded

renamed to an integer variable; causes the Text Rectangles in the scrollbox to be loaded from string_array when set to 1

uc renamed to an integer constant or variable; the normal color for lines in the scrollbox

Functionality RenamedVars for m_sboxs and m_sboxm

(continued)



cursor_index :: 0

first_index :: 0

hc :: 14

hilite_array :: my_hilite_array

last_index :: my_filelength

scrollbox_chars :: 70

scrollbox_lines :: 22

string_array :: my_string_array

string_array_loaded :: 1

uc :: 13

PROGRAM INTERFACEThe callback_select callback function, for both thegms_radioscroll_var( ) and gms_togglescroll_array( ) functions,must expect as arguments two pointers to an integer and onepointer to an id. The value parameter passed from thegms_radioscroll_var( ) (m_sboxs GISMO) and thegms_togglescroll_array( ) (m_sboxm GISMO) functions isdifferent. The other parameters are identical.

intmy_function_select (part_index, value, picked_part)

int *part_index; /* which of the Filled TextRectangles in the Group was clickedon; valid values are 0 to(scrollbox_lines - 1) */

int *value; /* for m_sboxs: line number withinstring_array that is currentlyhighlighted; valid values arefirst_index to last_index;for m_sboxm: 1 = highlighted,0 = unhighlighted */

id *picked_part; /* id of Filled Text Rectangle thatwas clicked on */


code belongs here... */


printf("*part_index = %d; *value = %d\n",*part_index, *arrayindex);

return 1;}The callback_slider function must expect as an argument apointer to integer:

intmy_function_slider (cursorindex)

int *cursorindex;/* index in string_array of firstline displayed in scrollbox */


code belongs here... */printf("*cursorindex = %d \n", *cursorindex);return 1;

}

NOTE: part_index, value, picked_part, and cursorindex are pointers(i.e., called by reference) so that my_function_select andmy_function_slider can be written in either C, FORTRAN, orAda.

The callback functions my_function_slider andmy_function_select must be declared to SL-GMS with thegmsAddUserFctn( ) call:

.

.int my_arg1p[] = {G_POINTER};int my_args3p[] = {G_POINTER, G_POINTER, G_POINTER};..gmsAddUserFctn("my_function_slider",

my_function_slider,G_INTEGER,1, my_arg1p);


gmsAddUserFctn("my_function_select",my_function_select,G_INTEGER,3, my_arg3p);


Scrolling functions

The SL-GMS GISMO Action Functions which provide scrolling aredesigned to be used for scrolling menus containing lines of text. Exam-ples of the use of the scrolling functions (and scrollbox GISMOs) can befound in the gismos subdirectory of the demo directory.

The function in the library that actually does the scrolling isgms_textscroll_array( ). The other functions that affect the scrollboxwork by changing the value of the cursor_index variable. Thecursor_index variable represents an offset into the string_array — in oth-er words, string_array[cursor_index] is the first line of text displayed inthe scrollbox window. For instance, the gms_textscroll_lines( ) functionincrements cursor_index by numlines, and then calls gmsVarChanged( )on cursor_index. When SL-GMS is notified that cursor_index haschanged, the gms_textscroll_array( ) function is activated and scrolls thetext in the scrollbox.

Two functions for manipulating the scrollbox with a slider GISMO alsoexist: gms_text_array_slider_var( ) and gms_text_array_slider_hilite(). These functions control the slider GISMO’s input and display dynamics,respectively. As with the gms_textscroll_lines( ) function describedabove, these functions work by changing the value of cursor_index. Thefunctions also change the size of the slider rectangle to reflect the percent-age of the file that is being viewed in the scrollbox.

In addition to the scrolling behavior, the scrollbox itself can respond tomouse clicks in two different ways: radio behavior and check behavior.

The gms_radioscroll_var( ) and gms_hilitescroll_var( ) functions areused in conjunction to provide radio-highlighting behavior. When a line oftext is clicked, it is highlighted. If it is clicked again it is unhighlighted. Ifanother line of text is clicked, the first line is unhighlighted and the new lineis highlighted.

The gms_togglescroll_array( ) and gms_hilitescroll_array( ) functionsare used to highlight one or more lines of text in a scrollbox. Thehilite_array variable is an array of integers that contains the information

that determines which lines of the array are highlighted. Thegms_togglescroll_array( ) function sets array element values to 1 if theline is highlighted and 0 if it is not. The gms_hilitescroll_array( ) function


reads the values in the hilite_array and highlights the correct lines of textin the scrollbox.

ExampleThe three dynamic action functions in the DynProp below are used to loada Group of Text Rectangles from an array of strings(gms_textscroll_array( )), and to provide scrolling, highlighting, and tog-gling behavior for each line of text. The Text Rectangles are created withempty strings; they are loaded later when the gms_textscroll_array( )function is called.

// Part of a scrollbox with check behaviortextlines: group

ftrect 8.00012 69.6011 97.5998 72.8011 ""ftrect 8.00012 66.4011 97.5998 69.6011 ""ftrect 8.00012 63.2011 97.5998 66.4011 ""ftrect 8.00012 60.0012 97.5998 63.2011 ""...

. dynprop \(# \

(call gms_togglescroll_array(callback,&cursor_index, &hilite_array, 0))) \

(* \(call gms_hilitescroll_array(&cursor_index,

&hilite_array, hc, uc))) \(string_array_loaded \

(= 1 \(call gms_textscroll_array(&string_array,

&cursor_index,scrollbox_chars,scrollbox_lines))))

endg

The calling syntax for the gms_togglescroll_array( ) functions is describedon page A-106. The calling syntax for the gms_hilitescroll_array( ) func-tion is described on page A-92. The calling syntax of thegms_textscroll_array( ) function is described on page A-104. SCROLL-BOX GISMOs are described in greater detail starting on page A-44.


SLIDER GISMOs

Description: manipulate a variable through a range of valuesbetween a minimum and a maximum and optionally call anapplication callback

DynProps for functionality:

The SLIDER GISMO Model DynProp which performs a moveoperation (move part of the GISMO within a minimum and amaximum) and optionally calls a user function is:

#call gms_slider_var1(callback, &var, min, max)

*call gms_hilite_percent1(&var, min, max)

The SLIDER GISMO Model DynProp which performs a replacepoints operation (move a part of the GISMO within a minimumand a maximum and the capability to change the size of themoving part) and calls a user function is:

#call gms_slider_var1(callback, &var, min, max)

*call gms_hilite_percent2(&var1, &var2, min,

max)


GISMO action function: gms_slider_var1( ),gms_hilite_percent1( ), and gms_hilite_percent2( )


When selected, the SLIDER GISMO calls gms_slider_var1( ) toset the value of a variable between a minimum and maximum.A part of the GISMO object may be moved between two otherscale-defining objects. The position of the moving elementrepresents the actual value of the variable.

The callback function is invoked with one or two arguments,which is the value of the variable or variables associated withthe location of the slider.

A DynProp describing slider behavior is applied to a Model orGroup containing four or more objects. The first is thebackground object, which is redrawn whenever the slider isclicked. The second object is the slider itself, which may bepositioned to represent the value of a single variable, or mayhave its Points transformed to represent the value of twovariables. The scale is implied between Reference Pointslocated by the third and fourth objects.

The calling syntax of the gms_slider_var1( ) function isdescribed on page A-98. The calling syntax of thegms_hilite_percent1( ) function is described on page A-90. Thecalling syntax of the gms_hilite_percent2( ) function is describedon page A-91.

Variables:

The SLIDER GISMO is distributed in both "flat" (f_slide) andMotif look-alike versions (m_slideh, and m_slidev). Thevariables for the f_slide, m_slideh (horizontal) and m_slidev(vertical) GISMOs are:


The f_slide, m_slideh, and m_slidev GISMOs are allimplementations of a Model DynProp that performs a moveoperation. They call the gms_slider_var1( ) andgms_hilite_percent1( ) functions. For this type of ModelDynProp, renaming the callback variable is optional.

If a SLIDER GISMO is created using the Model DynProp whichperforms a replace points operation (using the gms_slider_var1() and the gms_hilite_percent2( ) functions), the callback variablemust be renamed and it must set the value of var1 and var2 sothat they can be used by the gms_hilite_percent2( ) function.

Example

RenamedVars(the SLIDER GISMO in this example is driven by one variable)

Sample RenamedVars for the m_slideh GISMO are:


max :: 1000.0

Variablesf_slide

m_slidehm_slidev



max renamed to double constant or variable; the maximum value in the range of valid values for var

min renamed to double constant or variable; the minimum value in the range of valid values for var

var renamed to the variable which drives the GISMO


min :: 0.0

var :: my_variable

PROGRAM INTERFACEThe callback function must expect as an argument a pointer to adouble:


double *value;/* value of variable; relativeposition of GISMO part picked inrange of min to max */


code belongs here... */printf("*value = %g\n", *value);/* update dynamics and display */gmsDynUpdate(nil);gmsUpdate(nil);return 1;

}



.


1, my_arg1p);


TEXTENTRY ARRAY GISMOsDescription: call an application callback function with individualfields entered of type integer, double, or string.

DynProps:

The TEXTENTRY ARRAY GISMO Model DynProp with "edge"highlighting is:

#call gms_textentry_array(callback, &arrayvar,

maxchars, type)arrayvar

= *call gms_textload_array(&arrayvar,maxchars,

array_type)__selected_object

= *call2 gms_hilite_edge_selobj(hc, uc, hw, uw)

The TEXTENTRY ARRAY GISMO Model DynProp with "fill"highlighting is:

#call gms_textentry_array(callback, &arrayvar,

maxchars, type)arrayvar

= *call gms_textload_array(&arrayvar,maxchars,

array_type)__selected_object

= *call2 gms_hilite_color_selobj(hc, uc)


GISMO action functions: gms_textentry_array( ), gms_textload_array( ), gms_hilite_edge_selobj( ), and gms_hilite_color_selobj( )


The TEXTENTRY ARRAY GISMO can be a Model or Group ofText or Text Rectangle objects whose contents are controlled byan array variable, arrayvar, and whose highlighting is controlledby the _ _selected_object variable. Upon a string event,gms_textentry_array( ) copies the text string from the indexpart within the Model or Group into the indexed element in thearray.

The _ _selected_object variable is used by the SL-GMS eventhandler to determine which object is currently echoing andshould therefore receive the string event via gmsDynEvent( )upon completion. When this occurs, the GISMO callbackfunction used queries the text string contained in the echoingobject and places it into the variable provided as an argument.The __selected_object variable is also used by thegms_hilite_edge_selobj( ) and gms_hilite_color_selobj( )functions to hilite the selected GISMO.

The calling syntax of the gms_textentry_array( ) function isdescribed on page A-102. The calling syntax of thegms_textload_array( ) function is described on page A-104.The calling syntax of the gms_hilite_edge_selobj( ) function isdescribed on page A-88. The calling syntax of thegms_hilite_color_selobj( ) function is described on page A-86.

Variables:

Variables for a TEXTENTRY ARRAY GISMO are:


Basic SL-GMS Data Types (defined in the file "gmscodes.h"distributed in the lib subdirectory) valid for the TEXTENTRYARRAY GISMO are:

VariablesTextEntry Array GISMO


array_type renamed to an integer constant or variable; the variable's Basic SL-GMS Array Type in decimal (the list of valid values is provided under the heading Array Types in the table below)

arrayvar renamed to the array variable which the text represents




maxchars renamed to an integer constant or variable; the maximum number of characters allowed for input

type renamed to an integer constant or variable; the variable's Basic SL-GMS Data Base Type in decimal (the list of valid values is provided under the heading Types in the table below)




Example

RenamedVarsSample RenamedVars for a TEXTENTRY ARRAY GISMO toallow input of an integer (maximum of 10 characters); call themy_function callback and set the variable my_variable:

array_type :: 2 (integer)

arrayvar :: my_variable


hc ::7

hw :: 3.

maxchars :: 10

Basic SL-GMS Data TypesValid for the TEXTENTRY ARRAY GISMO

Data Type Description Hex Value Decimal Value

G_INTEGER integer 0x2 2

G_DOUBLE double 0x8 8

G_STRING pointer to pointer to a null-terminated string

0x100 256

Basic SL-GMS Array TypesValid for the TEXTENTRY ARRAY GISMO

Array Types Description Hex ValueDecimal

Value



G_CHAR pointer to pointer to a null-terminated string

0x10 16


type :: 2 (integer)

uc ::15

uw ::1.

Sample RenamedVars for a TEXTENTRY ARRAY GISMO toallow input of a double (maximum of 10 characters); call themy_function callback and set the variable my_variable:

array_type :: 8 (double)



hc ::7

hw :: 3.

maxchars :: 10

type :: 8 (double)

uc ::15

uw ::1.

Sample RenamedVars for a TEXTENTRY ARRAY GISMO toallow input of a string (maximum of 10 characters); call themy_function callback and set the variable my_variable:

array_type :: 16 (string)



hc ::7

hw :: 3.

maxchars :: 10

type :: 256 (string)

uc ::15

uw ::1.

PROGRAM INTERFACE

If type is 2 (integer) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to an integer:

int


my_function (obj, i)

id *obj; /* pointer to pointer to GISMO partpicked */

int *i; /* integer value entered */{

/* this is a dummy statement; actual functioncode belongs here... */

printf("*obj = %x, *i = %d\n",*obj, *i);

/* include this statement if wish to clear stringjust entered */

gmsTRepl(*obj,"");

/* include this statement todeactivate/unhighlight upon end ofstring entry, i.e., with the<RETURN> key */

gmsStTextEditObj(gmsQStEvState( ), nil,0,"","",0);

return 1;}

If type is 8 (double) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to a double:

intmy_function (obj, d)

id *obj; /* pointer to a pointer to GISMO partpicked */

double *d; /* double value entered */{


printf("*obj = %x, *d = %g\n",*obj, *d);


gmsTRepl(*obj,"");




return 1;}

If type is 256 (string) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to a pointer to char:

intmy_function (obj, s)

id *obj; /* pointer to pointer to GISMO partpicked */

char **s; /* string entered */{


printf("*obj = %x, *s = %s\n",*obj, *s);


gmsTRepl(*obj,"");



return 1;}

NOTE: obj, i, d, and s are pointers (i.e., called by reference) so thatmy_function can be written in either C, FORTRAN, or Ada.


By default, the TEXTENTRY ARRAY GISMO is selected(activated and highlighted) by clicking on it with the mouse andunselected when another TEXTENTRY ARRAY GISMO isselected. To have the TEXTENTRY ARRAY GISMO deactivateand unhighlight upon termination of string entry, that is, via the<RETURN> key, the gmsStTextEditObj( ) function call isincluded in the user callback function. Regardless of type thecallback function my_function must be declared to SL-GMSwith the gmsAddUserFctn( ) call as follows:

.


2, my_arg2p);

In the code fragment above, my_arg2p[ ] is exactly thesame for each type because thearguments to my_function are alwayspointers.


TEXTENTRY VAR GISMOs

Description: call an application callback function with individualfields entered of type integer, double, or string.

DynProps:

Functionality:

The TEXTENTRY VAR GISMO Model DynProp with "edge"highlighting is:

#call gms_textentry_var(callback, &variable,

maxchars, type)__selected_object

= *call gms_hilite_edge_selobj(hc, uc, hw, uw)

The TEXTENTRY VAR GISMO Model DynProp with "fill"highlighting is:

#call gms_textentry_var(callback, &variable,

maxchars, type)__selected_object

= *call gms_hilite_color_selobj(hc, uc)


GISMO action functions: gms_textentry_var( ),gms_hilite_edge_selobj( ), and gms_hilite_color_selobj( )


The TEXTENTRY VAR GISMO uses the gms_textentry_var( )function which does two things in response to either a locatorselection of the object, or the string event which is generatedupon completion of the string by typing a <NEWLINE>:

• When the TEXTENTRY VAR GISMO is selected via aLocator, the Text or Text Rectangle object is made into thecurrent string-echo object by calling SL-GMS functiongmsStTextEditObj( ). The internal SL-GMS variables,_ _selected_object and _ _self are set to the address of theobject at the same time.

• The _ _selected_object variable is used by the SL-GMSevent handler to determine which objectis currently echoing and should therefore receive the string event via gmsDynEvent( ) upon completion.When this occurs, the GISMO callback function used queries the text string contained in theechoing object and places it into the variable provided as an argument. The __selected_object variable is also used by the gms_hilite_edge_selobj( ) andgms_hilite_color_selobj( ) functions to hilite the selected GISMO.

The calling syntax of the gms_textentry_var( ) function isdescribed on page A-103. The calling syntax of thegms_hilite_edge_selobj( ) function is described on page A-88.The calling syntax of the gms_hilite_color_selobj( ) function isdescribed on page A-86.

Variables:

The TEXTENTRY VAR GISMO is distributed in both "flat"(f_textv and textentry) and Motif look-alike versions (m_textv).The variables for the f_textv GISMO are:


Variablesf_textv


callback renamed to the user callback function (without quotation marks); renaming is optional if variable is renamed


hw renamed to a double constant or variable; the highlight edge width


type renamed to an integer constant or variable; the variable's Basic SL-GMS Data Base Type in decimal (the list of valid values is provided under the heading Types in the table on page A-71)

variable renamed to a string variable which the text represents; renaming is optional if callback is renamed




Variables for the textentry GISMO are:

Variables for the m_textv GISMO are:

Variablestextentry






Variablesm_textv


see Table Am (page A-111)1




The basic SL-GMS Data Types (defined in the file "gmscodes.h"distributed in the lib subdirectory), valid for the TEXTENTRYVAR GISMO, are:

Example

RenamedVarsSample RenamedVars for the m_textv GISMO to allow input ofan integer (maximum of 10 characters); call the my_functioncallback and set the variable my_variable:




1. button_label is not a variable in the m_textv GISMO.

Basic SL-GMS Data TypesValid for the TEXTENTRY VAR GISMO

Data Type Description Hex Value Decimal Value



G_STRING pointer-to-pointer to a null-terminated string

0x100 256

Variablesm_textv(continued)



edge_width :: 3

maxchars :: 10

text_align_x :: 2

text_height :: 1.5

type :: 2 (integer)

variable :: my_variable

Sample RenamedVars for the m_textv GISMO to allow input of adouble (maximum of 10 characters); call the my_functioncallback and set the variable my_variable:


edge_width :: 3

maxchars :: 10

text_align_x :: 2

text_height :: 1.5

type :: 8 (double)


Sample RenamedVars for the m_textv GISMO to allow input of astring (maximum of 10 characters); call the my_functioncallback and set the variable my_variable:


edge_width :: 3

maxchars :: 10

text_align_x :: 2

text_height :: 1.5

type :: 256 (string)


PROGRAM INTERFACEIf type is 2 (integer) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to an integer:

int


my_function (obj, i)id *obj; /* pointer to pointer to GISMO part

picked */int *i; /* integer value entered */


code belongs here... */printf("*obj = %x, *i = %d\n",*obj, *i);


gmsTRepl(*obj,"");


gmsStTextEditObj(gmsQStEvState( ),nil,0,"","", 0);

return 1;}

If type is 8 (double) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to a double:

intmy_function (obj, d)

id *obj; /*pointer to pointer to GISMO part picked*/double *d;/* double value entered */

{/* this is a dummy statement; actual function code

belongs here... */printf("*obj = %x, *d = %g\n",*obj, *d);


gmsTRepl(*obj,"");


/*include this statement to deactivate/unhighlightupon end of string entry, i.e.,with <RETURN> key*/

gmsStTextEditObj(gmsQStEvState( ), nil, 0,"","",0);

return 1;}

If type is 256 (string) the callback function must expect as anargument a pointer to a pointer to the object selected and apointer to a pointer to char:

intmy_function (obj, s)

id *obj;/*pointer to pointer to GISMO part picked*/char **s; /* string entered */


code belongs here... */printf("*obj = %x, *s = %s\n",*obj, *s);


gmsTRepl(*obj,"");



return 1;}

NOTE: obj, i, d, and s are pointers (i.e., called by reference) so thatmy_function can be written in either C, FORTRAN, or Ada.


By default, the TEXTENTRY VAR GISMO is selected (activatedand highlighted) by clicking on it with the mouse and unselectedwhen another TEXTENTRY VAR GISMO is selected. To havethe TEXTENTRY VAR GISMO deactivate and unhighlight upontermination of string entry, that is, via the <RETURN> key, thegmsStTextEditObj( ) function call is included in the user callbackfunction.

Regardless of type the callback function my_function must bedeclared to SL-GMS with the gmsAddUserFctn( ) call asfollows:

.


2, my_arg2p);

In the code fragment above, my_arg2p[ ] is the same for eachtype because the arguments to my_function are alwayspointers.


NON STANDARD

COLORCELLS GISMOs

Description: manipulates a color index variable equal to thecolor index of the object picked and optionally calls anapplication callback function

DynProps:

Functionality

#call gms_color_select(callback, &colorvar)

Appearance (colarr4 only):

cube_start_index= *

ecolor (cube_start_index - 4)fcolor (cube_start_index + 0)

cube_start_index= *


.

.

.cube_start_index

= *



The appearance of objects in the colorcells GISMO isdetermined by the attributes associated with each object.DynProps are not utilized for control of appearance.

GISMO action functions: gms_color_select( )


When selected, the COLORCELLS GISMO callsgms_color_select( ) to set the value of the colorvar renamedvariable to the color index of the object selected. The callbackfunction is invoked (if the callback variable is renamed) andpassed the value of the fill color index of the selected part.

Valid color indices are taken from the "colordef.dat" file definedin either the SL-GMS lib directory, the current directory, or anydirectory defined to SL-GMS with the gmsAddLibPath( )function.

The calling syntax of the gms_color_select( ) function isdescribed on page A-82.

Variables:

Variables for the colorcells GISMO are:

Variables colorcells


callback renamed to the user callback function (without quotation marks); renaming is optional if colorvar is renamed


Variables for the colarr4 GISMO are:

Example

RenamedVarscallback (callback NOT renamed)

colorvar :: my_colorvar(variable renamed)

OR


colorvar (variable NOT renamed)

OR

colorvar generally renamed to the integer variable that drives the GISMO; renaming is optional if callback is renamed

Variables colarr4


callback renamed to the user callback function (without quotation marks); renaming is optional if colorvar is renamed

colorvar generally renamed to the integer variable that drives the GISMO; renaming is optional if callback is renamed

cube_start_index renamed to an integer constant or variable; the color for each cell is computed as (cube_start_index + offset where offset is in the range 0-63)

Variables colorcells

(continued)




colorvar :: my_colorvar(variable renamed)

Either colorvar, callback, or both must be renamed. If onlycolorvar is renamed, the value of the renamed variable(my_colorvar in the first example above) is changed directly inmemory in response to the input event. If only the callbackvariable is renamed, the callback function (my_function in thesecond example) is invoked. If both colorvar and callback arerenamed, as in the third example, the value of the renamedvariable my_colorvar is changed directly in memory, and themy_function callback function is then invoked. The callbackfunction might perform some error checking or change the valueof my_colorvar further.

PROGRAM INTERFACEThe callback function must expect as an argument a pointer toan integer:


int *value; /* value of color index of objectpicked*/


code belongs here... */printf("*value = %d\n", *value);return 1;

}




.


1, my_arg1p);


SL-GMS GISMO Action Functions

(In alphabetical order by function name)

gms_call( )

Syntaxintgms_call (callback)

int (*callback)( );/* user-defined callbackfunction */

DescriptionThis function calls a user-defined function in response to a locator release.

CallbackPage A-6 provides a description of the callback function.

gms_call1( )

Syntaxintgms_call1 (callback, arg1)


long arg1; /* argument to user-defined callbackfunction */

DescriptionThis function calls a user-defined function with one argument in responseto a locator release.

CallbackThe callback function must expect as arguments a pointer to an integer anda long:

int


my_function (partindex, arg)int *partindex;/* index of GISMO part picked */long arg; /* argument to callback function */


code belongs here... */printf("*partindex = %d; arg = %d\n",

*partindex, arg);return 1;

}

NOTE: partindex is a pointer (i.e., called by reference) so thatmy_function can be written in either C, FORTRAN, or Ada.

The callback function my_function must be declared to SL-GMS with thegmsAddUserFctn( ) call:

.

.int my_arg1p1i[] = {G_POINTER, G_INTEGER};..gmsAddUserFctn("my_function", my_function, G_INTEGER,

2, my_arg1p1i);

gms_color_select( )

Syntaxintgms_color_select (callback, colorindex)


int *colorindex;/* color index variable */


DescriptionThis function sets a color index variable to the fill color index of the select-ed part and optionally calls a user callback function, passing the fill colorindex of the selected part.


gms_cycle_var( )

Syntaxintgms_cycle_var (callback, variable)


int *variable;/* index variable */

DescriptionThis function cycles a variable based upon the number of parts in theselected object. The function cycles the value of variable from 0 to "n-1"where "n" is equivalent to the number of objects contained in the Model orGroup to which the DynProp containing this function is attached, andinvokes an optional user-defined function.


gms_datscreen_state_invoke( )

Syntaxintgms_datscreen_state_invoke (viewname, modelname,

resetflag, clearflag)char *viewname;/* name of View in which to display

Models */char *modelname;/* name of Model to display */


int resetflag;/* ON = reset State stack */int clearflag;/* ON = clear View before displaying

Model */

DescriptionThis function creates and activates an Instance of the datscreen Stateclass. It also sets the View name, adds a Model to the State Instance’sModel List, and sets the State Instance’s clearflag to the specified value,resetflag to the specified value, datflag to 1, popflag to 0, and freeflag to1.

gms_flash( )

Syntaxintgms_flash ( )

DescriptionThe gms_flash( ) function highlights the selected object using "flash"behavior. The _ _button_hilite variable is set in response to a locatorpress, and reset in response to a locator release.

gms_flash_call( )

Syntaxintgms_flash_call (callback)


DescriptionThis function calls a user-defined function with "flash" highlighting behavioron the selected object. The _ _button_hilite variable is set in response toa locator press, and reset in response to a locator release. If a callbackfunction is specified, it is invoked after _ _button_hilite is reset.



gms_fpercent_var1( )

Syntaxintgms_fpercent_var1(callback, variable, minvalue,

maxvalue)int (*callback)( );/* user-defined callback

function */double *variable;/* variable to set */double minvalue;/* maximum value of range */double maxvalue;/* minimum value of range */

DescriptionThis function sets a variable in a range in response to a locator press on aFILL PERCENT GISMO.

CallbackPage A-43 for a description of the callback function.

gms_hilite_color( )

Syntaxintgms_hilite_color (arrayvar, hc, uc)

int *arrayvar;/* array variable */int hc; /* highlighted color */int uc; /* unhighlighted color */

DescriptionThis function highlights the objects in a Group or part using fill color,(objects are assumed to be filled), according to the values in the array vari-able. If arrayvar[part-index] is 1, the part’s fill color is set to the highlight-ed color. If the arrayvar[part-index] is 0, the part’s fill color is set to the


unhighlighted color. Other objects in the Group are changed to theunhilighted color.

gms_hilite_color_selobj( )

Syntaxintgms_hilite_color_selobj (hc, uc)

int hc; /* highlighted color */int uc; /* unhighlighted color */

DescriptionThis function highlights only one object in a Group — that which is the cur-rent TextEdit object. An object is made the current TextEdit object throughexecution of one of the following functions:

gmsStTextEditobj( )

gms_textentry_array( )

gms_textentry_var( )

gms_hilite_color_var( )

Syntaxintgms_hilite_color_var (indexvar, hc, uc)

int *indexvar;/* part index of object to highlight*/

int hc; /* highlighted color */int uc; /* unhighlighted color */

DescriptionThis function highlights an object in a Group or part using fill color (objectsare assumed to be filled). The object whose part index is the same as thevalue of indexvar is set to the highlighted color. Other objects in the part(which could be a Group) are changed to the unhighlighted color.


gms_hilite_cycle( )

Syntaxintgms_hilite_cycle (indexvar)


DescriptionThis function highlights an object in a Group or part using visibility. Theobject whose part index is the same as the value of indexvar is made visi-ble. Other objects in the part (which could be a Group) are made invisible.If the index variable is -1, all objects in the part or Group are made invisi-ble.

gms_hilite_edge( )

Syntaxintgms_hilite_edge (arrayvar, hc, uc, hw, uw)

int *arrayvar;/* array of highlight flags */int hc; /* highlighted edge color */int uc; /* unhighlighted edge color */double hw; /* highlighted edge width */double uw; /* unhighlighted edge width */

DescriptionThis function highlights each object of a Group or part using edge color andwidth. If arrayvar[part-index] is 1, the part is highlighted. Otherwise, thepart is unhilighted.


gms_hilite_edge_selobj( )

Syntaxintgms_hilite_edge_selobj (hc, uc, hw, uw)

int hc; /* highlighted edge color */int uc; /* unhighlighted edge color */double hw; /* highlighted edge width */double uw; /* unhighlighted edge width */

DescriptionThis function highlights using edge color and width,according to whether the object, or one of the partswithin the object, is equal to the currently-selected TextEdit object_ _selected_object.

gms_hilite_edge_var( )

Syntaxintgms_hilite_edge_var (indexvar, hc, uc, hw, uw)


int hc; /* highlighted edge color */int uc; /* unhighlighted edge color */double hw; /* highlighted edge width */double uw; /* unhighlighted edge width */

DescriptionThis function highlights objects in a Group or part using edge color andwidth. The object whose part index is the same as the value of indexvaris highlighted. Other objects in the part (which could be a Group) areunhighlighted. A value of -1 means that nothing is highlighted.

gms_hilite_flip( )


Syntaxintgms_hilite_flip (arrayvar)

int *arrayvar;/* array of highlight flags */

DescriptionThis function highlights each object of a Group, associating each object inorder with each element of the given array variable. Each object of theGroup must itself be an object

containing at least two parts. The function highlights by changing the visi-bility of each member of a two-part Group. The visibility of each is"flipped," that is, one or the other is visible. The first is visible (and thesecond part is invisible) if the associated variable is 0. The second part isvisible if the variable is 1.

gms_hilite_flip_var( )

Syntaxintgms_hilite_flip_var (indexvar)

int *indexvar;/* highlight variable */

DescriptionThis function highlights only one object in a Group. The object highlightedis the one whose part-index is equal to the value of indexvar. The objectmust contain at least two parts. The function highlights by changing thevisibility of the first two parts of the object. The visibility of each is"flipped," that is, one or the other is visible. The first part is visible (andthe second part is invisible) if the value of indexvar is 0. The second partis visible if indexvar is 1.


gms_hilite_fpercent1( )

Syntaxintgms_hilite_fpercent1 (variable, minval, maxval)

double *variable;/* fill value */double minval;/* minimum value of range */double maxval;/* maximum value of range */

DescriptionThis function performs a fpercent action given a range on the secondobject in a FILL PERCENT GISMO. The first object is assumed to be abackground object. variable is set to the relative fill position in the minvalto maxval range.

gms_hilite_percent1( )

Syntaxintgms_hilite_percent1 (variable, minval, maxval)

double *variable;/* position value */double minval;/* minimum value of range */double maxval;/* maximum value of range */

DescriptionThis function performs a move action given a range on the second objectin a SLIDER GISMO. This function moves the object so that the Refer-ence Point of the object is positioned at a place interpolated between theReference Points on the third and fourth object elements. The first objectelement is a background object and is always redrawn. variable is set tothe relative position in the minval to maxval range.


gms_hilite_percent2( )

Syntaxintgms_hilite_percent2 (var1, var2, minval, maxval)

double *var1; /* value for one end of slider */double *var2; /* value for other end of slider */double minval;/* minimum value of range */double maxval;/* maximum value of range */

DescriptionThis function performs a replace points action given a range on the sec-ond object in a SLIDER GISMO, setting the start and end to represent thefirst and second variables given as arguments. The result is that the sec-ond object in the SLIDER GISMO is sized to var1 and var2 to represent apercentage of the range defined by minval and maxval.

gms_hilite_vis( )

Syntaxintgms_hilite_vis (arrayvar)

int *arrayvar;/* array of highlight values */

DescriptionThis function highlights the members of a Group using visibility. EachGroup member must itself be an object containing at least two parts. Ifarrayvar[part-index] is 0, the first part of the Group member is visible andthe second part is invisible. Otherwise, the second part of the Groupmember is visible.


gms_hilite_vis_var( )

Syntaxintgms_hilite_vis_var (indexvar)

int *indexvar;/* index variable for part tohighlight*/

DescriptionThis function highlights the members of a Group using visibility. EachGroup member must itself be an object containing at least two parts. Thesecond part of the Group member whose part-index is equal to the value ofindexvar is made visible. For all other Group members, the first part isvisible.

gms_hilitescroll_array( )

Syntaxintgms_hilitescroll_array (cursorindex, hilitearray, hc,

uc)int *cursorindex;/* offset into string array */int *hilitearray;/* array of highlight flags */int hc; /* highlight color */int uc; /* unhighlight color */

DescriptionThe gms_hilitescroll_array( ) function is used to highlight selected linesof text.

The first argument, cursorindex, is an index (offset) into hilitearray.

The second argument, hilitearray, is an array of integers that specifieswhich lines of the array are highlighted. The value of the element hilitear-ray[cursorindex] is the highlight flag for the first line of text. An array ele-ment with a value of 1 indicates a highlighted line of text.

The third and fourth arguments are the colors with which to highlight andunhighlight the lines of text.


gms_hilitescroll_var( )

Syntaxintgms_hilitescroll_var (cursorindex, hiliteindex, hc,

uc)int *cursorindex;/* array index of the string

displayed in the first object of aGroup of Text Rectangles */

int *hiliteindex;/* array index of the currentlyhighlighted string */

int hc; /* highlight color */int uc; /* unhighlight color */

DescriptionThe gms_hilitescroll_var( ) function highlights one member of a Group of Text Rectangles. The member highlighted is theone whose part-index is equal to (*hiliteindex - *cursorindex). All othermembers of the Group are unhighlighted.

The third and fourth arguments are the highlight and unhighlight colors,respectively.

gms_popup_state_invoke( )

Syntaxintgms_popup_state_invoke (viewname, modelname,

resetflag)char *viewname;/* name of View in which to display

Model */char *modelname;/* name of Model to display */int resetflag;/* ON = reset State stack */


DescriptionThis function creates and activates an Instance of a generic State class. Italso sets the View name, adds the specified Model to the State Instance’sModels List, sets the State Instance’s popflag on, the freeflag on, theclearflag off, and sets the State Instance’s resetflag attribute. The reset-flag set to 1 causes the function gmsStResetToMark( ) to be called on thecurrent State. This deactivates States starting at the current State and upthe State tree until a marked State is encountered.

gms_quit( )

Syntaxintgms_quit( )

DescriptionThis function exits from SL-GMS by calling gmsExit( ).

gms_radio_array( )

Syntaxintgms_radio_array (callback, arrayvar, always_on)


int *arrayvar;/* array of values */int always_on;/* if set to 1, one element in

"arrayvar" is always on */

DescriptionThis function associates an array variable with a set of radio buttons.Each element of the array variable, arrayvar, corresponds to the part num-bers of the object (zero relative). It sets the value of no more than oneelement of arrayvar to 1 and sets all the remaining elements to 0 andpasses the callback function the index of the selected object, and the valuewhich is set for that member of the array variable.


If the always_on flag is set to 1, at least one element of arrayvar is alwaysset to 1. In addition, radio buttons are selected (or unselected) either by aloc_release Event (pressing and releasing the mouse button) or aloc_motion Event (dragging the mouse over the radio buttons) method.

If always_on is set to 0, radio buttons can only be selected (or unselected)by a loc_release Event. In addition, all radio buttons can be unselected atthe same time, one does not have to remain on.


gms_radio_var( )

Syntaxintgms_radio_var (callback, indexvar, always_on)


int *indexvar;/* index of selected object */int always_on;/* if set to 1, part index is always

passed to callback function */

DescriptionThis function associates an index variable, indexvar, with a set of radiobuttons. The function sets indexvar to the part-index of the selectedobject and passes it to the callback function as the first argument. Thevariable indexvar is set to -1 whenever none of the radio buttons areselected.

There are two ways for this to occur:

1. the mouse cursor is not on one of the radio buttons when thealways_on flag is set to 1 and the loc_motion method is beingused for button selection;

2. a "selected" radio button is "unselected" when always_on is setto 0.

If the always_on flag is set to 1, then at least one radio button is alwayson. In addition, radio buttons are selected (or unselected) either by a


loc_release Event (pressing and releasing the mouse button) or aloc_motion Event (dragging the mouse over the radio buttons) method.

If always_on is set to 0, radio buttons can only be selected (or unselected)by a loc_release Event. In addition, all radio buttons can be unselected atthe same time, one does not have to remain on.


gms_radioscroll_var( )

Syntaxintgms_radioscroll_var (callback, cursorindex,

hiliteindex, always_on,always_call)


int *cursorindex;/* array index of the stringdisplayed in the first object of aGroup of Text Rectangles */

int *hiliteindex;/* array index that corresponds tothe selected object in a Group ofText Rectangles */

int always_on;/* not used */int always_call;/* always call callback function */

DescriptionThe gms_radioscroll_var( ) sets the value of hiliteindex in response to alocator Event.

The first argument, callback, is an optional pointer to a user-defined call-back function.

The second argument, cursorindex, is an index (offset) into an array ofstrings. If the array is 100 lines long, and the scrolling window is display-


ing the last 25 lines of the array, then cursorindex would be equal to 74(cursor_index is zero relative).

The third argument, hiliteindex, can be thought of as an index (offset) intothe array of strings. It is the index of the string in an array of strings that ishighlighted when it is displayed in a scrollbox.

The fourth argument, always_on, is not currently used.

The fifth argument, always_call, is a flag that determines how and whenthe callback function (callback) is called. If always_call is set to ON (1),the callback function is always executed. If the flag is set to OFF (0), thecallback function is called only when the mouse button is released (i.e.,when gmsQEvCode(event) == G_LOC_RELEASE).


gms_screen_state_invoke( )

Syntaxintgms_screen_state_invoke (viewname, modelname,

resetflag, clearflag)char *viewname;/* name of View in which to display

Models */char *modelname;/* name of Model to display */int resetflag;/* ON = reset State stack */int clearflag;/* ON = clear View before displaying

Model */

DescriptionThis function creates and activates an Instance of a generic State Class.It sets the View name, adds the specified Model to the State Instance’sModel Name list, sets the State Instance’s popflag off, the clearflag to thespecified value, and the freeflag on. Setting the resetflag to 1 causes thefunction gmsStResetToMark( ) to be called on the current State, meaningthat States are deactivated starting at the current State and up the Statetree until a marked State is encountered.


This function returns 0 if it fails to activate because it could not find thenamed View or Model.

gms_slider_var1( )

Syntaxintgms_slider_var1 (callback, variable, minval,

maxval)int (*callback)( );/* user-defined callback

function */double *variable;/* value to set */double minval;/* minimum value of range */double maxval;/* maximum value of range */

DescriptionThis function sets a real variable to the value interpolated between the giv-en maximum and minimum, depending upon the position of the locatorEvent in relation to the third and fourth GISMO elements, described in thesection SLIDER GISMOs on page A-55.


gms_state_invoke( )

Syntaxintgms_state_invoke (classname, viewname, modelname,

resetflag, clearflag, popflag, datflag)char *classname;/* name of State class to instance

*/char *viewname;/* name of View in which to display

Models */char *modelname;/* name of Model to display */int resetflag;/* ON = reset State stack */


int clearflag;/* ON = clear View before displayingModel */

int popflag; /* value for State "popflag" */int datflag; /* value for State "datflag" */

DescriptionThe gms_state_invoke( ) function creates a new Instance of the Stateclass classname and installs it in the State Management Hierarchy. Theother arguments set the various State Instance attributes as described inthe section Attributes provided by the generic State Class on page E-4.

When the resetflag is set to 1, it causes the function, gmsStResetToMark() to be called on the event State (that State in which an event occurred).States are then deactivated, starting at the event State, up the State treeuntil a State instance marked with the gmsStMark function is encountered.The newly-created State Instance is installed there. If the event Statedoes not exist, the deactivation process starts at the current State. If thereis no marked State Instance, it resets to the Top State and installs the new-ly-created State Instance there.

NOTE: The gms_state_invoke( ) function can not be used to invoke anyof the Enhanced States described in the SL-GMS® State ClassLibrary Reference.

gms_state_pop( )

Syntaxintgms_state_pop ( )

This function deactivates the event State (i.e., that State in which an eventoccurred) if it exists, otherwise it deactivates the current State.

gms_state_return( )

Syntaxintgms_state_return ( )


DescriptionThis function deactivates the event State (i.e., that State in which an eventoccurred) if it exists, otherwise it deactivates the current State.

gms_stayon( )

Syntaxintgms_stayon ( )

DescriptionThe gms_stayon( ) function causes the _ _button_hilite variable to beset, and gmsDynUpdate( ) to be called on the object currently pro-cessed. After all DynProp actions for the selected object are performed,the _ _button_hilite variable is reset.

gms_stayon_call( )

Syntaxintgms_stayon_call (callback)


DescriptionThis function calls a user-defined function with "stayon" highlighting behav-ior on the selected object. The gms_stayon_call( ) function causes the_ _button_hilite variable to be set, and gmsDynUpdate( ) to be called onthe object currently processed. If a callback function is specified, it isinvoked. After the callback function returns, the _ _button_hilite variableis reset. If no callback function is specified, the _ _button_hilite variableis not reset until all DynProp actions for the selected object are performed.



gms_text_array_slider_hilite( )

Syntaxintgms_text_array_slider_hilite (cursorindex,

scrollbox_lines, first_index,last_index)

int *cursorindex;/* offset into string array */int scrollbox_lines;/* lines in scrollbox */int first_index;/* index of first line in box */int last_index;/* index of last line in box */

DescriptionThe gms_text_array_slider_hilite( ) function movesthe slider box in response to the value set by gms_text_array_slider_var(). It also resizes the slider box, so that its size corresponds to the percent-age of the string array which is displayed in the scrollbox window.

The first argument, cursorindex, is an index (offset) into the string array.

The second argument, scrollbox_lines, is the number of lines (Text Rect-angles in a Group) in the scrollbox.

The third and fourth arguments are the indices of the first and last elementsin the string array (zero relative).

gms_text_array_slider_var( )

Syntaxintgms_text_array_slider_var (callback, cursorindex,

maxlines, first_index, last_index)int (*callback)( );/* user-defined callback

function */int *cursorindex;/* offset into string array */int maxlines; /* lines in scrollbox */int first_index;/* index of first string array

element */


int last_index;/* index of last string array element*/

DescriptionThe gms_text_array_slider_var( ) function responds to a locator press onthe slider and sets the variable cursorindex to the index in the string arrayof the first line in the scrollbox. The first argument, callback, is an option-al pointer to a user-defined callback function.

The second argument, cursorindex, is an index (offset) into the stringarray.

The third argument, maxlines, is the maximum number of visible lines(Text Rectangles in a Group) in the scrollbox.

The fourth and fifth arguments are the indices of the first and last elementsin the string array.


gms_textentry_array( )

Syntaxintgms_textentry_array (callback, arrayvar, maxchars,

type)int (*callback)( );/* user-defined callback

function */int *arrayvar;/* array for entered data */int maxchars; /* maximum number of input characters

allowed */int type; /* a valid data type as described on

page A-62*/

DescriptionThis function handles a Group of textentry objects that is associated withan array variable. On a locator Event, the selected object within the Groupis made the current echo object, and all subsequent key events are


absorbed except for non-printable ASCII keys. On a carriage-return, thevariable is updated with the entered value and the specified callback iscalled, if it exists, passing it the current textedit object id and the address ofthe variable. Finally, the next object in the Group is made the current tex-tedit object.

CallbackPages A-63 through A-65 provide a description of the callback function.

gms_textentry_var( )

Syntaxintgms_textentry_var (callback, variable, maxchars, type)

int (*callback)( );/* user_defined callbackfunction */

int *variable;/* object for entered data */int maxchars; /* maximum number of input characters

allowed */int type; /* a valid data type as described on

page A-71*/

DescriptionThis function accepts input for a single Text Rectangle object.

CallbackPages A-72 through A-74 provide a description of the callback function.


gms_textload_array( )

Syntaxintgms_textload_array (arrayvar, maxchars, type)

int *arrayvar;/* pointer to array of strings */int maxchars; /* maximum number of characters per

string in "arrayvar" */int type; /* a valid array data type as

described on page A-62*/

DescriptionThis function sets the text content for of each member of a Group of TextRectangle objects with the content of the given array variable. Valid val-ues for type are described on page A-62.

gms_textscroll_array ( )

Syntaxintgms_textscroll_array (arrayvar, indexvar, maxchars,

maxlines)int *arrayvar;/* pointer to array of strings */int *indexvar;/* offset into "arrayvar" */int maxchars; /* maximum number of characters per

line */int maxlines; /* maximum number of lines */

DescriptionThe gms_textscroll_array( ) function is used to load a Group of TextRectangle objects with strings from an array.

The first argument, arrayvar, is a pointer to an array of strings.

The second argument, indexvar, is a pointer to a variable that is used asan offset into the array. The Group of Text Rectangles is loaded fromarrayvar beginning with arrayvar[indexvar].


The third argument, maxchars, is the maximum number of characters perline.

The fourth argument, maxlines, should be set to the maximum number oftext lines that can be displayed in the GISMO, that is, the number of TextRectangle objects in the Group.

gms_textscroll_lines ( )

Syntaxintgms_textscroll_lines (arrayvar, indexvar, maxlines,

numlines)int *arrayvar;/* pointer to array of strings */int *indexvar;/* offset into "arrayvar" of first

string visible in a Group of TextRectangles */

int maxlines; /* maximum number of lines in Group */int numlines; /* number of lines to scroll */

DescriptionThe gms_textscroll_lines( ) function is used to scroll through an array ofstrings displayed in a Group of Text Rectangle objects numlines at a time.

The first argument, arrayvar, is a pointer to an array of strings.

The second argument, indexvar, is a pointer to a variable that is used asan offset into the array. In response to a locator press, the value of num-lines is added to indexvar.

The third argument, maxlines, should be set to the maximum number oftext lines that can be displayed in the GISMO,that is, the number of Text Rectangle objects in the Group).

The fourth argument, numlines, is the number of lines to scroll. numlinescan have a negative value. In the on-line examples in the demo directory,this function is used to scroll one line at a time, that is, numlines isrenamed to the value 1.


gms_toggle_array( )

Syntaxintgms_toggle_array (callback, arrayvar)

int (*callback)( );/* user_defined callbackfunction */

int *arrayvar;/* array of ints*/

DescriptionThis function toggles each element in an array variable between the values0 and 1.


gms_togglescroll_array( )

Syntaxintgms_togglescroll_array (callback, cursorindex,

hilitearray, always_on)int (*callback)( );/* user-defined callback

function */int *cursorindex;/* offset into string array */int *hilitearray;/* array of highlight flags */int *always_on;/* not used */

DescriptionThe gms_togglescroll_array( ) function sets array element values in hilit-earray based upon which Text Rectangle was clicked with the mouse.

The first argument, callback, is an optional pointer to a user-defined call-back function.

The second argument, cursorindex, is an index (offset) into the array.


The third argument, hilitearray, is an array of integers that specifies whichlines of the array are highlighted. An array element with a value of 1 indi-cates a highlighted line of text.

The fourth argument, always_on, is currently not used.



Reserved variable names for GISMO DynProps

The reserved variable names set or used by SL-GMS functions andSL-GMS GISMO Action Functions are provided in the following table.

Reserved Variable Names for GISMO DynProps

Variable Type Description

__button_hilite int set to 1 if highlighting is to occur; set to 0 to unhighlight

set by:gms_flash_call( )gms_stayon_call( )

__button_index int part number in Group or Model selected; set to -1 if no part currently selected

set by:gms_flash_call( )gms_stayon_call( )

__locator id Locator which picked the GISMO

used by:gms_call( )gms_call1( )gms_color_select( )gms_flash_call( )gms_fpercent_var1( )gms_radio_array( )gms_radio_var( )gms_slider_var1( )gms_stayon_call( )gms_textentry_array( )gms_toggle_array( )

__self id set to the object owning the dynamic description


Any variable name preceded by two underscores does not appear inSL-GMSDraw’s Object Renamed Variables window.

__selected_object id current Text-entry object

set by:gmsStTextEditObj( );gms_textentry_array( )gms_textentry_var( )

used by:gms_hilite_color_selobj( )

button_state int Provides the means for automatic, persistent button highlighting. This variable has no effect unless it is renamed.If it is renamed so that the state name appears at the beginning of the name string, followed by underscore; i.e.,<state name>_button_stateSL-SMS automatically sets this variable to: 0 when state is not active 1 when state is currently activeIf the button_state variable is renamed to any other name, SL-SMS ignores it.

timeofday string set to system time as hh:mm:ss upon gmsDynInit( ) and updated once a second

Reserved Variable Names for GISMO DynProps(continued)

Variable Type Description


Appearance variables for GISMO DynProps

The tables in this section summarize the appearance RenamedVars for the"f" style (flat look) and "m" style (Motif look-alike) GISMOs.

f Table Appearance Variables for f_* GISMOs (flat look)


button_label renamed to a string constant or variable

edge_hicolor renamed to an integer constant or variable; the edge highlight color

edge_uncolor renamed to an integer constant or variable; the edge unhighlight color

edge_width renamed to an integer constant or variable; the edge width

fill_hicolor renamed to an integer constant or variable; the fill highlight color

fill_uncolor renamed to an integer constant or variable; the fill unhighlight color

text_font renamed to an integer constant or variable; the font index used to display button_label

text_height renamed to a numeric constant or variable

text_hicolor renamed to an integer constant or variable; the text highlight color

text_prec renamed to an integer constant or variable; the font type used to display button_label

text_uncolor renamed to an integer constant or variable; the text unhighlight color


m TableAppearance Variables for m_* GISMOs (Motif look-alike)


button_label renamed to a string constant or variable

direction (ma_call and ma_popup only) renamed to an integer constant or variable; 0 = up arrow, 1 = down arrow, 2 = right arrow, 3 = left arrow

edge_width renamed to an integer constant or variable; the width of highlight shadows

text_align_x renamed to an integer constant or variable; for left (1), center (2), or right (3) horizontal alignment of text

text_height renamed to a numeric constant or variable


Appearance of BUTTON Type GISMOs

DimensionsThe "m" and "f" series of GISMOs have fixed dimensions. These can bechanged by scaling. SubModels can be scaled by setting the Scaleparameters in the SubModel Control Panel or by scaling the Instance.

Figure A-2The "state_1" object

Scaling can be either equal or unequal in the x and y dimensions. Textheight will be scaled also, therefore, some adjustment of this appearancevariable may be necessary to produce the desired results.

Appearance

"f" StyleThe appearance of the "f" style BUTTON type GISMO is createdwith two Filled Text Rectangles objects called state_1 andstate_0. The state_1 object controls the appearance of thebutton when it is selected. The state_0 object controls theappearance of the button when it is unselected.

The state_1 object, shown in Figure A-2, is a Filled TextRectangle created with the following SL-GML code. The f_callGISMO will be used for this example.

state_1: ftrect 0 0 10 4 "f_call"

f_call


Figure A-3The "state_0" object

The f_call GISMO has the following DynProp attached to it:

DynProp for the "state_1" ("selected") object


button_label= *

stext button_label "%s"

when the variable button_label is initialized or changed, the text "f_call" is replaced with the text string assigned to the variable button_label

text_hicolor= * tcolor text_hicolor

when the variable text_hicolor is initialized or changed, the Text color (tcolor) is the value assigned to text_hicolor

fill_hicolor= *

fcolor fill_hicolor

when the variable fill_hicolor is initialized or changed, the fill color (fcolor) of the Filled Text Rectangle is the value assigned to fill_hicolor

f_call


The state_0 object, shown in Figure A-3, is a Filled TextRectangle created with the following SL-GML code:

state_0: ftrect 0 0 10 4 "f_call"

The state_1 and state_0 objects are then grouped together, asshown in Figure A-4 (DynProps for state_1 and state_0 not

shown). The order of the grouped objects is important; thestate_1 object should be selected first, then the state_0 object.

groupstate_1: ftrect 0 0 10 4 "f_call"state_0: ftrect 0 0 10 4 "f_call"

endg

Figure A-4The Group of "state_1" and "state_0"

edge_hicolor= *

ecolor edge_hicolor

when the variable edge_hicolor is initialized or changed, then the edge color (ecolor) is the value assigned to edge_hicolor

__button_hilite || button_state= 1

vis 1redraw

= 0vis 0

when the value of the logical "either _ _button_hilite1 or button_state" is true, the state_1 object is made visible and redrawn. When the value of the logical is false, the state_1 object is invisible

1. __button_hilite is set to 1 (true) by the gms_flash( ) functionwhen the GISMO is selected, on a locator press, and then resetback to 0 (false) on a locator release.

DynProp for the "state_1" ("selected") object(continued)


f_call


The DynProp shown below is attached to it.

The DynProp shown below is attached to the Group. TheDynProp is attached to the Group because these variables arecommon to both the selected and the unselected state.

DynProp for the "state_0" ("unselected") object



vis 1redraw

= 1vis 0

when the value of the logical "either _ _button_hilite1 or button_state" is false, the state_0 object is made visible and redrawn. When the value of the logical is true, the state_0 object is invisible

1. __button_hilite is set to 1 (true) by the gms_flash( ) function whenthe GISMO is selected, on a locator press, and then reset back to 0 (false)on a locator release.

button_label= *


when the variable button_label is initialized or changed, the text "f_call" is replaced by the text string assigned to the variable button_label

text_uncolor= *

tcolor text_uncolor

when the variable text_uncolor is initialized or changed, the text color (tcolor) is the value assigned to text_uncolor

fill_uncolor= *

fcolor fill_uncolor

when the variable fill_uncolor is initialized or changed, the fill color (fcolor) of the Filled Text Rectangle is the value assigned to fill_uncolor

edge_uncolor= *

ecolor edge_uncolor

when the variable edge_uncolor is initialized or changed, the edge color (ecolor) is the value assigned to edge_uncolor


"m" StyleThe appearance of the "m" style BUTTON type GISMO is alsocreated with two objects called state_1 and state_0. Each ofthese objects is a Group that contains a Filled Text Rectangleobject and two Polyline objects. The state_1 object controls theappearance of the button when it is selected. The state_0object controls the appearance of the button when it isunselected.



__button_hilite || button_state= *

batcherase

when the value of the logical "either _ _button_hilite or button_state" is initialized or changed (either true or false), a batcherase and display is performed on the Group.

text_height= *

theight text_height

when the variable text_height is initialized or changed, the height of the Text (theight) is equal to the value assigned to the variable text_height

text_font= *

tfont text_font

when the variable text_font is initialized or changed, the Text font (tfont) is equal to the value assigned to the variable text_font

text_prec= *

tprec text_prec

when the variable text_prec is initialized or changed, the precision of the Text (tprec) is equal to the value assigned to the variable text_prec

edge_width= *

ewidth edge_width

when the variable edge_width is initialized or changed, the edge width of the Filled Text Rectangle (ewidth) is equal to the value assigned to the variable edge_width


The state_1 object is a Group that consists of a Filled TextRectangle object, named plate_1, and two Polyline objects,named upper_1 and lower_1, created with the SL-GML codeshown below. The m_call GISMO will be used for this example.Only the fill color (fcolor), edge color (ecolor), and edge style(estyle) variables will be shown, since these variablesdifferentiate the appearance of the different objects.

state_1: groupfcolor 14ecolor 0estyle 0plate_1: ftrect 0 0 10 4 "m_call"fcolor 0ecolor 15estyle 1

upper_1: line 0 0 0 4 10 4ecolor 12lower_1: line 0 0 10 0 10 4

endg

Figure A-5Parts of the "state_1" Group

m_call

m_call


state_1


The plate_1 object has a DynProp attached to it as shownbelow.

The state_1 Group also has a DynProp attached to it.

The state_0 object is a Group that consists of a Filled TextRectangle object, named plate_0, and two Polyline objects,named lower_0 and upper_0, created with the following SL-GMLcode. Only the fill color (fcolor), edge color (ecolor), and edge

DynProp for the "plate_1" object


button_label= *


when the variable button_label is initialized or changed, the text "m_call" is replaced by the text string assigned to the variable button_label

text_align_x= *

talign text_align_x 3

when the variable text_align_x is initialized or changed, the text alignment (talign) is the value assigned to text_align_x 3

DynProp for the "state_1" Group ("selected")



vis 0= 1

vis 1redraw

when the value of the logical "either _ _button_hilite or button_state" is false, the state_1 object is invisible. When the value of the logical is true, the state_1 object is made visible and redrawn


style (estyle) variables will be shown, since these variablesdifferentiate the appearance of the different objects.

state_0: groupfcolor 13ecolor 0estyle 0plate_0: ftrect 0 0 10 4 "m_call"fcolor 0ecolor 15estyle 1lower_0: line 0 0 10 0 10 4ecolor 12upper_0: line 0 0 0 4 10 4

endg

Figure A-6Parts of the "state_0" Group


state_0

m_call

m_call


The plate_0 object has a DynProp attached to it as shown below.

The state_0 Group also has a DynProp attached to it.

The state_1 and state_0 objects are then grouped together, asshown in Figure A-7 (DynProps for state_1, plate_1, state_0, andplate_0, and other variables are not shown).

groupstate_1: group

plate_1: ftrect 0 0 10 4 "m_call"upper_1: line 0 0 0 4 10 4

DynProp for the "plate_0" object


button_label= *


when the variable button_label is initialized or changed, the text "m_call" is replaced by the text string assigned to the variable button_label

text_align_x= *

talign text_align_x 3

when the variable text_align_x is initialized or changed, the text alignment (talign) is the value assigned to text_align_x 3

DynProp for the "state_0" object ("unselected")



vis 1redraw

= 1vis 0

when the value of the logical "either _ _button_hilite or button_state" is false, the state_0 object is made visible and redrawn. When the value of the logical is true, the state_0 object is invisible


lower_1: line 0 0 10 0 10 4endgstate_0: group

plate_0: ftrect 0 0 10 4 "m_call"lower_0: line 0 0 10 0 10 4upper_0: line 0 0 0 4 10 4

endgendg

The DynProp, shown at the bottom of the page, is attached tothe Group. The DynProp is attached to the Group becausethese variables are common to both the selected and theunselected state.

Figure A-7The Group of "state_1" and "state_0"



__button_hilite || button_state= *

batcherase

when the value of the logical "either _ _button_hilite or button_state" is any value (either true or false), a batcherase and display is performed on the Group

m_callm_call


text_height= *

theight text_height

when the variable text_height is initialized or changed, the height of the Text (theight) is equal to the value assigned to the variable text_height

edge_width= *

ewidth edge_width

when the variable edge_width is initialized or changed, the edge width (ewidth) of the Filled Text Rectangle and Polylines are equal to the value assigned to the variable edge_width

DynProp for the Group(continued)



B

Version 6.2a- 26 M

Glossary

actions The changes an object makes in dynamic descriptions are referred to as actions. These actions represent changes in an object’s attributes, position, or orientation.

attributes The qualities an object has are referred to as attributes. For example, a Text object may have size, alignment, font, path, height, and color. A Filled Circle has fill color, fill style, fill pattern, edge color, edge width, edge style, fill direction, and fill percent. In SL-GMS, objects are created with a set of default attributes. The default attributes, or particular attributes for an object or List of objects, may be modified.

Bitmap A special file that contains a raster image of graphics is called a Bitmap. This raster image is a copy of dots (pixels or sixels) displayed on part of a screen. Bitmaps are sometimes used to print a copy of a screen. A Bitmap may be used as an object with some workstations.

Boolean Relating to symbolic relationships implied by the logical operators AND, OR, and NOT.

button A button is a word, symbol, or box selected by a mouse pick which controls an application. A button is an iconic representation of a physical button or control mechanism.

Control Panel A Control Panel is a collection of buttons in a graphical display. The SL-GMSDraw interface uses Control Panels.

Datasource A Datasource is a set of variable definition objects and methods used to connect graphical objects with external sources of data or internal variables.

SL-GMS Reference B-1ay 2006

Device Coordinates Device Coordinates are coordinates used by the actual physical display device, and are usually in pixels. SL-GMS automatically maps Normalized Device Coordinates to Device Coordinates.

display dynamics Display dynamics describe behaviors an object performs to reflect the value of application variables. See also input dynamics, dynamics.

dynamic description Text in a syntax recognized by SL-GMS that specifies a change in the appearance of an object in response to a change in an application variable, or an action to be taken in response to input events for the object.

dynamics Dynamics describe behaviors an object follows to reflect external events. Dynamics, or dynamic descriptions, spell out how an object, or Group of objects, changes when certain external values change. Dynamic descriptions are added by making selections in a menu or by entering keywords which describe the dynamics.

DynProp A collection of dynamic descriptions attached to an object is referred to as an object’s DynProp (short for Dynamic Property).

Event An Event is something which occurs on a system, and that is related to a program but not caused by it. Input Events are triggered by mouse or button clicks, keyboard entry, window resizing, and so on. Timer Events are generated by the system clock.

GISMO Acronym for Graphical Interactive Screen Management Object. A GISMO is a dynamic object that responds to input Events, such as mouse clicks and key presses.

Group Several objects united into a single object is called a Group. Grouping allows more than one object to be collected within a Model and treated as a single entity. Groups are also objects, and each Model may have many Groups or no Groups.

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

input dynamics Dynamics which allow an object to respond to input Events, such as mouse clicks and key presses, are input dynamics. Input dynamic descriptions are introduced in an object’s DynProp with the "#" symbol.

Instance The object used to include a SubModel in a Model is called an Instance. An Instance can be thought of as a copy of a SubModel positioned once within another Model. For example, if a Model of a meter is created, it can be used as a SubModel, and many Instances can be created resulting in other meters in the Model.

message In object-oriented programming, a message is a request for an object to execute one of its methods.

method In object-oriented programming, a method is a procedure which operates only on objects of a particular Class. Methods are executed as a result of a message being sent to an object of that Class.

Model Models are collections of objects, such as Lines, Circles, Text, Graphs, and other Models. For example, a Model may contain the graphical objects which comprise a control panel, a monitoring system, or a floor plan. A Model might also consist of only a few objects which make up a component like a meter, gauge, or valve. Models may be used as objects in other Models.

NDC Normalized Device Coordinates specify a fractional portion of another coordinate space. In SL-GMS, Normalized Device Coordinates are used to define the NDC-extent of a View. The intended range of NDCs is from 0.0 to 1.0.


object A graphical entity, such as a Rectangle, Circle, Filled Rectangle, Line, or Text is called an object. Objects can be thought of as the organization which makes the dots on the screen work together to comprise a Circle, Rectangle, or the word "Next." An object can be moved around, changed, or removed. Objects include information about the qualities particular to that object, for example, its color, edge style, or whether it is filled with a color or pattern.

object-oriented Object-oriented programming is a programming and design methodology in which the system to be constructed is modelled as a collection of objects which interacts with one another by sending messages.

Object Reference Point: See Reference Point.

Operation Reference Point: See Reference Point.

output dynamics See display dynamics.

owner Upward links in a Model for a Graphical Primitive object. For example,

parts The term parts is used when referring to the objects collected as a Model. The parts of a Model are its objects.

Pull-Down Menu Menus in SL-GMSDraw that become visible only after picking their title bar are called Pull-Down Menus. Pull-Down Menus present a wide variety of options and activities without using any screen area until they are

Group or Model

object


selected. Once an option is chosen, the Pull-Down Menu disappears.

Reference Point Object Reference Point:This is the permanent Reference Point that is saved with the object. It exists only if set on an object using the Point Pull-Down Menu or by a program call to the function gmsRefPoint( ).

Operation Reference Point:This is a transient (temporary) Reference Point created to complete operations, such as rotate, copy, move, or scale. Following the operation, it no longer exists.The point selected to serve as Operation Reference Point depends upon the Mode, as set using the Point Selection Control icons:

• In CENTER Mode with a single object, the Operation Reference Point is the Object Reference Point, if one exists; otherwise, it is the center of the extent rectangle.

• In CENTER Mode with a selected Group of objects, the Operation Reference Point is the center of the extent rectangle.

• In POINT Mode, if a location is picked by a mouse click, the Point in the object’s extended Point List closest to the Point picked is taken as the Operation Reference Point; if an object is selected by means other than a mouse click, for example, with the All option in the Select submenu of the Edit Pull-Down Menu, the Operation Reference Point becomes the first Point in the extended Point List of the first object in the Select List.

Select List When working with SL-GMSDraw, the user may desire some change to affect a List of objects. This List is called the Select List. Objects are added to the Select List by clicking on each of them.


State class In SL-SMS, a State Class serves as a template for the creation of State Instances. A State Class defines the methods that are called when an Event occurs in a State Instance.

State Instance A State Instance is essentially a copy of a State Class. A State Instance maintains a List of the particular Models associated with it, as well as other information necessary for displaying and animating its Models.

SubModel When a Model is as used a part in another Model, it is called a SubModel. SubModels are virtually identical to Models; the only thing which distinguishes SubModels from Models is that SubModels are used as a part in a Model.

TextEdit object A TextEdit object is a Text or Filled Text Rectangle object used to echo characters entered from the keyboard.

Transformation object A Transformation object is a two-dimensional 2x3 matrix used to perform translation, scaling, and rotation of objects.

UserData Words or numbers can be associated with objects using UserData. UserData may contain any type of information entered from the keyboard. The information in UserData may be used by the application program in any manner desired. SL-GMS does not utilize the UserData field (except in a SL-GMS Mapping application), but rather maintains it for use by the application program.

UserWord A single integer can be associated with objects using UserWord. The information in UserWord may be used by the application program in any manner desired. SL-GMS does not utilize the UserWord field (except in a SL-GMS Mapping application), but rather maintains it for use by the application program.

VarDef A VarDef is a Variable Definition object created by the functions, gmsVarDefine( ), gmsStVarDefine( ), and gmsVarDefineNoTable( ).


View A View is an SL-GMS object that defines which portion of a Model is displayed and where it is displayed in a window. A View consists of a WC-extent and a NDC-extent.

WC-entent A View is defined by two extents, one of which is the WC-extent. The WC-extent of the View determines the portion of the World Coordinate space to display. Only those portions of a Model that fit within the View’s WC-extent are displayed.

window A window is a rectangular area of the screen used for output of graphics and text which is independently managed for clipping, popping, and so on.

Workstation See Workstation/Window.

Workstation/Window A Workstation/Window is a device, such as a video display or printer, used for displaying graphics. A Workstation/Window may also be a window on such a device.

World Coordinates The coordinate system used in SL-GMS to specify the location and size of graphical objects is measured in World Coordinates. The World Coordinate System is centered at the origin (0.0, 0.0), and extends from(-32768., -32768.) to (32767., 32767.).


C

Version 6.2a- 26 M

SL-GMS Interface with the X Toolkit and X Windows

Introduction

The SL-GMS interface to the X Toolkit (Xt) and X Windows (X) has twocomponents:

• The creation or use of an X window or Xt-based widget in whichto draw dynamic graphics

• The X event gathering — either SL-GMS gathers X events or anapplication X event-loop function external to SL-GMS does,which then either dispatches or passes the X events to SL-GMS

The SL-GMS interface to Xt (GWS-XT) and X (GWS-X) are contained intwo separate interface libraries, the gwsxt and gwsx libraries, respective-ly. When using SL-GMS to draw dynamic graphics in an Xt-based widget (aMotif or OLIT widget, for example), the GWS-XT interface should be used.When drawing SL-GMS dynamic graphics in an X window, the GWS-Xinterface should be used. In both the GWS-XT and GWS-X interfaces,SL-GMS can either gather X events or it can receive them from an applica-tion X event-loop gathering function external to SL-GMS. Both the GWS-XTand GWS-X interfaces and the process of X event gathering are describedbelow.

The SL-GMS / Xt Interface

SL-GMS can either create or use an existing X window for dynamic graph-ics; however, SL-GMS cannot create an Xt-based widget in which to drawdynamic graphics. If SL-GMS dynamic graphics are to be used in anXt-based widget (a Motif or an OLIT widget, for example), the widget mustbe created outside of SL-GMS. SL-GMS is informed of the Xt "id" of theXt-based widget in which to draw dynamic graphics in the gmsWorkst( )function call, which creates the SL-GMS Workst object. The Xt "id" of theXt-based widget (which is an unsigned long integer) is passed in as astring argument to gmsWorkst( ). The wind argument to gmsWorkst( ) isa

SL-GMS Reference C-1ay 2006

pointer to a character string that contains the Xt "id" of the widget. Simplyuse the sprintf( ) function to write the Xt "id" to a character string in memo-ry and pass a pointer to the string as the wind argument to gmsWorkst( ).Please note that the conn argument (used for specifying the X Displayconnection name) does not need to be specified when using GWS-XT,since SL-GMS is not opening a Display connection but will use the oneassociated with the specified widget.

SL-GMS may be used with an application Xt event-loop function external toSL-GMS through the use of the function, gmsExternalEventLoopFlag( ),which allows the user to specify that SL-GMS is not to gather X events.Instead, an application Xt event-loop function external to SL-GMS gathersthe X events. The X events are then dispatched from the application’s Xtevent-loop function directly to SL-GMS. For example, this is the situationwhen using the XtAppMainLoop( ) Xt event gathering function or a similarXt event gathering function which dispatches all X events to clients. If theapplication’s Xt event-loop function does not dispatch all X events to cli-ents, the use of an additional function, gmsProcessLowEvent( ), is neces-sary to pass the X events from the application’s Xt event-loop function toSL-GMS. This situation arises if there is a need for an application to query,monitor, and/or filter X events instead of simply dispatch all X events to anyclient that has indicated an interest in the relevant X event type. In thiscase, a customized Xt event-loop function will be used in the application inplace of XtAppMainLoop( ).

Alternatively, the SL-GMS Xt event-loop function, gmsMainLoop( ), maybe used to gather and dispatch all X events, much the same asXtAppMainLoop( ) does. The only difference between usinggmsMainLoop( ) and XtAppMainLoop( ) is in what controls the X eventgathering and dispatching. If gmsMainLoop( ) is used, SL-GMS controlsthe X event gathering and dispatching. If an application Xt event-loop func-tion external to SL-GMS such as XtAppMainLoop( ) is used, the control ofthe X event gathering and dispatching is under the application code. Forexample, many Motif Graphical User Interface (GUI) builder tools generatea main( ) function for the application which calls XtAppMainLoop( ) or asimilar function for X event-loop gathering and dispatching. The use ofSL-GMS with an application Xt event-loop function external to SL-GMSallows for easy integration of a Motif interface generated by a Motif GUIbuilder tool with SL-GMS.

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

The SL-GMS / X Interface

As mentioned above, SL-GMS can either create or use an existing X win-dow for dynamic graphics. If the gmsWorkst( ) function is called with a nullwind argument, SL-GMS will create an X window for drawing dynamicgraphics. The conn argument will be used as the name of an X Displayconnection to open if it is specified. If the conn argument is null, the DIS-PLAY environment variable will be used to determine the name of the Xdisplay connection to open.

If SL-GMS dynamic graphics are being used in an existing X window, boththe conn and wind arguments must be specified. The "id" of the X windowand the "id" of the associated X Display connection (both being unsignedlong integers) are passed in as the wind and conn arguments, respective-ly, to gmsWorkst( ). Both of these arguments to gmsWorkst( ) are point-ers to character strings that contain the appropriate "id". The sprintf( )function is used to write each "id" to different character strings in memoryand pass a pointer to the appropriate character string as the conn or windargument to gmsWorkst( ).

As mentioned above for the Xt case, SL-GMS may be used with an Xevent-loop external to SL-GMS through the use ofgmsExternalEventLoopFlag( ), which allows the user to specify thatSL-GMS is not to gather X events. Instead, an application X event-loopfunction external to SL-GMS gathers the X events; however, there is a sig-nificant difference when using X as opposed to Xt. Under X (Xlib) asopposed to Xt, the application’s X event-loop function will not dispatch Xevents to clients. As a result, a call to gmsProcessLowEvent( ) must beadded to the application’s X event-loop function to pass X events toSL-GMS. The easiest way to do this is to add a gmsProcessLowEvent( )function call to the application’s X event-loop so that every X event will bepassed to SL-GMS. The return value of gmsProcessLowEvent( ) will indi-cate whether or not SL-GMS was interested in the X event. This way, theuser does not

need to try to determine in the application’s X event-loop function whetheror not SL-GMS has an interest in an X event.

Alternatively, the SL-GMS X event-loop function, gmsMainLoop( ), may beused to gather X events. Some GUI builder tools generate Xlib codeinstead of Motif and Xt code. In this case, the generated code will probablycontain an X event-loop function that the application expects to use to


interact with the various parts of the GUI. This is an example of the situa-tion where the use of an application X event-loop function external toSL-GMS is mandatory. The application’s X event-loop should be modifiedto include a call to gmsProcessLowEvent( ) so that SL-GMS can receiveand process X events gathered by the X event-loop function.


D

Version 6.2a- 26 M

Model Utilities

Introduction

SL-GMS provides the utilities for converting Model files from one format toanother, and for generating localization files from Models. The Model con-version utilities are: gm1 (gm<one>), gm2, m1g, m1m2, and dxf2g. Thegenlocfile utility generates localization files from Models. These utilitiesare found in the SL-GMS bin directory, along with the SL-GML andSL-GMSDraw executables. Note that when processing files with these con-version utilities, errors are not reported.

Utility Command Line Description

gm1 [-loc lang_name] <filename>.g

convert .g to .m1

gm2 [-loc lang_name] <filename>. g

convert .g to .m2

m1g <filename>.m1 convert .m1 to .g

m1m2 <filename>.m1 convert .m1 to .m2

dxf2g ... <infile[ .dxf]> [modelname]

(See page D-4 for a full description of arguments)

convert AutoCad .dxf files to SL-GMS .g files

genlocfile -loclang_name [-p prefix][-wc] [modelname](See page D-15 for a full description of arguments)

generate localization file commands for "internationalized" objects in Models

SL-GMS Reference D-1ay 2006

Basic Model Conversion Utilities

SL-GMS provides a set of SL-GMS scripts that are used to convertSL-GMS Model files between ASCII, binary, and contiguous binary formats.The scripts gm1, gm2, m1g, and m1m2, invoke SL-GML with the -l (letter"l") option. Hence these scripts may be used to convert ".g" files to ".m1" or".m2" files in any order.

When editing a Model file that contains comments, the sequence gm1"<filename>.g", m1g "<filename>.m1" will destroy the comments in theoriginal ".g" file. This is to be expected and is a result of anysource-to-binary to source translation.

When a Model has an external SubModel in its SubModels List, a referenceto that SubModel remains in the ".m1" file, even if the Model has noInstances of the SubModel. However, if the Model is saved as a ".g" file andconverted to an ".m1" using the gm1 conversion utility, the reference to theexternal SubModel is lost.

The following commands can also be used with wildcard substitution:

gm1 *.g

m1g *.m1

gm2 *.g

m1m2 *.m1

More information about the commands involving ".m2" files is provided inChapter 11 — Performance.

While there is no dedicated script to convert from ".m2" to ".g" or ".m2" to".m1" files, SL-GML may be used to retrieve an ".m2" file, and save it as a".g" or ".m1". Under these conditions, original information is lost when con-verted back to the ".g" or ".m1" form. The current release of SL-GMS doesnot yet provide scripts to convert backwards because the ".m2" files aremost appropriately used for performance optimization during run timescreen loading.

It is important that ".m2" files be updated, using the m1m2 script for exam-ple, after editing ".m1" files because States automatically look first for".m2" files when activated. It may appear that changes made to an ".m1"file were not saved when actually they were and a corresponding ".m2" fileexists for an older version of the ".m1" file.

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

Localization A -loc option of the gm1 and gm2 conversion scripts allow them to applylocalization files to Models as they are converted from ".g" to ".m1" or ".m2"format. Each ".g" file can optionally have a corresponding localization file. Ifthe corresponding localization file exists for the ".g" Model, it will be used tolocalize the ".g" Model during the conversion. The gm1 and gm2 conver-sion scripts generate a localization file name for each ".g" file by concate-nating the name of the ".g" file (without the ".g" suffix), an "_" character,lang_name, and a ".lc" suffix.

For example, if the name of a ".g" file is "menu.g" and lang_name is "ja",the name of the corresponding localization file will be "menu_ja.lc".

To convert "menu.g" to "menu.m1" while applying the localization file"menu_ja.lc":

gm1 -loc ja menu.g

To convert all ".g" files in the current directory to ".m1" files and apply allcorresponding localization files with "lang_name" of "ja":

gm1 -loc ja *.g

Further information about localization files is provided in the International-ization — localization filessection of the SL-GMS Function Reference.


AutoCAD dxf2g ".dxf" file converter

The SL-GMS utility dxf2g converts AutoCAD ".dxf" (Data Exchange For-mat) files to SL-GMS ".g" (ASCII) Model files.

Usage: dxf2g [ -a | -f ] [ -c | -cf<file> ] [ -d<val> ] [ -e] [ -t<val> ] <file>[.dxf]

Convert the ".dxf" file to a series of SL-GMS format ".g" files, one ".g" filefor each active layer in the ".dxf" file plus a “.g” file for each Submodel.Each output layer file has the name "<file>_<lyr_name>.g", except for"<file>_subs.g", which contains all the "BLOCK" (SubModel) definitions.SubModels are external; the string “_<file>” is appended to the name ofeach.

If no flags or arguments are given, the usage summary is printed.

NOTE: All ".g" files are created in the directory where dxf2g is executed.

The dxf2g flags have the following meaning:

Flag Description

-a AutoCAD coordinates to be used without change1

-f Fit AutoCAD display to SL-GMSDraw default window (72 x 54)

-cap Approximate AutoCAD colors 1 – 255 with SL-GMS colors 0 – 31

-cf<file> Approximate AutoCAD colors with the color defs in <file>2

-d<value> Divide all x and y values by the <value> given. Default is 1.0.

-e Use $EXTMIN and $EXTMAX from dxf HEADER to set scaling3


Comments When the -f option (default) is effective (and none of the options -a, -d, -t,or -L have been set), the corners of the bounding window are obtained byusing the minimum and maximum x and y values obtained from the ".dxf"file. That window is then made to fit into the default SL-GMSDraw window,which has an extent of (0., 0.) to (72., 54.). The -w option is available to seta different extent such as the default display window of SL-DRAW2 whichwas (0., 0.) to (100., 75.).

Option -a aloneThe option -a makes no changes in the numerical values foundin the ".dxf" file before outputting them to the SL-GMS ".g" files.If -a is not used, there is no problem because dxf2gautomatically scales the coordinates to fit the SL-GMSDrawdefault display window.

Option -d<value> aloneAll coordinate and numerical values, for example, text heights,are divided by <value> before any further processing.

Whenever the -a option is used, the following precaution must betaken. The extent of the DXF file can (usually) be obtained bylooking at the values given by "EXTMAX x,y" and

-L Apply cosine(mid-latitude) correction to longitude coordinates when x,y coordinates of the dxf file are in degrees of lat and lon. Note: if those coordinates are multiples of the true lat/lon values, use -d<val> parameter to convert them to the true values

-t<value> Multiply nominal text height by this value. Default is 1.0

-tw Change black text to white

-w<ext_file>

Use extent specified in <ext_file>. Extent must be in this sequence in the <ext_file>; xmin ymin xmax ymax

1. The -a and -f flags are mutually exclusive; the default is -f 2. The -cap and -cf flags are mutually exclusive; if -cap and -cf are absent,use the 168 color defs in "$GMS_HOME/lib/colordef.acad" 3. Set if display does not fit the SL-GMSDraw window

Flag Description


"EXTMIN x, y" near the beginning of the DXF file. If -a is set andany of those x,y values exceeds a magnitude of 32,767 or thedifference between the x’s or y’s exceeds that magnitude, the-d<value> option must be used.

Option -L aloneThe -L option must be applied when the x,y coordinates aregiven in latitude and longitude. Each x coordinate is multiplied bythe cosine of the mid-latitude of the covered region. Failure touse this option in the case of lat/lon will cause the display to beelongated in the east-west direction.

Option -t<value> aloneThe height of each text character or string is multiplied by<value>. This option is of value when the text is too small whendisplayed at the desired zoom factor or factors.

Combinations of -a, -d, -LAny combination of these options is permitted. Two examples:

-a and -d<val>. If -a is set and any x or y coordinate in the DXFfile exceeds a magnitude of 32,767 or the difference between theMIN and MAX x or y exceeds that magnitude, the -d<val> optionmust also be applied in order to reduce such values to less than32,767. A common use for this combination is when the DXF filerepresents a map, especially when the map may have to adjoinanother map. The recommended value for <val> is a power often.

-a, -d<val>, and -L. When the coordinates are in lat/lon, the -Loption must be added.

A few DXF files convert to a "very small display," which, whenzoomed in, becomes a correct and satisfactory display. Thesolution for dxf2g could be the "zoom in" AutoCAD solution,where most initial displays are small. The alternative is the -eoption, that is, to execute "dxf2g -e <file>.dxf." That causesdxf2g to use the extent given by $EXTMIN and $EXTMAX fromthe DXF header, which is then normalized to the SL-GMSDrawstandard extent. (Our experience is that those values in the DXFheader are not always correct.)


Option -t<val> is sometimes helpful, while -tw may be neededwhen the display background colors are very dark grey or black.-t2 will double the dxf text heights, that is, those specified in thedxf file; -t0.5 will halve the dxf heights; -tw will make all textwhite.

The -w option is self-explanatory, as are -cap and "-cf <cfile>".

The option -e causes dxf2g to use the $EXTMIN and $EXTMAXvalues found in the header of the ".dxf" file. This option isnormally not necessary to obtain a satisfactory fit of the displayinto the SL-GMSDraw window; however there have been certain"pathological" cases that work only when -e is invoked.

File Descriptions dxf2g can be run in any directory provided that $GMS_HOME/bin is in the"path" and the environment variable $GMS_HOME is set correctly.

dxf2gFollow the USAGE statement.

colordef.acadThere are two things to consider:

1. The color numbers that appear in the ".g" files output bydxf2g

2. The colors to be available when using SL-GMSDraw.

A. The "colordef.acad" file contains the color numbers anddefinitions used by AutoCAD. By default, dxf2g outputs ".g" filesusing the same color numbers. See the USAGE statement onhow to use the -cap and -cf options to produce ".g" files with adifferent set of color numbers.

B. The standard "colordef.dat" file for SL-GMSDraw does notaccommodate all AutoCAD colors. Before using SL-GMSDraw todisplay the default dxf2g output files, that "colordef.dat" fileshould be sequestered, for example:

cd $GMS_HOME/lib

mv colordef.dat colordef.hold


Then execute

cp colordef.acad colordef.dat

If there is a "colordef.dat" file in the directory in whichSL-GMSDraw is being executed, it will use that file for its colors;otherwise it will use "$GMS_HOME/lib/colordef.dat" as its"colordef.dat" file.

A further point to consider is the background color forSL-GMSDraw. Experience with the test files used with dxf2gindicate that it is a good idea to change the first color of this filefrom 0 0 0 to .9 .9 .9, or even to .85 .85 .85, to display abackground sufficiently gray so that very pale colors, especiallypale yellow, can be seen without difficulty.

ColorThe file "colordef.acad" contains 168 RGB entries, as follows:

If the display hardware is capable of simultaneously displaying the neces-sary number of colors, "colordef.acad" should be set up as the "color-def.dat" file, as described above.

Index Contents

0 - 31 Standard SL-GMS colors

32 White

33 - 41 AutoCAD colors 1 - 9

42 - 51 AutoCAD colors 10 - 19 and 21 - 29 (colors are paired)

52 - 61 AutoCAD colors 30 - 39 and 40 - 49

..... ........

152 - 161 AutoCAD colors 230 - 239 and 240 - 249

162 - 167 AutoCAD colors 250 - 255


If the regular 32-color SL-GMS "colordef.dat" file is retained and an attemptis made to display a Model converted without the -cap option set, it is prob-able that no color displays will occur.

Colors are processed in one of three ways:

1. When neither -cap nor -cf is specified (default), each AutoCADcolor number (1 - 255) is converted in accordance with theentries 33 - 167 in "colordef.acad". When SL-GMSDraw is usedto display a Model made in such a case, the "colordef.dat" file forSL-GMSDraw must be a copy of "colordef.acad".

2. Specifying -cap is equivalent to saying, "Only the 32 SL-GMScolors are available for display — use them in the best way." Inthis case, each AutoCAD color number is converted to an index0 through 31 so that that index corresponds to the "best fit"(least squares fit) to one of the standard SL-GMS colors. (In thiscase, the SL-GMS 32-color "colordef.dat" file will work satisfac-torily during display.)

3. Specifying "-cf <file>" is equivalent to saying, "Only the N colorsdefined in <file> are available for display; use them in the bestway." In this case, each AutoCAD color number is converted toan index from 0 to N-1 so that that selected color is the "best fit"to one of the colors listed in <file>. In this case, <file> will worksatisfactorily as the "colordef.dat" file during display.

NOTE: Since all color numbers, converted or not, in the files created bydxf2g are one of the "colordef.acad" numbers and each displayedcolor corresponds to such a number, it is always best to use"colordef.acad" as the "colordef.dat" file in "$GMS_HOME/lib".The first 32 entries in this file are the standard SL-GMS colors. Ifyou wish to use a variant of the supplied color file, put it into thedirectory in which SL-GMSDraw is being executed and restartSL-GMSDraw.

Supplementary UtilitiesThere are four support utilities especially designed to improve efficiencywhen using dxf2g. These support utilities are distributed in the bin directo-ry. They are described below.


Since these utilities may not be provided on all platforms, alternative proce-dures are described for each utility as appropriate.

g myr____

This program converts to ".m1" format all "<file>_*.g" files associated withthe most recent "_subs.g" file and moves the saved SubModels to the SUB-MODS subdirectory, creating that directory, if necessary.

It does not work as expected if there is not a "most recent" "<file>_subs.g"file, as would be the case if the ".dxf" file had no BLOCK entries. In such acase, one would use "gm1 <file>_*.g".

gmyr invokes gm1. Assure that the path to gm1 and gml is established.

USAGE

gmyr<RETURN>

ALTERNATIVE

The value of gmyr will be appreciated after manually carrying out itsfunctions as delineated in steps 2, 3, and 4 of the following sequence:

1. Execute dxf2g "<file>" in accordance with the USAGE state-ment.

2. Move "<file>_subs.g" to the SUBMODS subdirectory.

3. Change to the SUBMODS directory.

4. Execute gm1 "<file>_subs.g"

5. Remove "<file._subs.g’

6. Change to the previous directory.

7. gm1"<file>_*.g" excluding "<file>_subs.g"

The point is that the external SubModels created fromconversion of the "<file>_subs.g" are often numerous andinterfere with working conveniently with the layer files, usuallythe only ones of significant interest. The above sequence, whichis functionally identical to what gmyr does, assures that allexternal SubModels will be in the SUBMODS subdirectory,where they are available to SL-GMSDraw.


mvaa_____

When the "_subs" file is converted to ".m1" format using gm1 directly, allthe Models listed therein are saved with the result that their ".m1" files endup in the current directory. The utility mvaa moves all such ".m1" files to theSUBMODS subdirectory (creating it, if necessary) where they are availableto SL-GMSDraw.

USAGE

mvaa<RETURN>

ALTERNATIVE

Move the SubModel files to SUBMODS.

Comparing AutoCAD and SL-GMSDraw displaysWhen doing this, it is usually better to bring up SL-GMSDraw first, sinceAutoCAD does not complain about unavailable colors. It occasionally hap-pens with AutoCAD that there are "dependent" layers, that is, layers in thelist that are "on" but that do not display when requested; however such alayer may display when another layer is turned on. The dxf2g solution tosuch a situation is not always predictable — two possibilities seem tooccur: 1. the dependent layer is displayed as a separate layer; 2. it is dis-played as part of another layer.

Sometimes a layer will appear to be empty in SL-GMSDraw. If this occurs,select the All option in the Select submenu of the Edit Pull-Down Menuand usually some very small or colorless objects will be revealed, where"colorless" denotes a color the same or very close to the background color.

Major Deficiencies1. Xref files are not handled.

2. The VIEWPORT facility has not been adequately tested; itshould not be used.


Problems, Anomalies, and Limitations

NOTE: The displays created by AutoCAD from ".dxf" files are consideredto be correct and have been used as the basis of comparison.

1. If the initial character of a BLOCK name is * or $ or -, it isreplaced by "aa_" or "ad_" or "am_", respectively. An interiorcharacter of * or $ or - is replaced by the "_" character.

2. If the initial character of a BLOCK name is a digit, it is prefixedby "an_".

3. If a BLOCK name is an SL-GMS keyword, it is prefixed by "ak_".

4. If the basename of a ".dxf" file is an SL-GMS keyword, executionstops with an appropriate message; the name of the file must bechanged.

5. The initially displayed line widths, that is, when the zoom factoris 1.0, are usually correct. Each line width in DRAW is constantand does not change thickness when zoomed, whereas lines inAutoCAD are actually filled rectangles or other shapes and dochange thickness when zoomed. The SL method has beenadopted primarily to achieve fast zoom and pan speeds, which manyof our applications require.

6. The AutoCAD feature that permits slanting of text characters(obliquing angle) is not supported.

7. AutoCAD constructs for text that begin with %% are not support-ed by dxf2g, except for the sequence %%% for %, which isrespected. In general, all other %% sequences are removedbefore the ".g" file is created, except for the cases describedhere. Both of the constructs, %%u and %%o, which enclosestrings, are removed, but any other %% sequences in that par-ticular string are not removed. Of the other %% sequences, onlythe first one appearing in any given string is removed. Note: The


sequence %%nnn is removed only if there are exactly three dig-its.

8. Partial Ellipses are not handled correctly.

9. POINT, as specified by $PDMODE and $PDSIZE. Only thePOINT is output.

10. If an x or y "extrusion" associated with an entity is non-zero, theentity is ignored. All z "extrusions" are assumed to be zero.SL-GMSDraw is a two-dimensional system.

Very Small RadiusThere is one case dxf2g cannot handle at all. If the radius of a sector (arc)or circle converts to a value less than 0.000015, the object will not be out-put or displayed. That is due to a basic feature of the SL-GMS program thatconverts ".g" files to ".m1" format, which thereby avoids spending its timetrying to create an arc or circle smaller than a single dot or pixel. This "verysmall radius" problem" may arise with a "very small display" and then goaway when the -e option is used.


The genlocfile utility

For each Model contained in a given ".m1" or ".m2" file, the genlocfile utili-ty traverses all parts and all local SubModels. For each object which"needs to be internationalized," genlocfile outputs a localization file com-mand to the localization file. To fall into the "needs to be internationalized"category, an object must be one of the following types:

• Text

• Filled Text Rectangle

• Model Instance

• Renamed Variable renamed to a String Constant

Additional conditions which must be fulfilled are as follows:

• all ancestors must have a name

• its name must be prefixed with the internationalization prefix

The command-line syntax of the genlocfile utility is as follows:

genlocfile -loc lang_name [-p prefix] [-wc]file1.[m1|m2] file2.[m1|m2] ...

The -p option specifies the internationalization prefix. The default value forthe internationalization prefix is "i_".

If a given Model does not contain any objects which fulfill all these condi-tions, a localization file is not generated for that Model.

The genlocfile utility synthesizes a name for the generated localization fileby concatenating four elements: the name of the ".m1" or ".m2" file (withoutthe ".m1" or ".m2" suffix), a "_" character, lang_name (specified with the-loc option), and a ".lc" suffix. For example, the following command:

genlocfile -loc ja menu1.m1

generates a localization file named "menu_ja.lc".

The genlocfile utility generates multi-byte localization files unless the -wcoption is specified. The -wc option is recognized in Windows NT only. Thisoption causes genlocfile to generate a wide-character (Unicode) localiza-tion file.

The genlocfile utility cannot process ".g" files.


UsageTo generate the localization file "menu_ja.lc" from "menu.m1":

genlocfile -loc ja menu.m1

To generate a localization file for each ".m2" file in the current directory,setting lang_name to "ja":

genlocfile -loc ja *.m2

To generate the wide-character localization file "menu_fr.lc" from"menu.m1" on Windows NT:

genlocfile -loc fr -wc menu.m1

To generate the localization file "menu_ja.lc" from "menu.m1", processingonly objects which have an "intl_" prefix in their name:

genlocfile -loc ja -p intl_ menu.m1

Further information about localization files is provided in the International-ization — localization filessection of the SL-GMS Function Reference.


E

Version 6.2a- 26 M

The State Management System

Introduction

The SL-GMS State Management System (SL-SMS) facilitates navigationover and control of a collection of dynamic graphical screens and the pro-cessing states of those screens. SL-SMS coordinates the mapping (mak-ing visible) and unmapping (making invisible) of dynamic screens, providesa simple method of handling Events, and automatically activates Data-sources. The design intent is to reduce to a minimum the user applicationprogramming required to control these elements. For example, GISMOs ina Model can provide pickable objects which, when selected, bring up otherscreens or popup menus. SL-SMS in a sense provides macros for calls tolibgms functions. SL-SMS users still have access to the full library offunctions provided by SL-GMS. Access to the library functions enablesusers to extend the functionality of SL-SMS as their requirements evolve.

The use of States is not restricted to screen switching. The complex defi-nition of custom State methods can be used to encapsulate responses toinput Events without necessarily causing a screen switch. For example,an application might attach to the "right mouse button press" Event ameaning that corresponds to the mode in which it was executed:while in a "drawing" mode, continue current linewhile in a "properties edit" mode, signal done and clear the Dialog Box.

Components of SL-SMS

SL-SMS is basically comprised of three parts: the GISMO Manager, theEvent processing loop controlled by the SL-GMS Main Functions, and theState Manager.

The GISMO ManagerSL-GMS GISMOs (Graphical Interactive State Management Objects) pro-vide a means of directly manipulating application

SL-GMS Reference E-1ay 2006

data, displaying data, and defining other aspects of interactive buttonbehavior. The GISMO Manager initializes required GISMO functions andcoordinates the dispatching of Events received from GISMOs.

The SL-GMS GISMO Library provides an extensive library of ready-to-useGISMOs which can be used, unaltered, simply by selecting the desiredGISMO from a palette of SubModels. Because GISMOs are defined usingstandard SL-GMS objects, the SL-GMS GISMO Library can be expandedby copying a GISMO which most closely matches the desired behavior andediting its DynProp.

The GISMO Manager is independent of the usual SL-GMS Event process-ing loop started with gmsMainLoop( ); it is initialized with a call to gmsIn-itGismos( ). More information about GISMOs is provided in Appendix Aand Chapter 5 — GISMOs.

The State ManagerSL-SMS manages a hierarchy of screen States. The State Manager han-dles, for example, automatic loading of Models, visibility of Models andViews, and determination of which Event callback functions should beavailable at any given time. This chapter explains the State Manager por-tion of SL-SMS in detail.

The SL-GMS Main FunctionsThe gmsMainInit( )1 and gmsMainLoop( ) functions are used in applica-tion programs to set up SL-GMS, create a Workstation/Window, handleEvent processing including Window expose or resize Events, and calluser-defined functions in response to certain input Events. AdditionalSL-SMS functions, used along with these functions, provide portable inte-gration to various platform-windowing systems such as X or SunView. TheSL-GMS Main Functions are fully documented in the section Main —SL-GMS main functions in the SL-GMS Function Reference.

1. For non-C programming languages, or situations where the argc-argv mechanism is inconvenient, or where unavailable, the function, gmsMainInitStr(argstr), can be used instead of gmsMainInit( ). Theargument argstr is of type "char*." It contains space-separated arguments.

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

State-changing GISMOs

PredefinedThree predefined State-changing GISMOs are provided with SL-GMS:SCREEN, DATSCREEN, and POPUP.

When a SCREEN GISMO is selected at run time, its Views and Modelsspecified in its Renamed Variables are made visible upon activation.

The DATSCREEN GISMO, when selected, makes its Views and Modelsvisible upon activation and, in addition, has its datflag renamed to ON,causing a ".dat" file to be read when the State Instance is activated.

The POPUP GISMO, when selected, makes its Views and Models visibleupon activation and, in addition, has its clearflag renamed to OFF, givingits Model the appearance and behavior of a popup menu.

Defined at Run time

A STATE GISMO is also provided with SL-GMS. When a STATE GISMOis selected at run time, it creates an Instance of a customized State classand makes its Views and Models visible upon activation.

SCREENSCREEN

DATSCREENDATSCREEN

POPUPPOPUP

STATESTATE


Attributes provided by the generic State Class

Listed below are the State attributes provided by the generic State Class.The flags’ default values are also provided. The functions used to set andquery these flags are found in the State — attributes section of the SL-GMSFunction Reference. These flags are provided as a convenience; theycontrol functionality which has been found useful in a wide variety of appli-cations. The use of the attribute flags is not required; they can all be set toOFF, if desired. In addition, new flags can be added to the State Classstructure.

State Attributes Provided by theGeneric State Class

State Attributes Description

autodeactflag if ON, upon G_LOC_PRESS of right mouse button, deactivate State Instance and reactivate its SuperState ("pop" the stack). Default value: ON

clearflag if ON, clear View upon activate, before making the State Instance’s Models visible. Default value: ON

d1flag if ON, read ".d1" file upon activate. Default value: OFF (not implemented)

datflag if ON, read ".dat" file upon activate. Name of ".dat" file is the name of the State’s first Model, with the ".dat" extension.Default value: OFF

freeflag if ON, free State Instance when the State Instance is deactivated. Normally set to ON for dialog boxes. Default value: OFF

gismoflag if ON, execute gmsGismoEvent( ) on GISMOs (i.e., allow Event to be processed by the GISMO DynProp actions). If OFF, allow Event to be processed by the State’s Event-handler. If a State Instance’s Models do not contain GISMOs, turning gismoflag OFF produces a slight performance enhancement when processing input Events.Default value: ON


Building Custom State Class Objects

The generic State class object is distributed with SL-SMS. The genericState object serves as a prototype State object that couples together han-dling of an event that affects data, Datasources, and the graphical repre-sentation of the data on the workstation screen. It includes componentsproven to be useful in designing multi-screen applications. The genericState class data structure, distributed in the file "gms_sms.h", provides suf-ficient functionality that it can serve as the foundation for building user-cus-tomized State class objects. The generic State class object is copied andthe new State object is customized by the application developers by delet-ing, modifying, and adding to the components provided in the genericstructure.

Generic State class featuresAn Instance of the generic State class in SL-SMS includes:

popflag if ON, use gmsPopOn( )/gmsPopOff( ) upon activate/deactivate. These functions save and restore a raster image of the View in which they appear. Should not be used on top of objects that will be dynamically updated. Default value: OFF

st30flag The version 3.0 compatibility flag is provided so that pre-4.0 programs can be invoked without changing the callback functions. If ON, callbacks are invoked without the State Instance as the first argument, as they were in version 3.0. Default value: OFF

updflag if ON, enable updates on State Instance. May be set in the suspend and reactivate methods. Default value: ON

visflag if ON, keep State Instance SuperState’s Models visible when State Instance is activated. Default value: OFF

State Attributes Provided by theGeneric State Class

(continued)

State Attributes Description


1. a Workstation/Window, a View, and a set of Models that arevisible when a State Instance is active. Since there can bemany concurrently active State Instances, there can be manyconcurrently visible Workstation/Windows, Views, and Models

2. a pointer to the generic State class which contains a set ofState methods. Among the State methods are Event-handlersto process input Events related to an active State Instance.Since there may be many concurrently-active State Instances,the State Instance that receives a given Event is determined bythe interaction of the Event attributes (e.g., the screen coordi-nates in the case of a Locator Event) and the active Worksta-tion/Window and View. Also included in the State methods arefunctions which affect the State tree such as activate, deacti-vate, and suspend.

3. a set of Datasources that becomes active when a given StateInstance is activated. In SL-SMS, Datasource objects automat-ically perform the necessary memory allocation for program vari-ables and invoke gmsVarDefine( ) and gmsVarChanged( )functions at appropriate times. When a State Instance is deac-tivated, Datasource objects automatically free memory.

4. a set of attributes that controls optional State Instance behav-ior. The attributes are flags which modify the manner in whichthe other three State Instance characteristics are implement-ed. A complete list of these flags appears in the sectionAttributes provided by the generic State Class on page -4.

Although the above four represent the core components of a generic StateInstance, a number of additional characteristics constitute the genericState Instance description:

• a State variable by the name of"<Instance-name>_button_state" which can be used by anapplication, and

• a TextEdit object — a Text Rectangle or Text object (one perWorkstation/Window) that is used to echo characters typed atthe keyboard. If no TextEdit object is defined for aWorkstation/Window, no Keyboard or String Events reach anyEvent-handlers. Selection of a TEXTENTRY GISMO replacesthe State Instance’s TextEdit object with the GISMO selected.


Upon initialization, SL-SMS internally performs the necessary functions tomake three Instances of the generic State class structure, setting appropri-ate attribute flags to produce the three predefined State Instances, screen,datscreen, and popup. These three Instances are made available tousers of SL-GMS via the SCREEN, DATSCREEN, and POPUP GISMOs1

respectively. The three predefined State Instances have the followingbehaviors:

The three Predefined State Instances are made available to users ofSL-GMS through the following functions: gms_screen_state_invoke( )gms_datscreen_state_invoke( ) gms_popup_state_invoke( )

These three functions are intended to be called from dynamic descriptions,but can be called from C language code.

The GISMO State-changing functionsThe GISMO State-changing functions are called from GISMO dynamicdescriptions; in other words, as arguments to call actions in an object’sinput (#) dynamics. The functions are:

1. Also through the gms_screen_state_invoke( ), gms_datscreen_state_invoke( ), and gms_popup_state_invoke( ) functions

screen State mouse button 3deactivates (pops) the

State

datscreen State opens ".dat" filecloses ".dat" filereads ".dat" file until a

blank line is encounteredmouse button 3

deactivates (pops) the State

popup State mouse button 3deactivates (pops) the

State


gms_state_invoke( )gms_screen_state_invoke( )gms_datscreen_state_invoke( )gms_popup_state_invoke( ) gms_state_return( ) gms_quit( )

These functions are used to create new State Instances of predefinedStates like datscreen, popup, and the generic screen State. Thegms_state_invoke( ) function creates an Instance of a customized Stateclass. The gms_state_return( ) function provides a simple method of "popping" a State Instance (i.e., deactivating it). Thegms_quit( ) function is used to cause program termination. A completedescription of the functions and their calling syntax can be found in thesection SL-GMS GISMO Action Functions on page -81.

State class methods

Method Name Typical Behavior

definevars called in between the Model Get operationand the DynInit operations during the gmsActivate( ) function• perform special variable-handling operations, before the gmsDynInit( ) function is called

• useful when using State Variables ( gmsStVarDefine( ) )

activate sent to State when State is activated (i.e., added to the State tree)• application-specific behavior, such as establishing links with data sources

copyfrom sent during the cloning process to permit the new class to copy from another State’s fields

customfree sent to the State when the State is freed; any custom memory allocation that took place when the State was created, activated, or during its existence can be freed here before the State is freed


State class methods, if used, must be declared in the State class sourcecode file with the exact method names used in the preceding table. Pro-vided as a guide, the table shows some typical steps performed in the vari-ous State methods. The user is not restricted to this list of steps.

State tree inheritanceSix types of State class methods may be defined in customized State mod-ules:

deactivate sent to State when State is deactivated1

• undo any special actions performed in activate, such as freeing objects or removing links to data sources.

suspend sent to State when a SubState is activated• suspend updating• disable data bindings

reactivate sent to State when a SubState is deactivated• resume updating• re-enable data bindings

update sent to each active State when a Timer Event is received• determine new application variable values• perform gmsVarChanged( ) on variables whose values have changed

1. The deactivate method never is invoked for the top State; if an appli-cation exits, the top State notification occurs in the win_destroy methodrather than the deactivate method.

Method Name Typical Behavior


State tree inheritance is the capability for a SubState to use a method pro-vided in a SuperState. As seen in the table above, two method types caninherit methods from their SuperState: Input Event-handler andUser-defined methods. It follows that redefining such methods within aSubState that exists in its SuperState has the effect of defining a differentresponse to the Event that triggers the execution of that method.

For example, an Input Event-handler method with a single statement,

return 1;has the effect of causing the Event to be ignored.

State Class Method Inheritance

Method Type Inherited by SubStates

Input Event-handler methods (Event-handler callbacks executed in response to a Locator, Keyboard, or String Event)

yes

Window Event-handler methods (Event-handler callbacks executed in response to a Window Event)

no

update method (the method which typically modifies variables driving screen objects and calls gmsVarChanged( ))

no

The activate, definevars, deactivate, suspend, and reactivate methods (used to specify actions to be taken when the State is added or removed from the tree of State Instances)

no

Notrecognized methods (executed when the State receives a message that it does not recognize)

no

User-defined methods (typically, used to operate on State class variables — the State class’ data and the methods for manipulating that data are encapsulated in a single module)

yes


Notrecognized methodsA State can now provide notrecognized methods that are executed whenthe State receives a message that it does not recognize. Three notrecog-nized methods are provided: notrecognized, notrecognized1, andnotrecognized2, taking zero, one and two arguments, respectively. Exam-ples of these methods are shown below:

static intnotrecognized (state, messagename)

idCLASS state;char *messagename;

{return gmsStStrMsg(state->client, messagename);

}

static intnotrecognized1 (state, messagename, arg1)

idCLASS state;char *messagename;int arg1;

{return gmsStStrMsg1(state->client,

messagename,arg1);}static intnotrecognized2 (state, messagename, arg1, arg2)

idCLASS state;char *messagename;int arg1;int arg2;

{return gmsStStrMsg2(state->client, messagename,

arg1, arg2);}


The methods must be added to the State class’ method list:

gmsClassAddMethod(stclass, "notrecognized",notrecognized, G_INTEGER, 0);

gmsClassAddMethod(stclass, "notrecognized1",notrecognized1, G_INTEGER, 0);

gmsClassAddMethod(stclass, "notrecognized2",notrecognized2, G_INTEGER, 0);

State class event handlingSL-SMS allows a State method to be defined for each type of Event gener-ated at the Workstation level, as described in Chapter 7 — Event Handling.

NOTE: When using SL-SMS only the event codes listed in the tablebelow can be used. State class Event-handler methods must bedeclared in the State class source code file with the exact namesused below.

The State methods are shown with their corresponding Event codes:

Valid Event-handler Methods

Method Name Event code

loc_press G_LOC_PRESS

loc_release G_LOC_RELEASE

loc_motion G_LOC_MOTION

key_press G_KEY_PRESS

key_release G_KEY_RELEASE

key_filter G_KEY_FILTER

str_done G_STR_DONE

win_expose G_WIN_EXPOSE

win_resize G_WIN_RESIZE

win_focus_in G_WIN_FOCUS_IN

win_focus_out G_WIN_FOCUS_OUT

win_enter G_WIN_ENTER


Examplestatic intloc_motion (state, event)

id state;id event;

{unsigned int mod;

/* only print data for loc_motionEvent while MB1 is held down */

if (!(gmsQEvButtons(event) & G_LOC_BUTTON_LEFT))return 1;

printf("<loc_motion> state: %s button: %s (%d,%d)trig: %s mods: %s\n",

gmsQStName(state), buttons_str(event),pntX(gmsQEvPoint(event)),pntY(gmsQEvPoint(event)),trigger_str(event),mod_str(event));

return 1;}

win_leave G_WIN_LEAVE

win_map G_WIN_MAP

win_unmap G_WIN_UNMAP

win_destroy G_WIN_DESTROY

win_destroy_override1

1. A "win_destroy_override" method can be de-fined for a State but there is no correspondingevent code.

Valid Event-handler Methods(continued)

Method Name Event code


The first argument of every State Instance’s Event-handler callback is apointer to the State Instance itself, which permits callback functions toquery and modify the State Instance’s Workstation/Window, View, Models,and other attributes.

The second argument to an Event-handler is the Event object. The type ofobject varies, depending upon the type of Event:

• The Locator Event callbacks receive the LocEvent object.

• The Keyboard Event callbacks receive the KeyEvent object.

• The String Event callbacks receive the StrEvent object.

• The Window Event callbacks receive the WinEvent object.

Locator Events are dispatched to a particular State Instance based uponthe Workstation/Window and View in which they occur. In addition,SL-SMS checks within the State Instance’s Model to determine whether theselected object is a GISMO. If the object is a GISMO, its dynamics areexecuted and no further processing is done for that Event.

Keyboard Events are dispatched to a particular State Instance basedupon the Workstation/Window in which they occur and the State Instance’slocation in the State tree. The Event is given to the most recently activatedState Instance which has a TextEdit object. Function Key events aretreated as Keyboard Events and can be used to trigger GISMO Actions byusing the function gmsFKeyProcess( ).

A String Event is dispatched following a series of Keyboard Events endingin a Keyboard Event with an Event code of XK_Linefeed. (A complete listof XK_ key symbol codes is provided in the "keysymdef.h" file in the libdirectory.)

NOTE: If no TextEdit object is defined using the gmsTextEditObj( ) orgmsTextEditObjName( ) functions for a Workstation/Window,neither Keyboard Events nor String Events are sent to any StateInstances.

For Window Events, State methods are invoked when a WinEvent objectis received for a State Instance’s Workstation/Window. In this way,SL-SMS automatically manages the many Events received by a multi-Win-


dow application and dispatches them to the correct callback function,based upon the organization of State Instances for the application.

The win_destroy( ) method is still supported to allow a State to performcleanup tasks before exiting. A return value of -1 indicates that the Statein question has not only deactivated itself but also a SuperState(s). As aresult, the processing of the custom win_destroy( ) Event handler methodis aborted because some of the SL-SMS States still to be processed mayno longer exist. This situation is not common but may occur under certainconditions. For example, an SL-SMS State controlling an SL-GMS Modelmay handle the win_destroy( ) method by deactivating both itself and itsSuperStates that control the relevant SL-GMS Workstation and View. Inthis case, since the SuperStates were deactivated from a SubState, theprocessing of the win_destroy( ) Event handler method must be aborted,since the SuperStates no longer exist to receive the win_destroy( ) meth-od.

In some cases, it may be necessary to inhibit the window destroy. Forexample, a State may require additional user input before exiting. Toallow this, a new method, win_destroy_override( ), is now supported.

Before a window is destroyed, the win_destroy_override( ) method isexecuted in all States that use the window and in all SubStates of thoseStates. SubStates receive the win_destroy_override( ) callback even ifthey use a different window from the window being destroyed.

If the win_destroy_override( ) method for any State or SubState returns anon-zero value, the window is not destroyed. In this way, each affectedState or SubState has the opportunity to "cancel" the pending windowdestroy.

If all win_destroy_override( ) methods return 0 (zero), all affected Statesare deactivated and the window is destroyed.

If a State Instance’s Class does not implement a Locator, Keyboard, orString Event method, the State Instance inherits the method from its Super-State. All other Event methods are not inherited.

More information about Events in SL-SMS is provided in Chapter 7 — EventHandling.


Implementation of Exemplar cloning for State ClassesThe process of creating SL-GMS State Instances includes the ability to usea State Class "Exemplar." The Exemplar does not have to be defined; it isoptional. The Exemplar is never activated, either; it is simply used as atemplate for storing default attributes.

The Exemplar is a single pre-defined State Instance which is associatedwith the generic State Class. Creation of State Instances of that Class isdone by "cloning" the State Class Exemplar. This provides a mechanismwhereby default attributes may be established for a State Class andassigned automatically whenever an Instance of that class is created.

The Exemplar State Instance is usually defined during the initialize( ) func-tion for a particular State Class. This is done by simply calling thegmsStateInst( ) function and assigning the Instance name to be the sameas the class name.

Each time a subsequent gmsStateInst( ) function call is made to create anInstance of the State Class, it first looks to see if the Exemplar can befound. If so, the new State Instance is created by cloning the Exemplar; ifnot, a simple Instance is created with the standard default attributes.

The process of cloning the Exemplar to create a new State Instanceinvolves creating a simple Instance and then copying all the standard Stateattributes, such as "freeflag", "clearflag", and so on. The names of Modelsand Views are copied; pointers are not. Only the attributes of the standardState structure are copied; all "custom" State fields are set to 0.

The State Class can be defined so that additional State fields are copied tothe new Instance by providing a copyfrom method. The method is invokedduring the cloning process to permit the class to copy other State fields.

This method is defined as follows:

static intcopyfrom (state1, state2)idCLASS state1, state2;

{state1->customfield = state2->customfield;

return 1;}


Any necessary information may be copied from the Exemplar in this man-ner in a custom copyfrom method.

As noted above, the Exemplar is usually created in the initialize( ) methodof a State class. The following is a code fragment example:

.

. <top of file>

.struct Abc {

G_STATE_FIELDS<other, Abc-specific state fields>

} Abc, *idAbc

#define CLASS Abc#define idCLASS idAbc#define CLASSNAME "Abc"

.

. <file code>

.g_generic_state_initialize ()

{id stclass;idCLASS exemplar;

/* create a state class */stclass = gmsStateClass(CLASSNAME, sizeof(struct

CLASS));gmsClassAddMethod(stclass, "copyfrom", copyfrom,

G_INTEGER, 0);.. <other methods>.

gmsStClassInstall(stclass);

exemplar = gmsStateInst(CLASSNAME, CLASSNAME);.. <(optional) exemplar

attribute settings>


.return 1;

}

Side effects of implementing the Exemplar The Exemplar is an optional State which is never to be updated. Thus, theuser may or may not create the Exemplar, and, if it is created, may or maynot reset its attributes.

If an Exemplar exists, all State Instances of that State Class (created afterthe Exemplar) will copy its attributes. However, if the user has an applica-tion, created before the existence of the Exemplar, and if that applicationwas implemented using a State Instance with the same name as the Stateclass, that State Instance will become the Exemplar, and any State Instanc-es created after it will copy its attributes.

The difference between the old and the new applications will be that theState Instances created in the new application may not receive defaultSL-SMS attributes, but attributes from the Exemplar instead. If the Exem-plar has the default SL-SMS attributes, no change in behavior will be seen.If the Exemplar is changed, however, these changes will appear in all sub-sequently-created State Instances. The old application will have StateInstances with default SMS attributes and the new application will haveState Instances with the Exemplar attributes. The difference in theseattributes could lead to divergent behavior.

A simple fix for this divergent behavior problem is for users to rename anyState Instances which currently have the same name as the State Class.This renaming would have to occur not only in the gmsStateInst( ) call, butalso anywhere the State Instance's name was used, including calls togmsStFindByName( ), Renamed Vars in Models, and so on.


Using the State Message Debug flagTo facilitate the development of custom State Class objects, the functiongmsStDebugFlag( ) is provided for inclusion in the developer’s code.This function provides the means to control tracing of messages betweenState Class objects. This function is implemented as follows:

gmsStDebugFlag(0)No tracing of messages

gmsStDebugFlag(1)Basic tracing of messages

gmsStDebugFlag(2)Verbose tracing of messages,including "update" calls

Event-handler functions outside SL-SMS

It is also possible to set up Event handlers outside of SL-SMS; in most cas-es, however, using the SL-SMS approach is more straightforward and istherefore recommended.

In SL-GMS, a single function, gmsWSEventFctn( ), is used to establish acallback function for an Event on a particular Workstation/Window:

intgmsWsEventFctn (workst, eventcode, fctn)

id workst; /* Workstation which is to receiveEvent */

int eventcode;/* type of Event */int (*fctn) ( );/* callback function to be invoked

upon Event */The gmsWsEventFctn( ) function is invoked from an application program.This function sets up Event handlers on a per-Workstation/Window basisby passing the object pointer for the desired Workstation/Window (workst).

In SL-SMS, the gmsInitState( ) function calls gmsWsEventFctn( ) oncefor every Event type listed in the table, Valid Event-handler Methods onpage -12, in order to set up the Event-handlers that dispatch Events toGISMO action functions or State class methods.

NOTE: The function gmsWsEventFctn( ) must not be called inapplications that use gmsInitStates( ), as GISMOs will notfunction properly.


All Event handlers may be established by using this function except forone: the Event handler for String Events. To define an Event handler forString Events gmsWsTestEditObj( ) should be used:

intgmsWsTextEditObj(workst, textobj, maxchars,

promptstring, initstring,dispatch_mode, fctn)

id workst; /* Workstation which is to receiveEvent */

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 invokedupon Event */

Each Workstation/Window created manages a single window-managerwindow. At present, multiple window-manager windows are handled by cre-ating multiple Workstation-Window objects. Creating multiple Worksta-tion-Window objects does not produce any practical limitations.


F

Version 6.2a- 26 M

Datasource Management

Introduction

The SL Datasource Management System (SL-DMS) is a service providedby SL-GMS to simplify the interconnection of application data and SL-GMSscreen objects.

The design intent of SL-DMS is ultimately to eliminate programmingrequired to connect with external data sources or internal variables. Thiselimination of programming facilitates the use of graphics screens drivenby large sets of data.

The current Datasource Management System provides:

• a simulation Datasource for interactive dynamic previewing;and

• the ability to create customized Datasources.

SL-DMS automates data management through variable definition, memoryallocation, and variable modification. A table is set up in memory whichconnects an application’s data directly to SL-GMS screen-control objects.This table approach updates screen elements only when their underlyingdata changes. Each Datasource may be conceived as a collection of vari-ables and a set of methods to operate on them. Many Datasources mayexist in a given application, and can be activated and deactivated accord-ing to the needs of the program.

SL is working closely with application developers to determine the bestpossible interface for SL-DMS. At present, Datasources are created andaccessed by using the functions described in the Datasource sections ofthe SL-GMS® Function Reference.

SL-GMS Reference F-1ay 2006

Datasource classes and Instances

The Datasource class serves as a template for creation of DatasourceInstances. The Datasource class also defines a set of methods to manip-ulate a Datasource Instance’s variables.

The Datasource class structures are defined in the file ”gms_dms.h”.

A Datasource Instance is essentially a copy of the Datasource class struc-ture; each maintains a linked List of Variable Definition objects calledVarDefs. In addition, Datasource classes and Instances have a name fieldwhich enables them to be named.

Datasource files

SL-DMS uses two types of files, designated by the suffixes ".dat" and ".d1".The ".dat" file is an ASCII file used to specify dynamic behavior. The".dat" file contains lists of variables and values, as well as commands, suchas step and random, which modify those variables. Typically, ".dat" filesare used to generate test data when prototyping.

The ".dat" file is also used as a Datasource description file for SimulationDatasources. More information about the syntax of ".dat" files is providedin the section Previewing dynamics of the SL-GMS Quick Reference. Infor-mation about using ".dat" files is provided in the section Previewing theDynamic Behavior of Objects on page 3-61.

The ".d1" file is a binary representation of a list of Datasources. The ".d1"file format is subject to change.

Types of Datasources

Currently, one Datasource type is supplied with SL-DMS: the simulationDatasource. Additional Datasources will be supplied in a future release ofSL-GMS. If necessary, however, customized Datasources may be creat-ed by the user.

The simulation Datasource is used when reading ".dat" files. When a".dat" file is read by the SL-GMS Preview utility, SL-DMS is actually invok-ing an Instance of the simulation Datasource.

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

Using Datasources within SL-SMS

Any SL-SMS State Instance may have one Datasource associated with it.

Setting the State Instance’s datflag to G_ON tells SL-SMS to open a ".dat"file with the same name (prefix) as the State Instance’s first Model. Thisdata file should use the same syntax described in the section Previewingthe Dynamic Behavior of Objects on page 3-61.

If SL-DMS encounters an error in a ".dat" file, an error message is generat-ed as shown in the following example:

ERROR: file "xradial.dat", line 1: syntax error indata spec command

Currently, Datasource activation routines are placed directly in the Stateclass activate method.

Additional information about using Datasources with SL-SMS is provided inAppendix E.

On-line examples

"gms_dms.h" fileThe header file "gms_dms.h" distributed in the lib subdirectory providestwo structures which define the Datasource class and minimal Datasourceobjects. The class Definition is used by SL-DMS for managing Instancesof Datasource objects and should not be modified directly by Datasourcesor applications. In addition, the Datasource object’s "required fields"(defined as "G_DATASOURCE_FIELDS") should only be modified bySL-DMS. However, each Variable Definition (VarDef) in the idLinkRefvardefs field provides an id ds_pointer field which is available for Data-source use.


"simpleds.c" fileThe "simpleds.c" file distributed in the dmstest subdirectory of the demodirectory sets out the definition of an elemental "hello world" Datasourceobject:

1. The simpleDs structure contains only theG_DATASOURCE_FIELDS which are required by SL-DMS.

2. Only two methods are defined (activate and update), each ofwhich perform something basic, but demonstrable, to allattached variables.

3. Empty class-table macros exist for the SL-GMS object "dump"and "file" utilities. The result is that minimal information is"dumped" or "filed" about an Instance of simpleDs. Nestedobjects (VarDefs, in this case) are output according to their ownclass tables.

4. The global initialization function simpleDsClassInit( ) createsthe simpleDs Datasource class using gmsDsClass( ); it adver-tises its interfaces and class tables with thegmsClassAddMethod( ), gmsClassAddDumpTable( ), andgmsClassAddM1Table( ) functions and finally calls gmsD-sClassInstall( ).

"simpletest.c" moduleThe program "simpletest.c" distributed in the dmstest subdirectory of thedemo directory presents a simple test for simpleDs. A simple Model refer-encing two variables (ival and dval) is loaded into SL-GMS and a singleInstance of simpleDs is created, given two VarDefs, and activated. ALocator Event-handler is registered to trigger updates, and gmsMainLoop() is called.

"filetest.c" modulesThe code provided in "fileds.h", "fileds.c", "filedsvar.c", and "filetest.c" pre-sents a more complex example Datasource, which expands on the requiredG_DATASOURCE_FIELDS and attaches an additional object, fileDsVar, toeach VarDef.


"filetest.c" fileThe test program "filetest.c" exercises not only fileDs but thegmsDsList*( ) interfaces.

"fileds.h" fileThe header file "fileds.h" provides the structure definitions forfileDs and fileDsVar. The fileDs structure adds filename, format,and fp fields to G_DATASOURCE_FIELDS for Instance-levelreference. Per-variable information is kept in the fileDsVarobject.

"fileds.c" and "filedsvar.c" filesThe function provided within "fileds.c" creates a Datasourceclass with six methods, and ends its global initialization functionby invoking the function provided within "filedsvar.c".


G

Version 6.2a- 26 M

Linking SL-GMS applications

Introduction

This appendix describes the SL-GMS Run-time Function libraries and howan executable SL-GMS application is created.

Components of the SL-GMS Run-time Function Libraries

Figure G-1The basic layers of the SL-GMS Run-time Function Libraries

The SL-GMS Run-time Function Libraries may be seen as consisting of twolayers:

1. libgms is the central library which consists of all the C func-tions1 needed to construct complex graphical Models, manipu-

1. Complete Ada, FORTRAN, and Pascal interfaces are also provided for libgms.

User Application Program

Models libgms SL-GWS

SL-GMSDrawor

SL-GML

user-callablefunction library

workstation-specificinterface

or SL-GMSRUN

smsmap

user-callable

function libraryMapping application

SL-GMS Reference G-1ay 2006

late their size and position, modify screen States, or maintainexternal data sources.

Models are read into application programs by functions fromlibgms that are linked with program code. At link time, thefunctions required by Models, as well as functions required tointerface the program code, are extracted from libgms andbecome part of the application. The central library, libgms itself,has five components as follows:

SL-GMF — Graphical Modeling Function

cluster of functions needed for creation and manipulation ofgraphical objects and the comprehensive handling ofhierarchical Models built-up from the objects (on-line as: libgms)

SL-GMD — Graphical Modeling Dynamics

cluster of functions that support the coherent binding betweenapplication variables and screen object(s) or screen-objectelements (online as: libgmd)

SL-DMS — Datasource Management System

cluster of functions required to simplify the set up andmaintenance of specifications for external data sources, such asconventional files, live data feeds, or other programs and/orapplications code; libdms also includes transparent functionsrequired to support specific proprietary products such asBASEstar from DEC, Nexpert Object from Neuron Data, forexample, as well as a variety of SQL file structures (online as: libdms)

SL-SMS — State Management System

cluster of functions which simplify the organization,management, and access to application states in real-worldenvironments where the management of many screens and/orapplication states is required; libsms, libsmsnew, libsmsnt,and libsmsxm make possible, for example,

• initialization

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

• the codeless switching and management of screen states toachieve nesting, sequencing, and branching within sets ofscreens

• data source manipulation,

• dialog handling

• zoom,pan,layering control

libsms, libsmsnew, libsmsnt, and libsmsxm also support truemultiple-concurrent states running under a single process, orunder multiple processes (online as: libsms, libsmsnew, libsmsnt, and libsmsxm)

SL-OOE — SL Object Oriented Environment kernel whichprovides object-oriented resources that manage and control theouter architecture, as well as independent messaging,encapsulation, dynamic binding, and inheritance.

2. SL-SMSMAP is the Mapping application library of functions thatprovides the developer with the capability of creating interactive,animated graphics that satisfy the needs of map and networkbased applications. The graphics integrate into both X-basedand Microsoft Windows (NT & 95) systems.

3. SL-GWS is the Graphics Workstation System, supported byits own set of functions in libgws. This outer layer contains inde-pendent clusters of low-level protocols and functions that maybe seen as virtual workstations. Each cluster provides specificsupport for an increasing variety of platforms, graphics boards,devices, graphics standards, windowing conventions, raster (bit-map) capabilities, and operating system idiosyncrasies. Confin-ing such functions to this layer greatly simplifies transportabilitywithout disturbing the higher-level structures of SL-GMS. Asillustrations, there are virtual workstations for X Window,DECwindows, and others.


PC-Intel

An executable SL-GMS application program is created by compiling theapplication source code modules and then linking the resulting binary fileswith the SL-GMS Run-time Function Libraries and the Windows NT Librar-ies.

The SL-GMS Run-time Function Libraries are distributed in$GMS_HOME\lib and are listed below.

SL-GMS Run-time Function Libraries(Alphabetical Order)

Library Name Description

"libdms.lib" Data Management System Library

"libgmd.lib" Graphical Modeling Dynamics Library

"libgms.lib" Graphical Modeling Functions Library

"libgws.lib" Graphics Workstation Library

"libgwsnt.lib" NT Graphics Workstation Library

"libsms.lib" Screen Management System Library

compile

link

ApplicationSourceCode

Modules SL-GMSRun-timeFunctionLibraries

ApplicationBinaryCode

Modules

Windows NTLibraries

ExecutableSL-GMS

ApplicationProgram


An executable SL-GMS application program is created on PC-Intel systemsusing the nmake command. (This executable program reads the rulescontained in a file called "makefile" to compile and link an applicationprogram.) Each SL-GMS on-line example program in the demo directoryis distributed with a "makefile" file. Executing

nmake

in an on-line example subdirectory creates the executable program.

Any "makefile" file in the demo subdirectories containingC programs2 can be copied and modified to create a new "makefile" file forcompiling and linking an SL-GMS application written in C.

Each "makefile" file distributed with the on-line examples is composed of twoparts. The first part specifies

• the module order required for linking the SL-GMS Run-timeFunction Libraries and the Windows NT Libraries, and

• the system-specific options for compiling and linking applicationprograms.

The second part specifies

• the module order required for linking the application binary codemodules,

libsmsmap.lib Mapping Application Library

libsmsnew.lib Enhanced Screen Management System Library

libsmsnt.lib NT Screen Management System Library

2. The <non-C language> Interface Reference manuals provide complete information about compiling and linking applications in languages other than C.


(continued)



• the SL-GMS Run-time Function Libraries and the systemlibraries used for linking (by using variables defined in the firstpart), and

• the application-specific options for compiling and linking (such asspecial compiler flags).

The partial link32 command line that results from the rules specified in "make-file" is:

link32 -align:0x1000 -subsystem:console-entry:mainCRTStartup <object files><gms libraries> <system libraries>-out:<executable>

where,

<obj files> object files to link

<gms libraries> SL-GMS libraries in the following order:Note: the libsmsmap.lib library is only required if the application utilizes the SL-GMS Mapping Application Library

libsmsmap.lib libsmsnt.liblibsmsnew.liblibsms.liblibgmd.liblibdms.liblibgms.liblibgws.liblibgwsnt.lib

<system libraries> libc.lib, kernel32.lib, user32.lib, gdi32.lib, comdlg32.lib, winspool.lib

<executable> name of the ".exe" executable image

NOTE: The module order is important. System-specific arguments that result are not shown in the command lines above.


Sun systems

An executable SL-GMS application program is created by compiling theapplication source code modules and then linking the resulting binary fileswith the SL-GMS Run-time Function Libraries and the X Libraries.

The SL-GMS Run-time Function Libraries are distributed in$GMS_HOME/lib and are listed below.



“libdms.a” Datasource Management System Library

“libgmd.a” Graphical Modeling Dynamics Library

“libgms.a” Graphical Modeling Functions Library

“libgws.a” Graphics Workstation Library

“libgwsx.a” X Graphics Workstation Library

“libgwsxt.a” Xt Graphics Workstation Library

compile

link

ApplicationSourceCode

Modules SL-GMSRun-timeFunctionLibraries

ApplicationBinaryCode

Modules

XLibraries

ExecutableSL-GMS

ApplicationProgram


An executable SL-GMS application program is created on Sun systemsusing the SunOS make utility. (This utility reads the rules contained in afile called “Makefile” to compile and link an application program.) EachSL-GMS on-line example program in the demo directory is distributed witha “Makefile” file. Executing

make -n

in an on-line example subdirectory displays the link line required to createthe executable program.

Any “Makefile” file in the demo subdirectories containingC programs3 can be copied and modified to create a new “Makefile” file forcompiling and linking an SL-GMS application written in C. (Developers ofMotif applications should use the “Makefile” file in the demo/gms_motifdirectory.4)

Each “Makefile” file distributed with the on-line examples is composed of twoparts. The first part specifies

• the module order required for linking the SL-GMS Run-timeFunction Libraries and the X Libraries, and

“libsms.a” State Management System Library

libsmsmap.a Mapping Application Library

libsmsnew.a Enhanced Screen Management System Library

libsmsxm.a X and Motif Enhanced State Management System Library

3. The <non-C language> Interface Reference manuals provide complete information about compiling and linking applications in languages other than C.

4. The “Makefile” file for the gms_motif on-line example may need to be edited to recognize the proper libraries. The “Makefile” file specifies -lXm, -lXt, and -lX11 which assumes that the linker can find the appropriate libraries. If this is not the case, -lXm, -lXt, and -lX11 must be replaced with the full path name of the libraries.


(continued)



• the system-specific options for compiling and linking applicationprograms (for example, whether or not to use shared libraries5).

The second part specifies

• the module order required for linking the application binary codemodules,

• the SL-GMS Run-time Function Libraries and the systemlibraries used for linking (by using variables defined in the firstpart), and

• the application-specific options for compiling and linking (such asspecial compiler flags).

The partial cc linker command line that results from the rules specified in “Make-file” is:

cc ... -lsmsmap -lsmsx -lsmsnew -lsms -lgmd -ldms-lgms -lgws -lgwsx -lX11 -lsocket ...

For Motif applications, the partial cc linker command line that results from therules specified in “Makefile” is:

cc ...-lsmsmap -lsmsxm -lsmsnew -lsms -lgmd -ldms-lgms -lgws -lgwsxt -lXm -lXt -lX11 -lgen-lsocket ...

NOTE: The module order is important. System-specific arguments thatresult are not shown in the command lines above.The smsmap library is only required if the application utilizes theSL-GMS Mapping Application Library.

5. All executables distributed with SL-GMS are linked with stand-alone X libraries using the -Bstatic option.


Index
Symbols
"#" operator, GISMO input dynamics.5-2".dat" files.........................................3-61"2" dump code, for Prim class..........3-50"f" style button....................................A-3"f" style GISMO..................................A-1"flip" highlighting in GISMO..............A-35"fontdef.dat" file

creating in Windows...................9-11creating in Windows NT.............9-11

"m" style BUTTON .........................A-116"m" style button..................................A-3"m" style GISMO................................A-1.c files

userfctns ....................................3-39.cde file ............................................10-7.d1 files

definition ......................................F-2.dat files

colordef.dat ................................10-2definition .............................2-11, F-2fontdef.dat.................................... 9-5

.def filesdefinition ....................................2-13

.dxf files............................. 2-5, 10-6, D-4definition ....................................2-11

.g filesconversion to .m1 ......................12-5definition ...........................2-12, 2-13editing ........................................12-2

.i filesdefinition ....................................2-12

.m1 fileschanges not saved...................... D-2conversion to .g .........................12-5definition ....................................2-13

.m2 files ................................... 11-2, D-2definition ....................................2-13format.........................................11-3

loading........................................11-3saving.........................................11-3

.p1 filesdefinition.....................................2-13

.ps filesdefinition.....................................2-13

_ _button_hilite, in DynProp .......... A-108_ _button_index, in DynProp......... A-108_ _locator, in DynProp................... A-108_ _selected_object, in DynProp .... A-109_ _self, in DynProp........................ A-108

Numerics0 (unselected), gms_toggle_array( ) 5-251 (selected), gms_toggle_array( ) ....5-25

A

-a option, AutoCAD ...........................D-4action

range ..........................................3-43range scaling..............................3-43

Action FunctionsGISMO ............................... 5-5, A-53

action keyword, definition of...............3-7action, dynamic

conditional ....................................3-8definition of...................................3-2implicit ..........................................3-8unconditional ................................3-8

activate method........................E-8, E-10Ada programming language

applying to C on-line examples ....1-1animation

double buffering .........................3-48dynamic description ...................4-39graph ..........................................4-14Model .........................................4-10smooth .......................................3-48

application building...........................12-7application data ................................. F-1

SL-GMS Reference iVersion 6.2a- 26 May 2006

Index
application Xt event-loop function
external to SL-GMS .................... C-2Apply Xform .....................................11-2array variables .................................11-5

in dynamic descriptions .............3-52ASCII data files ................................2-11ASCII save of Models

m1g conversion script .................. 2-5ASCII screen-description files..........2-12ASCII to binary conversion ..............12-6aspect ratio ........................................ 8-7AutoCAD

-a option...................................... D-4-c option ...................................... D-4-cf option ..................................... D-4color ...........................................10-5-d option...................................... D-4-e option...................................... D-4-f option....................................... D-4files, conversion of ............... 2-5, D-4-t option....................................... D-5

autodeactflag, in generic State ..........E-4autoscale Graphs............................... 4-6axis labeling....................................... 4-4

B

background gridGraphs ................................4-3, 4-18

Bar Graph .......................................... 4-3batcherase dynamic action ..............3-46behaviors, State Instance ..................E-7binary to ASCII conversion ..............12-6bitplane mask...................................10-3bracket character

in Simple Roman font .................. 9-4Bstatic link option.............................. G-9button causing event.......................... 7-4BUTTON GISMO...............................A-3BUTTON GROUP GISMOs.............A-24button_state .......................................E-6

in DynProp .............................. A-109

C

C language programs................G-5, G-8-c option, AutoCAD ...........................D-4C++ programming language

applying to C on-line examples ....1-1caching SubModels........................11-19CALL GISMOs .................................. A-4callback

Keyboard Event......................... E-14Locator Event ............................ E-14String Event............................... E-14Window Event ........................... E-14

Cartographic Roman fontunderscore character ...................9-4

cc linker .............................................G-9-cf option, AutoCAD ..........................D-4Chart

dynamic......................................3-21CHECK button........................ 5-15, A-24Clear Redraw Mode .........................3-50clearflag, in generic State.................. E-4click (mouse), definition of..................1-1colarr4 GISMO ................................ A-78color

AutoCAD ....................................10-5change in Model.........................12-2Common Desktop Environment .10-7definition files .............................10-2

modification ..........................10-3index...........................................10-2management ..............................10-1palette

changing...............................10-2per Workstation ..........................10-1PostScript...................................10-4

colorcells GISMO ............................ A-77COLORCELLS GISMOs ................. A-76colordef.acad file ..............................10-5

SL-GMS Reference iiVersion 6.2a- 26 May 2006

Index
colordef.cde file................................10-7colordef.dat files...............................10-2
format of.....................................10-2colordef.grey files.............................10-4command file

error ...........................................12-2naming .......................................12-2

command filessee .g files

command interpretation ...................12-1compiling

application source code .............. G-4compiling, application source code... G-7Composite Graph............................... 4-4conditional dynamic action

definition of ..................................3-8Conditional dynamics.....................11-13Contiguous binary-executable

screen-description files ..............2-13conversion

ASCII to binary...........................12-6binary to ASCII...........................12-6of Model files...................... 12-5, D-1

conversion routinesfor date and time values ............4-23

converting Model files ......................12-5coordinate systems

conversion example.....................8-2World Coordinate System............8-4

coordinatesin ".g" file ....................................2-12Internal Coordinate System ......... 8-2

coordlimits........................................4-26GraphTrace................................4-30

copyfrom method..................................E-8customfree method................................E-8customized State

function definition.......................A-22customized State class

creation ........................................E-8

CYCLE GISMOs ............................. A-37cycle1 GISMO................................. A-38cycle2 GISMO................................. A-38

D

-d option, AutoCAD ...........................D-4d1flag, in generic State ..................... E-4data

application ................................... F-1as collection of variables ............. F-1file used as Datasource............... F-3methods to operate variables...... F-1sent to screen-controlled objects F-1

data files, see .dat filesdata linkage........................................2-4Data Management System Library....G-4Datasource

and SL-SMS................................ F-3Class ........................................... F-2in State Instances........................ E-6Instances of................................. F-2objects

freeing memory ..................... E-6memory allocation ................. E-6

see also Previewsimulation .................................... F-2types of........................................ F-2

Datasource Management System(SL-DMS) ............................ F-1, G-2

Datasource ManagementSystem Library ............................G-7

dateas axis on Graph ........................4-18conversion routines ....................4-23

datflag, in generic State .................... E-4DATSCREEN GISMO................A-7, E-3datscreen State behavior .................. E-7dbflag flag.........................................3-49DC (Device Coordinate) .....................8-2deactivate method....................E-9, E-10

SL-GMS Reference iiiVersion 6.2a- 26 May 2006

Index
default
double-buffering Mode...............3-50files

default settings.....................2-13Text fonts ..................................... 9-3

for SL-GMS............................ 9-1default window position...................... 8-9definevars method .............................E-8demo directory (SL-GMS)......... G-5, G-8Device Coordinates ........................... 8-2dispatching X events......................... C-2display assembly area

double buffering .........................3-48display dynamics

definition of .........................3-6, 3-11DISPLAY environment variable ........ C-3display process, streamlining...........11-9displaying a Model ............................. 8-4double buffer option .........................3-49double buffering ...............................11-4

animation ...................................3-48hardware....................................3-48marking for in SL-GMSDraw......3-49Modes ........................................3-50software .....................................3-48to minimize flicker ......................3-48

dummy variables..............................4-31dxf2g

conversion script .................2-5, 10-5utility................................... 10-5, D-4

dynamic actionaction types..................................3-5definition of ..................................3-2examples ..................................... 3-2move ............................................ 3-2types

Attribute..................................3-5Graph ..................................... 3-6Icon Switch............................. 3-6Point Changes .......................3-5

Text ........................................3-5Transformation .......................3-5User-defined...........................3-6

dynamic behavior .............................. F-2dynamic descriptions

adding to Model object ...............3-44array variables............................3-52definition of...................................3-6Dynamic Properties......................3-6expressions in ............................3-34format of .....................................3-27function calls in...........................3-34ranges in ....................................3-43Renamed Vars ...........................3-57syntax for display .......................3-27trigger .........................................3-30unconditional .................... 3-27, 3-28value, conditional .......................3-28

dynamic expressiondefinition of...................................3-7evaluation...................................3-52expression element ....................3-10valid elements ............................3-10

dynamic graphical objects..................3-2dynamics

actions........................................3-28display ..........................................3-6driven by array variables3-52, 11-10,

C-1driven by structure variables ......3-53GISMO .........................................5-2in non-replicating SubModels...11-16input ...........................................3-11optimized.................11-9, 11-10, C-1

dynarray dynamic action ..................3-52DynProp

attached to a GISMO ...................5-2attached to GISMO ....................3-11attached to Group ................... A-115conditional dynamics................11-13

SL-GMS Reference ivVersion 6.2a- 26 May 2006

Index
definition .............................2-3, 3-29display dynamics .......................3-11example .....................................3-36example GISMO ........................A-32execution order ..........................3-33expression ...............................11-13GISMO......................................... 5-3hierarchy ....................................3-33highlighting a GISMO................... 5-5input dynamics...........................3-11maximum length of ....................3-29optimizing memory space ............5-5Samples.....................................3-29SL-GML versus SL-GMSDraw...3-29space between = and * ..............3-29specifying in SL-GMSDraw..........3-6state_0 ("unselected") object ...A-115state_1 ("selected") object .......A-113structuring for optimization.......11-13
E-e option, AutoCAD........................... D-4echo characters .................................E-6ecolor action, example.....................3-32edge (Line) style ............................A-118edge color (ecolor).........................A-118Edit Data File window ......................3-61endsource keyword

preview ......................................3-65Enhanced Screen Management System

Library................................. G-5, G-8Erase Update Mode.........................3-50erasing objects.................................3-45error

in command file..........................12-2error 11 bad alloc.............................3-49error 9 bad drawable........................3-49error message

Preview ......................................3-41estyle attribute ...............................A-118

European, versions of SL-GMS .......2-14Event-handlers ...................................7-1

callback arguments ................... E-14in SL-SMS....................................7-1in State class............................... E-9methods .................................... E-12

Eventscodes............................................7-3Event Query functions..................7-6event query functions, examples..7-7input handler methods............... E-10modifier codes..............................7-4processing loop ........................... E-2processing sequence ...................7-1query functions, using ..................7-7timer ...........................................7-12types of...................................... E-14Window ..................................... E-14

ewidth action, example.....................3-31example, trend Graph ......................4-12expose Event .................................... E-2expression element

dynamic expression ...................3-10expressions

in dynamic descriptions...... 3-7, 3-34valid elements in ........................3-10

Extenteliminating calculation of ..........11-15for an object .............................11-14

externally-created window................8-13

F

-f option, AutoCAD ............................D-4f_call GISMO.................. A-4, A-5, A-112f_dscrn GISMO ................................. A-8f_fill GISMO..................................... A-41f_popup GISMO .............................. A-11f_quit GISMO .................................. A-14f_return GISMO............................... A-16f_scrn GISMO ................................. A-18

SL-GMS Reference vVersion 6.2a- 26 May 2006

Index
f_slide GISMO .................................A-56f_state GISMO.................................A-21f_textv GISMO .................................A-68fcolor attribute ................................A-118file
collection of Views and Models..2-13Noncontiguous binary-executable

screen-description..........2-13optimized for run time screen-load

performance...................2-13PostScript formatted

screen-description..........2-13suffixes recognized by SL-GMS 2-11

file conversion".dxf" to ".g" ................................. D-4".g" to ".m1"........................ 12-6, D-1".g" to ".m2"................................. D-1".m1" to ".g"........................ 12-6, D-1".m1" to ".m2"..................... 11-4, D-1".m2" to ".g"................................. D-2".m2" to ".m1".............................. D-2Model file to SL-GML

command file..................12-2Model files..................................12-2

filetypesconversion .................................2-11reserved suffixes........................2-11SL-GMS .....................................2-11

fill color (fcolor) ..............................A-118fill pattern

for fill color on monochrome ......10-1FILL PERCENT GISMOs.................A-40flag

batcheraseexample ...............................3-47

repairexample ...............................3-47

flickering, unwanted .........................3-48font

Cartographic Roman.................... 9-4

default ..........................................9-3default set

for SL-GMS ............................9-1defining.........................................9-5Hershey........................................9-4PostScript...................................9-14precision 1....................................9-4preloading ................................11-15scalable ................................ 9-2, 9-7Simple Roman..............................9-4TrueType family names..............9-10

fontdef program (Windows NT) ........9-11fontdef program (Windows)..............9-11fontdef.dat file

customizing ..................................9-5format ...........................................9-5PostScript Workstation...............9-13Windows NT....................... 9-9, 9-11X Window System ........................9-6XFontSet platforms ......................9-7

formal variables, Graphs ..................4-15format description strings, Graphs ...4-21format, of dynamic descriptions .......3-27formatting strings

in GraphAxes .............................4-17FORTRAN programming language

applying to C on-line examples ....1-1freeflag, in generic State ................... E-4function calls

in dynamic descriptions..............3-34Function Libraries

SL-GMS components..................G-1

Gg_struct_define( ) .............................3-53g_struct_member_define( ) ..............3-53G_WS_DBUFF_CLEAR...................3-50G_WS_DBUFF_ERASE ..................3-50G_WS_LOOKUP_COLORS ............10-7

X Workstation option ..................10-1

SL-GMS Reference viVersion 6.2a- 26 May 2006

Index
G_WS_NOPASTE Workstation option5-1generic State Class
attributes of ..................................E-4genlocfile utility.............................. D-14GISMO

"f" style.........................................A-1"m" style.......................................A-1Action Function Library ................ 5-3Action Functions ................ 5-5, A-53

definition of...........................3-12Action functions

syntax...................................A-81activation...................................... 5-1arrow shape .................................A-2BUTTON ......................................A-3BUTTON GROUP......................A-24BUTTON GROUP definition ......5-15BUTTON GROUP highlighting...5-25BUTTON type appearance ......A-112BUTTON type construction5-7, A-112CALL............................................A-4COLORCELLS...........................A-76compatibility with platforms..........A-2Constructing a "GISMO helper" .5-16constructing a CHECK GROUP.5-24constructing a RADIO GROUP..5-19construction .................................A-3customizing................................5-26CYCLE.......................................A-37DATSCREEN...............................A-7definition ...................................... 5-1definition of ..................................2-4diamond shape ............................A-2DynProp attached ........................ 5-2DynProp syntax ........................... 5-3FILL PERCENT .........................A-40fixed dimensions ......................A-112flat "f" style ...................................A-1functions in.................................3-12helper constructing ....................5-16

helpers ...................................... A-24highlighting behavior ....................5-5in SL-SMS................................... E-1input dynamics .............................5-2Library ..................2-4, 5-1, 5-28, E-2Manager ...................................... E-1Model names............................... A-2Motif "m" style ............................. A-1MULTIPLE SELECTION ........... A-44naming conventions .................... A-3output dynamics ...........................5-2POPUP...................................... A-10predefined ................... 2-4, 5-1, 5-27purpose ........................................5-1QUIT.......................................... A-13rectangular .................................. A-2RETURN ................................... A-15return value of Action functions....7-1sample construction .....................5-7scaling ..............................A-1, A-112SCREEN ................................... A-17SCROLLBOX ............................ A-44scrolling functions.......................5-26SLIDER ..................................... A-55STATE....................................... A-20State-changing ............................ E-3State-changing functions in......... E-4TEXTENTRY ARRAY ............... A-59TEXTENTRY VAR .................... A-67three dimensional look ................ A-1TOGGLE ................................... A-32toggle group ...............................5-15user-defined function....................5-3using...........................................5-26

GISMO action function"flash" behavior ......................... A-84"stayon" highlighting................ A-100color index variable, setting....... A-83create generic State class......... A-94create State Class..................... A-97

SL-GMS Reference viiVersion 6.2a- 26 May 2006

Index
cycle a variable ..........................A-83datscreen State class, creation..A-84deactivate event State .............A-100DynProp action ........................A-100exit SL-GMS ..............................A-94fill percent ..................................A-90highlight object...........................A-85highlight selected text ................A-92highlight Text Rectangle ............A-93interpolate ..................................A-98locator press ..............................A-85locator release ...........................A-81move slider box........................A-101radio button array.......................A-94radio buttons, index ...................A-95scroll ........................................A-105set array element .....................A-106set hiliteindex .............................A-96slider ..........................................A-90slider index...............................A-101State class installation ...............A-99text content ..............................A-104text entry ..................................A-102Text Rectangle.........................A-103Text Rectangle Group..............A-104toggle array element ................A-106
gismoflagand Event-handling...................... 7-1in generic State............................E-4

Glossary, SL-GMS.....................B-1, G-1gm1

conversion script ................ 12-6, D-1gm2 conversion script....................... D-1

gms_

gms_call( ) ...............................A-4, A-81gms_call1( ) .....................................A-81gms_color_select( ) ...............A-77, A-82gms_cycle_var( ) ...................A-37, A-83

gms_datscreen_state_invoke( )A-7, A-83, E-8

gms_flash( ) ... 5-4, A-4, A-7, A-10, A-13, A-15, A-17, A-46, A-84

gms_flash_call( ) ............................. A-84gms_fpercent_var1( ) .............A-41, A-85gms_hilite_color( )..............................5-6gms_hilite_color( )........ A-27, A-33, A-85gms_hilite_color_selobj( ) .....A-60, A-68,

A-86gms_hilite_color_var( )...........A-27, A-86gms_hilite_cycle( ) ...........................5-13gms_hilite_cycle( ) .................A-37, A-87gms_hilite_edge( )........ A-27, A-33, A-87gms_hilite_edge_selobj( ) .....A-60, A-68,

A-88gms_hilite_edge_var( )...........A-27, A-88gms_hilite_flip( ) ........... A-27, A-33, A-88gms_hilite_flip_var( ) ..............A-27, A-89gms_hilite_fpercent1( )...........A-41, A-90gms_hilite_percent1( )............A-56, A-90gms_hilite_percent2( )............A-56, A-91gms_hilite_vis( ) ..5-22, A-27, A-33, A-91gms_hilite_vis_var( ) .... 5-24, A-27, A-92gms_hilitescroll_array( ) .........A-53, A-92gms_hilitescroll_var( ) .. A-46, A-53, A-93gms_motif on-line example, resolving

problem with making ...................G-8gms_popup_state_invoke( )..A-10, A-93,

E-8gms_quit( ) ..................... A-13, A-94, E-8gms_radio_array( )....... 5-22, A-27, A-94gms_radio_var( ) .......... 5-23, A-27, A-95gms_radioscroll_var( ).. A-46, A-53, A-96gms_return( )..................................... E-8gms_screen_state_invoke( ) .A-17, A-97,

E-8gms_slider_var1( ) .................A-56, A-98gms_state_invoke( ).................A-20, E-8gms_state_pop( ) ...................A-15, A-99

SL-GMS Reference viiiVersion 6.2a- 26 May 2006

Index
gms_state_return( ) .........................A-99gms_stayon( ) ..................................A-20gms_stayon_call( ).........................A-100gms_text_array_slider_highlight( )...A-46gms_text_array_slider_hilite( )........A-53,
A-101gms_text_array_slider_var( ) A-46, A-53,

A-101gms_textentry_array( )...................A-102gms_textentry_var( ).. A-60, A-68, A-103gms_textload_array( )..........A-60, A-104gms_textscroll_array( )A-46, A-53, A-104gms_textscroll_lines( )A-46, A-53, A-105gms_toggle_array( )....5-25, A-33, A-106gms_togglescroll_array( ) .....A-46, A-53,

A-106

gmsAgmsAddLibPath( ) ............................11-4gmsAddUserFctn( ).................3-35, 3-39gmsAllVarsChanged( )...................11-10gmsAutoUpdateMode( ).................11-10

gmsBgmsBitmap( ) ...................................2-12

gmsDgmsDoubleBufferFlag( )...................3-50gmsDynInit( ) ...................................11-7gmsDynUpdArrayFlag( ) ................11-10gmsDynUpdate( ).............................11-6

gmsEgmsExtentMode(............................11-14gmsExtentMode( ) .........................11-10gmsExternalEventLoopFlag( ) ...C-2, C-3

gmsF

gmsFindObject( ) ...........................11-14

gmsI

gmsInitGismos( ) ............................... E-2

gmsM

gmsM2Save( )..................................2-13gmsM2XGet( ).................... 11-16, 11-19gmsMainInit( ) ................................... E-2gmsMainInitStr( )............................... E-2gmsMainLoop( ) ................................ E-2

using in Xt interface.....................C-2gmsMGSave( ) .................................2-12gmsModCacheCapacity( )..............11-20gmsModCacheCount( ) ..................11-20gmsModDynInitVarDefTable( ).........11-7gmsModInst( ) ..................................3-18gmsModNonReplicate( ) ................11-15gmsModPermanent( ) ........ 11-18, 11-19gmsMSave( )....................................2-13gmsMXGet( )...................... 11-16, 11-19

gmsNgmsNDCScale( ) ................................8-3gmsNoFlagsMode( ).......................11-10gmsNPXY( ) .......................................8-3

gmsOgmsObjFree( ) ...................... 3-48, 11-19

gmsPgmsProcessLowEvent( )

X interface ...................................C-3Xt interface ..................................C-2

gmsPSave( ) ....................................2-13gmsPsLViewWrite( )............... 9-16, 9-18gmsPsPolyMaxPoints( ) ...................9-18gmsPsViewWrite( )................. 2-13, 9-16gmsPsWsProcArgs( )............. 9-16, 9-18gmsPsWsProcArgsStr( ) ..................9-16

SL-GMS Reference ixVersion 6.2a- 26 May 2006

Index
gmsS
gmsStFreeAllVarDefs( )...................11-5gmsStM2Flag( ) ...............................11-4gmsStVarDefine( ) ...........................11-7gmsSubModReplicateMode( ) .......11-15

gmsT

gmsTPrec0RotFlag( ) ......................9-11

gmsU

gmsUpdate( ) ...................................11-6gmsUseShadowMode( ) .....11-10, 11-14

gmsVgmsVarChanged( ) ............................ 4-6gmsVarDefine( )

with optomized dynamics.........11-14gmsVarTypeDefine( ).......................3-53gmsVuRSave( ) ...............................2-12

gmsWgmsWCScale( )..................................8-2gmsWinFlags( )

setting of G_WS_NOPASTE ....... 5-1gmsWorkst( )

interfacing X................................ C-3using in SL-GMS/Xt interface ..... C-1

gmsWsDefaultOpts( ) ......................10-7gmsWsPort( )...................................3-48gmsWsPortXY( ) ..............................3-48gmsWsWind( ) .................................3-48gmsWsWindXY( ) ............................3-48

gmsZ

Graphautoscale ..................................... 4-6background grid ........................... 4-3components of ............................. 4-2creating ......................................3-21

customization of .........................3-22designing new ............................4-14dynamic......................................3-21format description strings ...........4-21GRAPHS subdirectory .................4-1grid in .........................................4-18Library ..........................................4-2positioning ....................................4-1Preview ......................................4-11Reference Point ...........................4-1renaming variables of...................4-4SL Graph Library........................3-21template ........................... 3-21, 4-14

designing..............................4-14tick marks .....................................4-4types of.........................................4-3

Graph template ................................4-30dummy variables ........................4-31example of general structure......4-37

GraphAxes ............................... 4-2, 4-16date and time .............................4-18

examples..............................4-22logarithmic....................................4-6non-graphic components............4-26object..........................................4-14

definition of ...........................3-22rescaling.....................................4-27types...........................................4-20used as grids..............................4-18variable limits ...............................4-5variables.......................................4-5

Graphical Modeling Dynamics ..........G-2Graphical Modeling Dynamics

Library .................................G-4, G-7Graphical Modeling Function ............G-2Graphical Modeling Functions

Library .................................G-4, G-7Graphical Modeling Language

(SL-GML) ...................................12-1graphical Models

SL-GMS Reference xVersion 6.2a- 26 May 2006

Index
refining .......................................12-1
Graphics Workstation Library ... G-4, G-7Graphics Workstation System .......... G-3GraphTrace...............................4-3, 4-28

actual data variables..................4-31coordlimits..................................4-30dynamics in................................4-31multi-color .................................... 4-7multi-linestyle ............................... 4-8non-graphic components of .......4-30object .........................................4-14object definition with SL-GML ....4-28object, definition of.....................3-22objects loaded with array of data4-36updating .....................................4-32variables ...................................... 4-5

graphtrace commandin SL-GML..................................4-28

grey-scale ........................................10-4grid

GraphAxes.................................4-18in graphs ....................................4-18

GroupDynProp example ......................5-23

GUI screen states ............................2-10GWS-X.............................................. C-1gwsx interface library ........................ C-1GWS-XT ........................................... C-1gwsxt interface library ....................... C-1

Hhelper button....................................5-16Hershey

font............................................... 9-4highlighting behaviors

GISMO......................................... 5-4hole

caused by erasures ...................3-45

I

IC (Internal Coordinate)......................8-2implicit dynamic action

definition of...................................3-8inheritance, of methods

States ........................................ E-10initialization, SL-SMS ........................ E-7initialize function

example..................................... A-22input dynamics

definition of.................................3-11input-event action

use of ...........................................5-4instancing Models

at run time ..................................3-18Internal Coordinate System................8-2Internal Coordinates...........................8-2IPC (Internal Pixel Coordinate) ..........8-2

JJapanese, versions of SL-GMS .......2-14

Kkeep_aspect_flag( ) method...............8-7key causing event ..............................7-4KEY_FILTER callback........................7-6key_filter method............................. E-12KEY_PRESS callback........................7-6key_press method........................... E-12KEY_RELEASE callback ...................7-6key_release method........................ E-12Keyboard Event................ 7-6, E-6, E-14keysymdef.h file .............................. E-14Korean, versions of SL-GMS ...........2-14

L

languages, non-C...............................1-1libdms................................G-2, G-4, G-7libgmd................................G-2, G-4, G-7

SL-GMS Reference xiVersion 6.2a- 26 May 2006

Index
libgms ............................... G-2, G-4, G-7libgws................................ G-3, G-4, G-7libgwsnt............................................. G-4libgwsx .............................................. G-7libgwsxt ............................................. G-7library
central SL-GMS C functions ....... G-1GISMO.......................... 2-4, 5-1, A-3

libsms................................ G-3, G-4, G-8libsmsmap................................. G-5, G-8libsmsnew................................. G-5, G-8libsmsnt............................................. G-5libsmsxm........................................... G-8link order

for SL-GMS applications..... G-6, G-9link32 command................................ G-6linking, binary files .................... G-4, G-7load times

compare M1 filer to M2 filer .......11-2loc_motion method ..........................E-12loc_press method ............................E-12loc_release method .........................E-12localization files

Unicode..................................... D-14localization of SL-GMS ....................2-14Locator Event........................... 7-6, E-14

Mm_call GISMO ...................................A-5m_dscrn GISMO................................A-8m_fill GISMO ...................................A-41m_popup GISMO...................A-11, A-16m_quit GISMO.................................A-14m_sboxm GISMO ............................A-48m_sboxs GISMO .............................A-48m_scrn GISMO................................A-18m_slideh GISMO .............................A-56m_slidev GISMO..............................A-56m_state GISMO...............................A-21m_textv GISMO ...............................A-70

m1g conversion script .......2-5, 12-6, D-1m1m2 conversion script ...2-5, 11-4, D-1,

D-2ma_call GISMO................................. A-5ma_popup GISMO .......................... A-11Main Functions, SL-GMS.................. E-2majorspacing....................................4-26majorticks .........................................4-16

spacing.........................................4-4make procedure file...........................G-5make utility ........................................G-8Makefile file .......................................G-8makefile file .......................................G-5mapping ............................................ E-1Mapping Application Library......G-5, G-8mapping_factor

description....................................8-9Marker

in Graphs......................................4-3maxtracelength.................................4-28md_button Model

DynProp .....................................5-19md_call GISMO................................. A-5md_dscrn GISMO ............................. A-8md_scrn GISMO ............................. A-18md_state GISMO ............................ A-21memory allocation ............................. E-6method

activate...................................... E-10deactivate.................................. E-10definevars..................................... E-10Input Event-handler................... E-10notrecognized............................ E-10reactivate................................... E-10suspend..................................... E-10types of........................................ E-9update ....................................... E-10user-defined .............................. E-10Window Event-handlers ............ E-10

minorspacing....................................4-26

SL-GMS Reference xiiVersion 6.2a- 26 May 2006

Index
minorticks.........................................4-16
spacing ........................................ 4-4mkpixmap: could not create pixmap

message ....................................3-49Model

display in external window .........8-13displaying in a window ................. 8-4file conversion............................. D-1functions required ....................... G-2instancing

at runtime.............................3-18nesting of ...................................3-18pan and zoom ............................8-13portability ...................................12-5setting name of ..........................8-12SubModels used ........................3-16transporting................................12-5Variable Definition tables ...........11-7window

default position.......................8-9setting location on screen ...... 8-9setting position .......................8-7setting size of ......................... 8-8

Model creationoptimization................................11-1

Model Dynamic Properties window..3-45Model Properties window.................3-44model_name( ) method....................8-12monochrome display........................10-1Motif applications, instructions for

compiling and linking .................. G-8Motif GUI builder tool ........................ C-2Motif standard ....................................A-1Motif widget....................................... C-1Motif, using SL-GMS with .................. 2-9mouse

click, definition of ......................... 1-1enable middle button ................... 5-1middle button

to activate a GISMO......... 5-1

right buttonto activate a GISMO .........5-1

movex and movey actions, example3-31ms_call GISMO................................. A-5ms_dscrn GISMO.............................. A-8ms_scrn GISMO.............................. A-18ms_state GISMO............................. A-21MULTIPLE SELECTION GISMOs .. A-44multiple Views ..................................12-7

printing .......................................9-16

NNative Control Objects .......................2-4NDC

(Normalized Device Coordinate) .8-1, 8-2

nested variables ...............................3-59nmake command...............................G-5noerase dynamic action ...................3-48

in non-replicating SubModels...11-17noerase option .................................3-50non-replicated SubModels .............11-15Normalized Device Coordinate Scale

Factorchanging.......................................8-3default value.................................8-3

Normalized Device Coordinates.........8-1View extent...................................8-5

Normalized Screen Coordinates (NSC) .8-2

Normalized Window Coordinatesdescription..................................8-10

Normalized Window Coordinates(NWC) ..........................................8-2

notrecognized methods................... E-10example..................................... E-11

NT Graphics Workstation Library ......G-4

Oobject

SL-GMS Reference xiiiVersion 6.2a- 26 May 2006

Index
dynamic graphical ........................ 3-2erasing .......................................3-45substitution for optimization .......11-4
Object Dynamic Properties option ...3-23Object Dynamic Properties window.3-23Object Flags window

doublebuffer...............................3-49noerase......................................3-50

Object Oriented Environment ........... G-3Object Renamed Variables option ...3-55Object Renamed Variables window.3-55object(s)

dynamicsediting ..................................3-23

renaming variables ....................3-55OLIT widget ...................................... C-1on-line example programs ........ G-5, G-8operating system idiosyncrasies....... G-3optimization......................................11-1

array variables ...........................11-5disable freeing SubModels ......11-18disabling calculation of extents 11-14disabling Shadow objects ........11-14font pre-loading........................11-15Model creation ...........................11-1object substitution ......................11-4scoping variables .......................11-5structuring DynProps ...............11-13SubModel cache ......................11-19suppress SubModel replication 11-15user-defined functions .............11-10Variable Definition tables ...........11-5

Optimization techniques ..................11-1optimized dynamics ...... 11-9, 11-10, C-1override

of Window Manager Quit option E-15

P

panchanging position of WC-window8-13

parametric instancingdefinition of.................................3-18for Graphs ..................................3-21in SL-DRAW...............................3-19

Pascal programming languageapplying to C on-line examples ....1-1

performanceenhanced ...................................11-5maximizing pixmap.....................3-49optimizing with Array Dynamics .3-52

permanent flag ...............................11-18pixmap

double buffering .........................3-48freeing ........................................3-48reconstruction.............................3-49

Plot Graph ..........................................4-3plotclear.................................. 4-34, 4-35plotreset ...........................................4-34plotshiftx ...........................................4-34plotshifty ...........................................4-34Polyline

in Graphs......................................4-3PostScript output........................9-17

Polyline limitPostScript output........................9-17

popflag, in generic State ................... E-5POPUP GISMO........................A-10, E-3popup State behavior ........................ E-7portability, of Model files........... 2-5, 12-5positioning a window..........................8-7PostScript

color ...........................................10-4default fonts..................................9-3fontdef.dat file.............................9-13output files..................................9-14polyline point limit.......................9-17printer .........................................9-14standard coordinates..................9-14standard mode ...........................9-14standard page size.....................9-14

SL-GMS Reference xivVersion 6.2a- 26 May 2006

Index
text .............................................9-14
precision, Text ................................... 9-2predefined State Instance..................E-7Preview

Graph.........................................4-11option .........................................3-61test data .....................................3-63variable

changing type.......................3-62Preview Options option

testingModel ...................................3-61

Preview Options window..................3-62printer

Postscript ...................................9-14printing to PostScript from code.......9-16programming languages .................... 1-1Project..............................................12-7project files.......................................2-13pscolordef.dat file.............................10-4

Qquery functions, for events................. 7-7QUIT GISMOs .................................A-13quitting an application

override of Window Manager Quit option .............................E-15

R

RADIO button ........................ 5-15, A-24RADIO GISMO ................................A-25radio3 GISMO..................................A-28radio-highlighting behavior...............A-53range

interpolation ...............................3-43scaling........................................3-43

ranges, in dynamic descriptions3-43, 4-4raster files

definition ....................................2-12import and export .......................2-12

manipulation...............................2-12SL-XImage File format ...............2-12Xwd format .................................2-12

reactivate method.....................E-9, E-10redraw action, example ....................3-32redraw dynamic action

in non-replicating SubModels...11-16Reference Point

Graph ...........................................4-1Renamed Variables Scrollbox............4-9RenamedVars ................................... A-3

and updating behavior................3-57example for RADIO GISMO ...... A-29

renaming variables...........................3-18example......................................4-12see also Rename Vars, SL-GMSDraw

rescaling, of GraphAxis ....................4-27reserved

variable names...............3-55, A-108resize Event ...................................... E-2RETURN GISMOs .......................... A-15reverse video....................................10-4RGB values ......................................10-2rotate action, example......................3-30rotation of precision 0

TrueType fonts)..........................9-11Run-time Functions, SL-GMS ............2-5

S

scalable Text fonts ..................... 9-2, 9-7scaling

GISMOs .................................. A-112Text fonts ............................. 9-2, 9-7

scoping variables .............................11-5screen

color index..................................10-4SCREEN GISMO .....................A-17, E-3Screen Management System LibraryG-4screen State behavior ....................... E-7screen State management ................ E-2

SL-GMS Reference xvVersion 6.2a- 26 May 2006

Index
SCROLLBOX GISMOs....................A-44scrollbox window..............................A-53scrolling functions
examples ...................................A-53scrolling menus................................A-53Shadow object

preventing the creation of ........11-14with object erasure...................11-14

Simple Roman fontsunderscore and bracket characters9-4

simulation Datasource .......................F-2SL Graph Library .............................3-21SL-DMS ..................................... 2-5, G-2SL-GMD............................................ G-2SL-GMF ............................................ G-2

coordinate-specifying to functions8-3SL-GML ...........................................12-1

example commands...................4-29SL-GMS

description of ............................... 2-1Glossary...............................B-1, G-1Main Functions ............................E-2

SL-GMS / X Interface........................ C-3SL-GMS / Xt Interface....................... C-1SL-GMS AX/Developer...................... 2-8SL-GMS C++/Developer.................... 2-8SL-GMS J/Developer......................... 2-9SL-GMS Mapping application library .2-6SL-GMS Run-time Function Libraries

directory location for ........... G-4, G-7SL-GMSDraw

purpose........................................ 2-3SL-GWS............................................ G-3SLIDER GISMOs.............................A-55SL-OOE ............................................ G-3SL-SMS .....................................E-1, G-2SL-SMS-WNT..................................2-10SL-SMS-XM.....................................2-10software double buffering ................3-48spacing, tick mark .............................. 4-4

special keys........................................1-1sprintf( )

using in SL-GMS/Xt interface......C-2st30flag, in generic State................... E-5startup sequence, SL-GMS..............10-3State Class

data structure, generic ................ E-5Event-handlers in ........................ E-9generic ........................................ E-5Instance components .................. E-5Instance, generic......................... E-5methods ...................................... E-9

STATE GISMO.........................A-20, E-3State Instances ................................. E-7

attributes of ................................. E-6inheritance of methods.............. E-10predefined ................................... E-7

State Management System Library...G-8State Management System

(SL-SMS) ..................... 2-5, E-1, G-2State object, definition....................... E-5State variable definition table ...........11-5state_0 object................................ A-114state_1 object................................ A-112State-changing GISMOs ................... E-3str_done method ............................. E-12String Events............................E-6, E-14structure variables............................3-53SubModel

cache........................................11-19disable freeing..........................11-18dynamic Chart ............................3-21dynamic Graph...........................3-21dynamic instancing.....................3-16dynamics in non-replicating......11-16instancing

at run time ............................3-18non-replicated

Variable Definition tables......11-7suppressing replication ............11-15

SL-GMS Reference xviVersion 6.2a- 26 May 2006

Index
used in construction of Models ..3-16using ..........................................3-16Variable Definition tables ...........11-7
SubModel(s)renaming variables ....................3-55

suffixes, file ......................................2-11suppressing replication

of SubModels...........................11-15suspend method ......................E-9, E-10

T

-t option, AutoCAD............................ D-5template

Graph.........................................4-14definition of...........................3-21

template designer, Graphs ..............4-18test data

preview ......................................3-63Text

change string in Model...............12-2default fonts ................................. 9-3

for SL-GMS............................ 9-1defined by .................................... 9-1DynProp object ..........................5-18fonts

scalable..................................9-7highlighting.................................A-53PostScript ..................................9-14precision ...................................... 9-2precision 1 fonts........................... 9-4scalable fonts............................... 9-2sizing behavior............................. 9-2

TextEdit object ...................................E-6in State Instance ..........................E-6

TEXTENTRY ARRAY GISMOs .......A-59textentry GISMO, variables for ........A-70TEXTENTRY VAR GISMOs ............A-67tick mark

axes ............................................. 4-4label ..................................4-16, 4-17

labeling.........................................4-4major ticks ..................................4-16minor ticks ..................................4-16on Graphs ....................................4-4spacing.........................................4-4

timeas axis on Graph ........................4-18conversion routines ....................4-23format .........................................4-19

timeofday variable, in DynProp ..... A-109Timer Events ....................................7-12toggle button

CHECK...................................... A-24RADIO....................................... A-24

toggle GISMO group ........................5-15TOGGLE GISMOs .......................... A-32toggle group .................................... A-24toggle3 GISMO ............................... A-34tprec0_rot_flag( )..............................9-11tracelength .......................................4-33traceline............................................4-28tracemarker ......................................4-28transformation

combining multiple .....................11-2transporting Models

between computers....................12-5traversal index..................................3-52trend Graph ........................................4-3

dynprop ......................................4-34example......................................4-13

trigger ...............................................3-30TrueType fonts .................................9-11type checking

preview variables .......................3-63

Uunconditional dynamic action

definition of...................................3-8underscore character, in Simple Roman

and Cartographic Roman fonts ....9-4

SL-GMS Reference xviiVersion 6.2a- 26 May 2006

Index
Unicode localization files ................ D-14unmapping.........................................E-1unwanted flickering ..........................3-48update method...................................E-9
description of .............................E-10inheritance of .............................E-10

updflag, in generic State ....................E-5User interaction..................................2-4user-defined

methods .....................................E-10user-defined function

example .....................................3-38GISMO......................................... 5-3in application program ...............3-39in dynamic descriptions .............3-35in DynProp .................................3-37previewing dynamics

error message......................3-41user-defined functions ...................11-10userfctns.c file..................................3-39

example .....................................3-39userfctns.o file..................................3-35userfctns_initialize( ) ...............3-35, 3-39

example .....................................3-41using SubModels .............................11-1usr_set_color( )................................3-37

Vvaluelimits ........................................4-26VarDefs

definition ......................................B-6variable

array...........................................11-5scoping ......................................11-5

Variable Definition tables .................11-5attached to Models ....................11-7

variable names, valid characters in .3-28Variable Reference ..........................3-28Variable Reference, definition of........ 3-7variables

as GraphAxis limits ......................4-5nested ........................................3-59renaming

example............................... A-38renaming GraphTrace ..................4-6reserved ......................... 3-55, A-108structure .....................................3-53types of, in Preview ....................3-62

video, reverse...................................10-4View

description....................................8-5printing .......................................9-16

view_ndc_extent( ) method................8-6view_wc_extent( ) method .................8-6view_wcextent..................................8-13ViewMgrState...................................8-13Views, multiple .................................12-7virtual workstations............................G-3vis action, example...........................3-30visflag, in generic State ..................... E-5visibility.............................................5-22

W

WC (World Coordinate)......................8-1WC-window

size of...........................................8-6widget

Motif ...........................................2-10Xt based

interfacing with SL-GMS..C-1win_destroy method...............E-13, E-15win_destroy_override method E-13, E-15win_enter method............................ E-12win_expose method ........................ E-12win_focus_in method ...................... E-12win_focus_out method .................... E-12win_leave method ........................... E-13win_map method............................. E-13win_position( ) method .......................8-9win_position_offset

SL-GMS Reference xviiiVersion 6.2a- 26 May 2006

Index
default value ..............................8-10description .................................8-10examples ...................................8-10
win_position_offset attributedefault value ..............................8-12examples ...................................8-11

win_position_offset( ) methodexample ....................................... 8-9

win_resize method...........................E-12win_unmap method .........................E-13Window

Events........................................E-14window

creation ........................................E-2default position............................. 8-9externally create ........................8-13positioning.................................... 8-7setting location on screen ............8-9setting the size............................. 8-8

Window Event-handler methods......E-10Windows NT

default fonts ................................. 9-3fontdef.dat file .............................. 9-9objects .......................................2-11using SL-GMS with ....................2-10

WinModState ..................................... 8-1Workstation(s)

raster file description..................2-12World Coordinate

View extent ..................................8-5World Coordinate Scale Factor (WCSF)

changing ...................................... 8-2default value ................................8-2

World Coordinate Scale Factor(WCSF)........................................ 8-4

World Coordinate System (WCS) ...... 8-4World Coordinates ............................. 8-1WsEvent class ................................... 7-6

X

X and Motif Enhanced State Management System Library ............................G-8

X as opposed to Xt............................C-3X error 11 bad alloc message ..........3-49X error 9 bad drawable message.....3-49X event gathering ..............................C-2X event-loop function

external, SL-GMS/X interface .....C-4X Graphics Workstation Library ........G-7X Interface.........................................C-3X Toolkit (Xt), SL-GMS interface.......C-1X Windows (X), SL-GMS interface....C-1X Workstation

default fonts..................................9-3XFontSet platforms

fontdef.dat file...............................9-7XK_ key symbol codes.................... E-14XListFonts( ).......................................9-7Xt Graphics Workstation Library .......G-7Xt Interface........................................C-1XtAppMainLoop( ) .............................C-2xvaluelimits.......................................4-30Xwd, raster file format ......................2-12

Yyvaluelimits.......................................4-30

Zzooming............................................8-13zoomrect( ) method ..........................8-13

SL-GMS Reference xixVersion 6.2a- 26 May 2006

sl-gms referencesldownloads.sl.com/docs/c++dev/6.2x/pdffiles/gref/gref.pdf · version 6.2a- 26 may...

Documents