Read SL-GMS Reference text version

SL-GMS® Reference

SL Corporation®

OBJECT-ORIENTED GRAPHICAL MODELING SYSTEM

Version 6.2a- 26 May 2006

Part Number GREF-360526

The information in this document is subject to change without notice and should not be construed as a commitment by the Sherrill-Lubinski Corporation. The Sherrill-Lubinski Corporation assumes no responsibility for any errors that may appear in this document. The software described in this document is furnished under a license and may be used or copied only in accordance with the terms of such license. This software is based in part on the work of the Independent JPEG Group. Symbol Factory TM artwork is licensed from Software Toolbox, Inc.

SL-GMS Reference

This manual is for use only in connection with the described software and may not be used for any commercial purpose or copied, distributed, sold, displayed, modified, published, or posted in whole or in part without the prior written permission of Sherrill-Lubinski Corporation. SL-GMS, SL Corporation, the SL Logo, and all Sherrill-Lubinski product names referenced in this manual are trademarks or registered trademarks of the Sherrill-Lubinski Corporation; any unauthorized use of these marks is strictly prohibited. All trademarks and registered trademarks referenced in this document are property of their respective companies. SL-GMS (6.2x) 26 May 2006 Configuration: C62a1_360526 Copyright (c) 1987-2006 Sherrill-Lubinski Corporation. All Rights Reserved. LIMITATIONS ON USE Use, duplication, or disclosure by the U.S. Government is subject to restrictions as set forth in the Technical Data - Commercial Items clause at DFARS 252.227-7015, the Rights in Data - General clause at FAR 52.227-14, and any other applicable provisions of the DFARS, FAR, or the NASA FAR supplement. SL CORPORATION 240 Tamal Vista Blvd. Corte Madera, CA 94925 CUSTOMER SUPPORT Phone 800.548.6881 (inside U.S.) 415.927.8400 Fax 415.927.8401 E-mail [email protected]

5/26/06

v6.2x

Part Number GREF-360526

Table of Contents

1. 2. SL-GMS Reference

How to use this manual ................................................................ 1-1

Overview of SL-GMS

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

3.

Dynamics

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

4.

Graphs

Introduction ................................................................................. 4-1 Using Graphs ............................................................................... 4-1

Version 6.2a- 26 May 2006

SL-GMS Reference

i

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

5.

GISMOs

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

6. 7.

The Enhanced State Management System

Introduction ................................................................................. 6-1

Event Handling

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

Version 6.2a- 26 May 2006

SL-GMS Reference

ii

8.

Display of Models

Overview ..................................................................................... 8-1 Coordinate systems ...................................................................... 8-1 Displaying a Model ..................................................................... 8-4

9.

Text

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

10. Color

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

11. Performance

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

12. The Graphical Modeling Language

Introduction ................................................................................. 12-1 Converting Model files ................................................................ 12-5 Projects ....................................................................................... 12-7

Appendix A --

SL-GMS GISMO Library Reference

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

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

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

Appendix B -- Appendix C --

Glossary SL-GMS Interface with the X Toolkit and X Windows

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

Appendix D --

Model Utilities

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

Appendix E --

The State Management System

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

Appendix F --

Datasource Management

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

Appendix G --

Linking SL-GMS applications

Introduction ................................................................................. G-1 Components of the SL-GMS Run-time Function Libraries ........... G-1 PC-Intel ....................................................................................... G-4

Version 6.2a- 26 May 2006

SL-GMS Reference

iv

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

Index

Version 6.2a- 26 May 2006

SL-GMS Reference

v

List of Figures

Number

Figure 2-1: Figure 2-2: Figure 3-1: Figure 3-2: Figure 3-3: Figure 3-4: Figure 3-5: Figure 3-6: Figure 3-7: Figure 3-8: Figure 3-9: Figure 3-10: Figure 3-11: Figure 3-12: Figure 3-13: Figure 3-14: Figure 3-15: Figure 3-16: Figure 3-17: Figure 3-18: Figure 3-19: Figure 3-20: Figure 3-21: Figure 3-22: Figure 3-23: Figure 3-24: Figure 3-25: Figure 3-26: Figure 3-27: Figure 3-28: Figure 4-1: Figure 4-2:

Title

Page

Attaching dynamics specifications to an object............................ 2-2 The SL-GMSDraw editor with the "buttons" palette active ............ 2-3 The SL-GMSDraw editor ............................................................. 3-1 DynProp containing two dynamic descriptions ............................. 3-7 DynProp with unconditional display dynamics ............................. 3-7 Dynamic description with conditional display dynamics ............... 3-8 SL-GMS encapsulates control object behavior ............................ 3-13 Control Object Palette (Windows) ............................................... 3-15 Control Object Palette (Motif) ...................................................... 3-16 Building the "meter" Model.......................................................... 3-17 Instancing the "meter" Model as an external SubModel ............... 3-18 An "aircraft" Model ...................................................................... 3-19 Instances of the "aircraft" SubModel in a cockpit screen.............. 3-20 Two Instances of the Graph template "lineplot"............................ 3-21 GraphAxis and GraphTrace objects ............................................. 3-22 A DynProp in the "Object Dynamic Properties" window ............... 3-24 A DynProp indented after pressing the "Apply" button ................. 3-25 A DynProp typed incorrectly with an error on line 3 ..................... 3-26 A dialog box displaying the location of an error ........................... 3-26 General syntax for display dynamic descriptions ......................... 3-27 DynProps are executed in depth-first object hierarchy order ........ 3-33 One unconditional and two conditional dynamic descriptions....... 3-36 A user-defined function in a dynamic description ........................ 3-37 "Model Dynamic Properties" window ........................................... 3-45 Diamond with dynamics to move over a static line ....................... 3-46 Diamond moving and erasing portions of the line ........................ 3-47 Diamond moving over the line ..................................................... 3-47 Renaming the "bg_color" variable in a Model Instance ................ 3-56 "Edit Data File" window............................................................... 3-61 "Preview Options" window........................................................... 3-62 A Graph consists of GraphAxes and GraphTraces ....................... 4-2 Graph showing use of tick spacing .............................................. 4-5

Version 6.2a- 26 May 2006

SL-GMS Reference

vi

Figure 4-3: Figure 4-4: Figure 4-5: Figure 4-6: Figure 5-1: Figure 5-2: Figure 5-3: Figure 5-4: Figure 5-5: Figure 5-6: Figure 5-7: Figure 5-8: Figure 5-9: Figure 5-10: Figure 5-11: Figure 5-12: Figure 5-13: Figure 5-14: Figure 5-15: Figure 5-16: Figure 5-17: Figure 7-1: Figure 8-1: Figure 8-2: Figure 8-3: Figure 8-4: Figure 8-5: Figure 8-6: Figure 8-7: Figure 8-8: Figure 9-1: Figure 9-2: Figure 9-3: Figure 9-4: Figure 9-5:

Graph with variables renamed (after Previewing) ........................ 4-10 Trend Graph that shifts to the left ................................................ 4-13 GraphAxis object with variables renamed to constants ................ 4-27 GraphAxis object with variables renamed to variables ................. 4-27 General structure of a GISMO DynProp ...................................... 5-2 Syntax of a typical GISMO DynProp ........................................... 5-3 Light switch ................................................................................ 5-7 Background pieces of the light switch ......................................... 5-8 Assembled background of the light switch ................................... 5-9 First part of GISMO .................................................................... 5-10 Two lines added to switch object ................................................. 5-11 "off_state" and "on_state" objects ............................................... 5-12 Placing the "off_state"/"on_state" Group on the background ........ 5-13 Examples of BUTTON GROUP type GISMOs .............................. 5-15 "GISMO helper" buttons .............................................................. 5-15 Parts of the "state_0" Group from the "md_button" GISMO.......... 5-17 Parts of the "state_1" Group from the "md_button" GISMO.......... 5-18 Three Instances before and after renaming variables .................. 5-20 Using an array to control a Radio Group GISMO ......................... 5-21 Using a single variable to control a Radio Group GISMO............. 5-23 An array variable used to control a CHECK GROUP GISMO ....... 5-24 Event-handling ........................................................................... 7-2 A Model in World Coordinate space ............................................ 8-4 Mapping a Model into a View object ............................................ 8-5 Two different View WC-extents .................................................... 8-6 Mappling of a Model into a window ............................................. 8-7 A "win_size" equal to (0.4, 0.3) ................................................... 8-8 A "win_position" equal to (0.5, 0.0) ............................................. 8-10 Normalized Window Coordinates (NWC) ..................................... 8-11 Some common "win_positin_offset" values ................................. 8-12 Default Precision 0 SL-GMS Fonts .............................................. 9-1 Default Precision 0 fonts across Workstation classes .................. 9-3 Precision 1 Hershey text fonts..................................................... 9-4 An example of SL-GMS "fontdef.dat" entries ............................... 9-5 Example "fontdef.dat" for the X Window System .......................... 9-6

Version 6.2a- 26 May 2006

SL-GMS Reference

vii

Figure 9-6: Figure 9-7: Figure 9-8: Figure 9-9: Figure 9-10: Figure 9-11: Figure 12-1: Figure A-1 Figure A-2 Figure A-3 Figure A-4 Figure A-5 Figure A-6 Figure A-7 Figure G-1

Sample "fontdef.dat" for a Japanese Sun Workstation ................. 9-7 Example "fontdef.dat" for a Windows NT system ......................... 9-9 An example of a Windows NT SL-GMS font name ....................... 9-11 Example "fontdef.dat" for a PostScript workstation ...................... 9-13 PostScript output for fonts with precision 0 or 2 ........................... 9-15 PostScript output for fonts with precision 1 .................................. 9-15 The SL-GML interpreter displaying the Model "cogen"................. 12-1 "GISMO helper" buttons .............................................................. A-24 The "state_1" object ................................................................... A-112 The "state_0" object ................................................................... A-113 The Group of "state_1" and "state_0" .......................................... A-114 Parts of the "state_1" Group ....................................................... A-117 Parts of the "state_0" Group ....................................................... A-119 The Group of "state_1" and "state_0" .......................................... A-121 The basic layers of the SL-GMS Run-time Function Libraries ...... G-1

Version 6.2a- 26 May 2006

SL-GMS Reference

viii

SL-GMS Reference

Sherrill-Lubinski

How to use this manual

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

Terminology clarification

The steps for the examples throughout this manual often state,

Click the ... button ... or Click the ... Pull-Down Menu and choose ...

Clicking a button, unless otherwise specified, refers to pressing and releasing the left mouse button. Clicking and choosing an option from a pull-down menu in the SL-GMSDraw editor refers to dragging -- pressing the left mouse button on the pull-down menu name, moving the mouse over the popped-up menu, keeping the left button depressed, and then releasing the 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 the characters "<", "R", "E", "T", "U", "R", "N", and ">".

Other programming languages

Following standard practices in software engineering, the examples in this book are presented in C, which has become the language of choice for tutorial examples in the literature. The C examples are still applicable when the functions are called in a different programming language.

Version 6.2a- 26 May 2006

SL-GMS Reference 1-1

12

2

Introduction

· · · · · · · · · · · · · ·

Overview of SL-GMS

SL-GMS (SL Graphical Modeling System) is a graphics software package used by developers to create and embed dynamic graphical screens into application 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 application deployment

Version 6.2a- 26 May 2006

SL-GMS Reference 2-1

Overview of SL-GMS

Figure 2-1: Attaching dynamics specifications to an object

Version 6.2a- 26 May 2006

SL-GMS Reference 2-2

Overview of SL-GMS

The SL-GMSDraw graphical editor, provided with a Development license of SL-GMS, is the primary tool used to create dynamic Models -- a collection of graphical objects that change in real-time in response to changes in application data. Models may be used as screens for the application or instanced as a component of another Model. Instances of several different Models may be placed together into a Palette. This Palette can be called up at any time and one or more of the predefined symbols can be selected for use 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 Properties option of the Dynamics Pull-Down Menu in SL-GMSDraw. Application development time is greatly reduced as dynamic specifications (and pro-

Version 6.2a- 26 May 2006

SL-GMS Reference 2-3

Overview of SL-GMS

gram state sequencing as described below) are built into Models, not into application code. Chapter 3 -- Dynamics provides detailed information about dynamics specification. User interaction is an integral part of a graphical interface. Operators must be able to control real-world, real-time processes through actions at the mouse and/or keyboard. This interaction is commonly conducted through interface controls: buttons, sliders, pull-down menus, scrolling lists, and text entry boxes. The native Control-Object Library supplied with the State-Class Library greatly reduces the programming effort necessary to create the complete graphical user interface for an application. In Windows 95 and Windows NT environments, native controls means Windows control objects and Windows NT control objects. In UNIX and OpenVMS environments, native controls generally means X-based Motif widgets.The support for native control sets in SL-GMS is encapsulated, generic, easy-to-use, and portable across Window Systems. Native controls can be added to any SL-GMS graphical Model. The developer can select any generic control in the library from a Palette in SL-GMSDraw. Native control attributes can be directly connected to application variables (as with any other graphical object in SL-GMS) to either display the value of the variables or to set them in response to user actions. In addition, pre-defined callback functions are automatically attached to these generic controls. The callbacks either set variables in response to actions or execute a message function with parameters attached to the controls. SL-GMS also provides GISMOs (Graphical Interactive Screen Management Objects) for user interaction. A large number of ready-to-use, predefined GISMOs are provided in the SL-GMS GISMO Library and described completely in Appendix A. In addition, any SL-GMS graphical object can have input dynamics attached to it, and be made into a GISMO. When selected, a GISMO can highlight, call user-defined callback functions, and/or change the current state of the application. Additional information about GISMOs is provided in Chapter 5 -- GISMOs. SL-GMS uses a data linkage technique that can be interfaced to any data acquisition system. Variable references in Dynamic Properties are bound with memory locations. When SL-GMS is notified of a change in the value at a specified memory location, the graphic objects associated with that value are updated automatically. The variable reference/memory bindings

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

Overview of SL-GMS

are organized in tables that deliver high performance updates. Access to a variable binding table can be restricted to a single State instance, or a group of State instances which localizes the data where it is needed and improves performance. Classes are provided to give the developer easy access to Model information at run-time. The list of variable references in a Model can be queried at any time. Once the list of variable references is obtained, they can be bound with data obtained from sockets, pipes, shared memory, or any other source of data. Linkage to data and variable scoping are described in Variable Handling in the SL-GMS Examples Manual. A currently evolving component of SL-GMS -- The Datasource Management System (SL-DMS) -- will ultimately eliminate all programming required 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 managing application states by encapsulating the basic elements (e.g., the active window-manager window, Model(s), event-handlers, complex user-interactions such as object selection, zoom/pan, and so on, and data sources) of dynamic graphical applications into State objects. State objects are implemented by the State Management System (SL-SMS) component of SL-GMS. SL-SMS is described in Chapter 6 -- The Enhanced State Management System. Many file converters are distributed with SL-GMS. For example, with the m1g script, Models may be converted to ASCII format for portability across all SL-supported platforms, for updating to newer versions of SL-GMS, and for global editing with any standard text editor. Another utility, dxf2g, converts AutoCAD ".dxf" (Data Exchange Format) files to SL-GMS ".g" (ASCII) Model files. The m1m2 script allows conversion of Models so that screen-Model input is accomplished in one quick read, thereby improving application performance. The SL-GMS run-time Functions, provided with a Development or a run-time license, are linked with the application program to load and run Models. Specific instructions for linking are provided in Appendix G.

Version 6.2a- 26 May 2006

SL-GMS Reference 2-5

Overview of SL-GMS

Mapping application library

Applications that use map and network data have special requirements due to the large number of objects and images, and the navigation and viewing techniques used with such large data sets. The SL-GMS Mapping application library provides developers with the capability of creating interactive, animated graphics that satisfy the needs of map and network based applications.

Support of Imported Vector Backgrounds

Utilities are provided for converting map data into SL-GMS Models that can be layered and tiled for increased viewing performance. A large, complex Map Model can be seperated into overlapping or stacked Models which serve as Map layers. For example, interstate highways in one Model, railroads in another Model, bodies of water in a Model, major streets in a Model, and neighborhood streets in a Model. Then, Map layers can be divided into adjoining rectangular Models called tiles.

Automatic management of Map tiles

The SL-GMS Mapping Library controls the movement of Models to and from memory based on the current view of the map. Only the visible tiles that fall within the current view of the Map are in memory.

Smooth Pan, Zoom and Decluttering

Many options are available with SL-GMS for panning and zooming Maps. The Map library supports continuous zooming and panning. Automatic and manual decluttering allows individual layers of the Map to be displayed or hidden. The zoom thresholds at which layers are hidden or made visible can be adjusted without any programming changes, simply by editing the layer configuration file.

Dynamic Vector Maps

Dynamic 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 Icons

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

Version 6.2a- 26 May 2006

SL-GMS Reference 2-6

Overview of SL-GMS

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

Non-Programmatic Configuration

The 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 stacking order and zoom thresholds for automatic decluttering.

Version 6.2a- 26 May 2006

SL-GMS Reference 2-7

Overview of SL-GMS

Programming frameworks

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

SL-GMS AX/Developer

SL-GMS AX/Developer enables users to create dynamic graphic displays using SL-GMSDraw and then animate these displays with live data from within any ActiveX container such as Visual Basic or MS Internet Explorer. The SL-GMS AX/Developer includes the SL-GMSDraw graphical editor, the SL-GMS ActiveX control, and example uses of the control in the Visual Basic and HTML environments. The developer is able to create sophisticated graphical user interfaces in Visual Basic or web scripting environments without writing any C/C++ code. The Models created with SL-GMSDraw are also portable to C/C++ or Java product environments.

SL-GMS C++/Developer

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

SL-GMS C++/Map

SL-GMS C++/Map is an extension to SL-GMS C++/Developer which allows for the inclusion of high performance dynamic geographical map displays and map icons within user interface applications. SL-GMS C++/Map includes the SL-GMS Mapping library and API , and traffic application frameworks. SL-GMS C++/Map is useful for traffic management systems, and utilities such as gas and power distribution who need high performance geographical maps and real-time dynamic graphics. The features of the SL-GMS Mapping library and API are described in the section Mapping application library on page 2-6.

Version 6.2a- 26 May 2006

SL-GMS Reference 2-8

Overview of SL-GMS

SL-GMS C++/Net

SL-GMS C++/Net is an extension to SL-GMS C++/Developer which provides functionality specific to the graphical user interface needs of telecom/network management application developers. SL-GMS C++/Net includes the Advanced Mapping libraries providing support for node and connectivity features, and network management application frameworks. SL-GMS C++/Net is useful for customers needing high performance cartographic maps, physical network diagrams, logical network diagrams, and equipment displays.

SL-GMS J/Developer

SL-GMS J/Developer allows for quick prototyping and rapid deployment of Java applications and Java applets that require high performance dynamic graphics. The SL-GMS J/Developer includes the SL-GMSDraw graphical editor, a code generator for Java, tools and source templates for Java applications and Java applets.

SL-GMS J/Net

SL-GMS J/Net is an extension to SL-GMS J/Developer which provides functionality specific to the graphical user interace needs of telecom/network management developers on the Java platform. SL-GMS J/Net includes the J/Net network library extension and associated API, network sysmbols library, telecom application frameworks and source templates. SL-GMS J/Net features Thin Client technology, high performance, customizable icons, industry standard icon library and automatic icon placement algorithms.

Integration with Motif GUI builders

To avoid the complexities of Motif programming, a growing number of large corporate and government developers begin application development using Motif productivity tools such as TeleUSE, UIM/X, or Builder Xcessory. These tools enable developers to build widgets interactively with drawing tools and to link events and callbacks to their code. SL-GMS provides the means to easily integrate dynamic graphics, designed with SL-GMS drawing tools, with the Motif widgets produced by the productivity tools and to

Version 6.2a- 26 May 2006

SL-GMS Reference 2-9

Overview of SL-GMS

extend the object-oriented appearance provided by Motif to encompass the functional aspects of the application. Further information about X integration is provided in Appendix C.

Integration with Visual C++ application frameworks

Under Windows NT, SL-GMS is compatible with window control code and application frameworks developed with Visual C++. Developers may use Visual 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 framework of the application.

Integrating graphics

The application provides SL-GMS a single widget or multiple widgets including a "drawing area" in which to draw. On-line examples distributed with SL-GMS show how widget creation and passing of the "drawing area" are done.

Extending the object-oriented appearance

Currently evolving sub-libraries of SL-SMS provide pre-canned States and SL-supplied callbacks that act as "wrappers" around Motif widgets. These "wrappers" eliminate much of the hand-coding ordinarily required to activate the widgets, feed data to be displayed in them, and define callback functions to control the application functions. In the resulting system process, GUI screen states follow the required system state changes, according to the overall object-oriented design, rather than forcing the system states to be driven by changes on the screens. Current SL-SMS sub-libraries provided are:

SL-SMS Sub-library SL-SMS-XM SL-SMS-WNT

Used for SL-GMS/Motif applications SL-GMS/Windows NT applications

Version 6.2a- 26 May 2006

SL-GMS Reference 2-10

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 distinguish between the file types, SL-GMS reserves the following file suffixes.

File Suffixes Reserved by SL-GMS Suffix .dat .dxf .g .i .m1 .m2 .p1 .ps .rc Description data file recognized by SL-GMS Preview utility for dynamics AutoCad ".dxf" (Data Exchange Format) files standard ASCII Model file raster (Bitmap) file (format dependent upon Workstation type) standard binary (noncontiguous) Model file compressed binary (contiguous) Model file Project files standard PostScript file resources file

".dat" files

Data files recognized by the SL-GMS Preview utility for dynamics are ASCII files which can be conventionally edited by any O/S editor. (Further information about preview ".dat" files is provided in the section Previewing the Dynamic Behavior of Objects on page 3-61.) The SL-GMS Preview utility is accessed via SL-GMSDraw's Preview Options option of the Dynamics Pull-Down Menu.

".dxf" files

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

Version 6.2a- 26 May 2006

SL-GMS Reference 2-11

Overview of SL-GMS

".g" files

ASCII screen-description files (".g") can be interpreted by SL-GML, produced by the SL-GMSDraw graphical editor, and/or conventionally edited by any O/S editor and transported to other SL-GMS platforms and environments. ".g" files can be created with the GML Script option of the Export submenu of SL-GMSDraw's File Pull-Down Menu (described in the section File Menu of the SL-GMSDraw User's Guide) or with the SL-GML gsave command. ".g" files can be created at run time with the gmsMGSave( ) function. All coordinates in a ".g" file have four significant digits after the decimal point. ".g" files can also be viewed with the View GML File option of the File Pull-Down Menu in SL-GMSDraw.

".i" files

Raster files can be imported for display in SL-GMS and exported for use by a variety of print/display device drivers. The format of the raster file is dependent upon the SL-GMS Workstation (e.g., X) in use. Workstation Raster File Description X 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

Raster files can be imported/exported with SL-GMSDraw's Import and Export options of the File Pull-Down Menu (described in the section File Menu of the SL-GMSDraw User's Guide). The raster files may also be manipulated programmatically with the gmsBitmap( ) and gmsVuRSave( ) functions. In previous versions of SL-GMS, raster files were imported/exported with a filename extension of ".i". SL-GMS now imports/exports images with the filename extension ".xwd" on Unix X systems, and ".bmp" on Windows 32 systems. Models that contain instances of Raster files with a filename

Version 6.2a- 26 May 2006

SL-GMS Reference 2-12

Overview of SL-GMS

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

".m1" files

Noncontiguous binary-executable screen-description files are produced by the SL-GMS drawing editor or user application programs and can be read by SL-GMSRUN. ".m1" files are created with the Save or Save as... option of SL-GMSDraw's File Pull-Down Menu or with the SL-GML save command. The ".m1" files can be created at run time with the gmsMSave( ) function.

".m2" files

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

".p1" files

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

".ps" files

PostScript formatted screen-description files can be accessed by any PostScript device drivers. PostScript output of Models can be created with the Print option of SL-GMSDraw's File Pull-Down Menu or can be created at run time with the gmsPsViewWrite( ) function. ".rc" files Files used to save and restore settings.

Version 6.2a- 26 May 2006

SL-GMS Reference 2-13

Overview of SL-GMS

Localization

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

Version 6.2a- 26 May 2006

SL-GMS Reference 2-14

3

Introduction

Dynamics

Figure 3-1: The SL-GMSDraw editor

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-1

Dynamics

Dynamic behavior is accomplished through actions which specify changes to be applied to the graphical representation in response to changes in application variables. All SL-GMS actions are directly implemented. For example, if a move action is specified in response to a change in the variable named position, the graphical object is moved via a transformation matrix. Some examples of 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 Amps

Fill and percent-fill of

Circles, Closed Splines, Rectangles, and Polygons

Version 6.2a- 26 May 2006

SL-GMS Reference 3-2

Dynamics

Examples of Dynamic Actions

(continued)

Sample Application

Dynamic Action

ALARM

black and red

Color

Visibility

Line style, Line width

Radius (of Circle)

34.5

Text replace, including digital-readout values and strings

Version 6.2a- 26 May 2006

SL-GMS Reference 3-3

Dynamics

Examples of Dynamic Actions

(continued)

Sample Application

Dynamic Action Text font and height

h hh

Graph axes and traces,

linear, log, and calendar/clock

Bars, pies, and charts

Version 6.2a- 26 May 2006

SL-GMS Reference 3-4

Dynamics

Actions

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

SL-GMS Action Types Action Type Attribute Description 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 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 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 graphical objects may be modified by replacing the Points that define the object

Transformation

Text

Point Change

Version 6.2a- 26 May 2006

SL-GMS Reference 3-5

Dynamics

SL-GMS Action Types

(continued)

Action Type Icon Switch

Description 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 changes to Graphs such as scaling limits, variable to drive a trace, and trace type, are included in Graph actions any changes may be specified in a user-defined function which is invoked via the call action in a DynProp

Graph

User-defined

Display dynamics

Display dynamics are specifications for changes to objects as a result of a change in an application variable. Any object, or individual object elements, may be driven separately by as many different variables as required. A dynamic description is 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. A DynProp (Dynamic Property) is all of the dynamic descriptions attached to an object.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-6

Dynamics

*

fcolor stat

dynamic description

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

DynProp

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 color indexed by the value of stat."

* fcolor stat

Figure 3-3: DynProp with unconditional display dynamics

fcolor is an action keyword. A complete table of all valid dynamic action keywords is provided in the chapter Dynamics Reference of the SL-GMS Quick Reference. stat is a Variable Reference. A Variable Reference can be identical to a variable in a programming language like Ada, FORTRAN, Pascal, or C. A Variable Reference can also be an expression -- a more complex entity involving formulas, function calls, data structures, files, and other data. Expressions can include any number of references to variables, or calls to application-specific functions and standard arithmetic and logical operators. Expressions are parsed for conventional notations. Actions in unconditional dynamic descriptions are executed whenever any Variable Reference in an object's DynProp changes. Compare this to the conditional dynamic description in Figure 3-4:. It specifies, "When the variable tankvol1 is within the indicated range, the object becomes per-

Version 6.2a- 26 May 2006

SL-GMS Reference 3-7

Dynamics

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

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

Figure 3-4: Dynamic description with conditional display dynamics

fpercent and fcolor are action keywords that change the fill-percent and fill color attributes of the object. tankvol1, tankmin1, and tankmax1 are Variable 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 Reference in an object's DynProp changes, or conditional -- action that occurs only when a specific variable is equal to a constant or within a certain range

Actions may also be: · implicit -- SL-GMS restores an object to its original state (or to an error state) when a variable falls outside any ranges specified by the user

DynProps are included as attributes of objects, along with other graphical attributes, all within the SL-GMS drawing editor. At runtime, whenever specified data variables change, SL-GMS automatically makes the correct sequence of library function calls to make specified changes on the screen. DynProps can be attached to SL-GMS objects using API calls in program code, or interactively with the SL-GMSDraw editor. This flexibility allows users to create an object to represent any underlying data quickly and test the dynamics immediately.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-8

Dynamics

Expressions

Expressions may be used wherever variables are allowed in dynamic descriptions. Expressions are always surrounded by a pair of parentheses. SL-GMS expression operators are similar to those defined in the C programming language. The complete list of expression operators is provided in the section Expression operators of the SL-GMS Quick Reference. Variables and constants can be combined in expressions. Constants can be either integer or real values, however; constants must correspond to the type of variables used or unpredictable results may occur. Constants which include decimal points are real values.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-9

Dynamics

The following elements are valid in expressions: Elements Valid in Expressions Expression Element A Variable Reference Integer, Real, and String Constants Unary and Binary Expressions Relational Expressions1 Function Call Expressions Description the name of a variable in the user's application may be used entries such as 2, 99, 234.45, "hello," and "STOP" are valid the ability to add(+), subtract(-), multiply(*), divide (/), or exponentiate (**) variables, constants, or the resultant variables of other expressions these include C operators that result in a true or false value i.e., >, <, >=, <=, ==, &&, || and != 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

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

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

(temp * 100) (((temp - 32) * 5 ) / 9) (temp * pres) (temp > 99) ((temp * pres) < 200)

Multiply temp by 100 Convert temp to Centigrade Multiply temp by pres TRUE if temp greater than 99 TRUE if product is less than 200

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-10

Dynamics

All variables used in an expression are attached to the same dynamic expression, so a change in any of the variables in an expression signals that the expression must be re-evaluated. Expressions can be used as the Variable Reference, the logical expression, and/or the action argument in a dynamic description. Below is an example of using an expression as a Variable Reference and as a logical expression: * stext tankvlv1 "%8.2f" ((tankvlv1 >= tankmax1) || (tankvlv1 <= tankmin1)) = 1 fcolor 4 tankvlv1 = (tankmin1+1):(tankmax1-1) fpercent 0:100 fcolor 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 variable goes above or below the range tankmin1 to tankmax1. When the variable is within the specified range, the object becomes percent-filled according to where in the range the variable falls, and the fill color is set to 2.

Input dynamics

Input dynamics are specifications for changes to objects as a result of an input Event. As mentioned earlier, GISMOs are objects that have input dynamics specified in their DynProps. The DynProp attached to a GISMO generally consists of two logical parts: 1. Input dynamics following a pound-sign ("#"), which include action(s) to manipulate SL-GMS internal or application program variable(s) and are performed when the GISMO is selected. 2. Display dynamics which include highlighting action(s) to be performed when the GISMO is selected. Typically these highlight-

Version 6.2a- 26 May 2006

SL-GMS Reference 3-11

Dynamics

ing actions are driven by the change in the SL-GMS internal or application program variable(s). Input dynamics are required for GISMOs. but typically are used. Display dynamics are optional

GISMO DynProps are generally placed on the GISMO Model, 1 although the DynProp may also be placed on any Model part such as a Group or an individual object. Often, the actions used in GISMO DynProps are call actions followed by a function 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 GISMO Action Functions provide optimized, special-purpose actions for behaviors that are often used. The actions used in the display dynamics portion of GISMO DynProps are generally functions which describe highlighting behaviors (usually following a gms_hilite_*( ) naming convention). Chapter 5 -- GISMOs and Appendix A provide a complete description of GISMOs and input dynamics.

Integration with native GUI control objects

Convenient user interaction with the screen in a windowing system is fundamental to a successful graphical user interface. Operators must be able to intuitively control real-world, real-time processes through mouse and keyboard interaction. This interaction can be conducted using control objects. 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 Interface are said to be "native" to that GUI. For example, the control objects native to the X-windows Motif systems are called widgets. Graphical objects built in SL-GMSDraw are completely compatible with widgets and other native GUI 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-12

Dynamics

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

Minimum programming

Encapsulating control object behavior within SL-SMS States frees the developer from the details of programming in the underlying Window System. In Windows NT environments native control objects are based upon the Microsoft Foundation Class Library. In Unix environments native control objects are X-based Motif widgets.

application variable native control object message to application application variable

Figure 3-5: SL-GMS encapsulates control object behavior With encapsulated behavior, there is no need to know details of Windows NT or Motif programming: the developer can concentrate on the interface solution and still receive the benefits. See Figure 3-5:.

Control object interface

SL-GMS supplies powerful functionality that solves the problem of including native control objects in application screens. Through SL-GMS encapsulation, native control objects can: · · Display or modify application variables. No programming is required to achieve this. Send a State message with parameters. Communication with the application is standardized and the application is automatically modularized. This separates the interface from the application.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-13

Dynamics

Programming effort necessary to create a complete interface for an application is greatly reduced by SL-GMS' encapsulation of native control objects. Data is presented and modified via control objects through a simple, direct-memory accessed table -- an approach that is consistent with all other objects in SL-GMS.

The Native Control Object Library

A library of the most common 32-bit Windows and Motif user interface controls is supplied in with SL-GMS. The controls are encapsulated for use with SL-GMS and organized in palettes for convenient use in SL-GMSDraw. The Control Objects provided in the library include: · · · · · · Push Button, Mode Button, Radio Button, Check Button, and 3-state Check Button Labels, Text Display and Text Edit Boxes (single and multi-line) Text List Boxes Scale Controls Various Container Controls Option menus

Version 6.2a- 26 May 2006

SL-GMS Reference 3-14

Dynamics

Figure 3-6: Control Object Palette (Windows)

Version 6.2a- 26 May 2006

SL-GMS Reference 3-15

Dynamics

Figure 3-7: Control Object Palette (Motif)

SubModels and dynamic instancing

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-16

Dynamics

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

Figure 3-8: Building the "meter" Model

Version 6.2a- 26 May 2006

SL-GMS Reference 3-17

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 which they are incorporated as External are automatically updated to reflect the changes. In SL-GMSDraw, Models can be nested within other Models to an arbitrary number of levels. Each Model Instance retains the dynamic properties of the original Model. Models may be instanced in the run-time application with the gmsModInst( ) function. Users differentiate Instance behavior by renaming variables associated with the original Model. The ability to instance Models and then attach different driving variables is called parametric instancing.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-18

Dynamics

Parametric instancing is achieved in SL-GMSDraw by interactively creating an instance and assigning new values or variables to each instance parameter. Each instance parameter can be assigned to a variable, a constant, an expression, or the value returned by a user function. For applications that need to dynamically instance objects, parametric instancing can be accomplished programmatically through API functions that are used to create an instance and assign values or variables to its parameters. For example, a voltmeter Instance of a meter Model might rename the variable m to volts, (where m is the variable controlling the original meter Model's dynamics), whereas an ohmmeter Instance might rename the m variable as ohms. The application program ultimately driving the display associates different Datasources with the two Instances. The aircraft icons, shown in Figure 3-10: and Figure 3-11: on page 3-20, are each a group of three instances of SubModels: speed bar, missile envelope and detection ring. The "speed bar" indicates the speed and direction of travel, the "detection ring" indicates the range of aircraft detection, and the "missile envelope" indicates a firing range. Instances of the aircraft SubModel are created at runtime by the application.

speed bar

missile envelope

detection ring

Figure 3-10: An "aircraft" Model

Version 6.2a- 26 May 2006

SL-GMS Reference 3-19

Dynamics

60 KM

RANGE

STATUS

NEXT

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

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-20

Dynamics

Charts and Graphs as dynamic SubModels

Parametric instancing is particularly valuable for Graphs, where the same basic Graph type may have several controlling parameters, such as value limits, x trace data, y trace data, background color, and so on. The SubModel, or template, may be instanced, as shown in Figure 3-12:, with different values set for each of its driving variables. To support dynamically changing graphs and charts, an extensive library of ready-to-use standard Graph templates are defined in SL-GMS. The SL-GMS Graph Library 2 includes trend graphs, pie charts, and logarithmic plots. Creating a working Graph involves simply instancing a Graph Model and renaming variables for tick mark spacing, axis limits, and other characteristics.

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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-21

Dynamics

In addition, customized graphs and charts are easily created through the use 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 is dynamically updated to plot individual Points or arrays of Points

GraphAxis GraphTrace (Polyline) GraphTrace (Markers) GraphTrace (Polyline/Markers)

Reference Point

major tick

minor tick

tick label

GraphAxis

Figure 3-13: GraphAxis and GraphTrace objects

These objects, along with the existing Graphical Primitive capabilities, provide all components necessary to construct complex, customized, dynamic charts and graphs consisting of any number or variety of axes and traces. Everything about the graph axes and traces functions in the same way as other Graphical Primitives, including a set of special actions to support the dynamic modification of any graph attributes (such as value limits and plot data).

Version 6.2a- 26 May 2006

SL-GMS Reference 3-22

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, and become visible or invisible. The proper syntax for dynamic descriptions is described in the section General syntax for display dynamic descriptions on page 3-27.

Editing Dynamics

Dynamic descriptions are normally attached to objects by using the Object Dynamic Properties option of the Dynamics Pull-Down Menu in SL-GMSDraw. The Object Dynamic Properties option displays the Object Dynamic Properties window. The Object Dynamic Properties window instances a simple text editor used to create or modify the object's dynamic description. No changes are actually 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 Dynamic Properties window. If multiple objects are on the Select List, use the Loop Control buttons in the Main Menu bar (refer to the SL-GMS®Draw User's Guide) to select the next object on the Select List. Click inside the Object Dynamic Properties window to begin editing. An example of a DynProp typed into the Object Dynamic Properties window is shown in Figure 3-14:.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-23

Dynamics

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

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 the next line to be typed. To insert a line, click at the end of the previous line and press the <RETURN> key. To modify a line, click the line, backspace over 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. To delete a line, either click on the line until the entire line is highlighted and press 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 button. This indentation, illustrated in Figure 3-15:, clarifies the grouping of the dynamic descriptions and the actions and variable tests within a particular dynamic description. The indentation has no effect on the execution of the dynamic description.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-24

Dynamics

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

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 Dynamic Properties window in a hold buffer. The contents in the hold buffer are held until quitting SL-GMSDraw or until changed by clicking the Hold button again. Leaving the Object Dynamic Properties window does not affect the hold buffer, nor does changing between Models affect it. The Release button replaces the current contents of the Object Dynamic 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 Dynamic Properties window to its original content.

Error checking

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-25

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 in Figure 3-17: on page 3-26, will display indicating the line in which the error occurs. Click the OK button to acknowledge the error. Correct all errors and click the Apply button again. The DynProp will then appear indented, as illustrated in Figure 3-15: on page 3-25.

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

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-26

Dynamics

General syntax for display dynamic descriptions

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

SL-GMS Editor Syntax SL-GML Syntax

Unconditional (direct) * action <argument> . . . Conditional Variable Reference = value action <argument> . . . (Variable Reference\ ( = value\ (action <argument>)\ (...))) (*\ (action <argument>)\ (...))

OR

Variable Reference = * action <argument> . . .

OR

(Variable Reference\ ( = *\ (action <argument>)\ (...)))

Conditional with value range Variable Reference = value1:value2 action <argument> . . . (Variable Reference\ ( = value1:value2\ (action <argument>)\ (...)))

Figure 3-18: General syntax for display dynamic descriptions Actions in unconditional dynamic descriptions are executed whenever any Variable Reference3 in an object's DynProp changes. Testing of a conditional dynamic expressions occurs whenever the tested variable, or any variable in the dynamic expression argument changes. However, actions in conditional dynamic descriptions are only executed whenever the testing of any logical expression results in TRUE after reading the value of a Vari3. <argument> can contain Variable References.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-27

Dynamics

able Reference. When an asterisk ( * ) is used in a conditional dynamic description, the object is updated whenever the variable or any variable in the arguments in the action(s) changes. NOTE: Unconditional dynamic descriptions must be specified before any conditional dynamic descriptions in an object's DynProp. Unlike other types of dynamic descriptions, unconditional dynamic descriptions are executed once upon initialization of dynamics with gmsDynInit( ). This initial execution allows for unconditional dynamic descriptions consisting solely of constants to be executed once. For example, an unconditional dynamic description can be used to cause a text label to appear on an object upon the first display of a Model. DynProps which contain solely unconditional dynamic descriptions are the most efficient DynProps. More information about efficiency in dynamics is provided 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 ASCII characters, except the parenthesis, "(" or ")", are valid if preceded by a backslash ("\"). A variable name must begin with the letters "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 on page 3-34. The value used in a conditional dynamic description may also be a range of values, specified by using two values, separated by a colon rather than a single value. In the case of a value range, the conditional action is performed when the value of the variable falls within the range specified by the two values. An action may be any of the actions listed in the section Dynamic actions of the SL-GMS Quick Reference, and include changes to objects' attributes, orientation, and Text. A conditional or an unconditional dynamic description may have a list of actions. All actions are performed in the order in

Version 6.2a- 26 May 2006

SL-GMS Reference 3-28

Dynamics

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

Evaluation of sample DynProps

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

EXAMPLE 1 Sample DynProp:

trigger = 1 plotdata x y The plotdata action is executed only when trigger = 1. The value of trigger is tested whenever trigger, x, or y changes. NOTE: It is the application program's responsibility to constrain the data values to those which work correctly for a DynProp. In the above example, trigger should be set to 1 by the application program only when both x and y are available.

EXAMPLE 2 Sample DynProp: 4

y = * plotdata x y The plotdata action is executed whenever x or y changes. The SL Graph templates distributed in the GRAPHS subdirectory are

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-29

Dynamics

set up with this type of dynamic description so that a trigger variable is not necessary. NOTE: It is the application program's responsibility to call gmsVarChanged( ) on both x and y at the same time. It is important to recognize that, in a conditional dynamic description utilizing the asterisk as shown above, the actions are performed not only when the variable has changed, but also if any of the variables (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, its rotation from 0 to -90 degrees is interpolated automatically by SL-GMS. The rotate action is conditional upon the value of volts 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), is equal to 1. When the expression is false (volts is less than or equal to 120), its value is 0. The vis action makes an object visible when its argument is 1, and invisible when its argument becomes 0. Because this action begins with an asterisk, it is an unconditional action.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-30

Dynamics

EXAMPLE 5 Sample DynProp (two conditional dynamic descriptions):

var1 = 4 ewidth 3 var2 = * movex var2 movey var3 The ewidth action is executed only when var1 is equal to 4. The movex and movey actions are executed only when var2 or var3 changes. The above DynProp is not equivalent to:

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

* movex var2 movey var3 var1 = 4 ewidth 3 The movex and movey actions are executed whenever var2 or var3 changes or whenever var1 changes. The ewidth action is executed only when var1 is equal to 4. NOTE: It is important to recognize, as shown in the second DynProp above, that unconditional dynamic descriptions are executed whenever any Variable Reference in a DynProp changes.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-31

Dynamics

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

* redraw var1 = 4 ecolor 2 In the above DynProp, the redraw action is executed whenever var1 changes. The ecolor action is executed only when var1 is equal to 4.

Sample DynProp (one conditional dynamic description):

var1 = * redraw In the above DynProp, the redraw action is executed whenever var1 changes. NOTE: The redraw action is intended to be used as part of a conditional dynamic description. If redraw is used as part of an unconditional dynamic description, it is only executed if some other conditional dynamic description is executed.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-32

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 Graphical Modeling Hierarchy determines the order of DynProp execution. DynProps are executed beginning with the DynProp for the topmost object in the SL-GMS Graphical Modeling Hierarchy, all the way down to the DynProp for the lowest-level object in the hierarchy using a depth-first path down 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 so on. DynProps for all objects on the same level in the hierarchy are executed in the order in which the objects were added to the system.

Model M1

-- DynProp

DynProp -- Group

G

Instance -- DynProp I

Circle -- DynProp C

Rectangle P1

DynProp

Line P2

Text P3

Model M2

-- DynProp

DynProp DynProp DynProp --

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 to the Model itself, so that DynProp is executed first. (Attaching dynamics to a Model is explained in the section Adding dynamics to a Model object on page 3-44.) Because the Group G was the first object created in the Model, the DynProp for that object is the next one executed. Then the DynProps for the three parts that comprise the Group (P1, P2, and P3) are executed in the order that the parts were added to the Group. The DynProp for the Model Instance I is executed followed by the DynProp for the

Version 6.2a- 26 May 2006

SL-GMS Reference 3-33

Sector P1

Sector P2 -- DynProp

Dynamics

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

Using function calls

A set of function calls can be used as a Variable Reference, the logical expression, and/or the action argument in a dynamic description, including function calls taken from the standard C Language Math Library. For example, a dynamic description that moves an object with respect to the logarithm of a variable appears as follows: time = * movex time pres = * movey log(pres) This dynamic description moves the associated object along the x axis with changes in time, and logarithmically along the y axis with changes in the variable pres. NOTE: To ensure proper DynProp evaluation, the function name must be followed immediately (i.e., with no spaces) by an open parenthesis, the argument list, and a closing parenthesis. A table of function call sets (with return types) currently available begins with the section Standard C-Library functions recognized in DynProps of the SL-GMS Quick Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-34

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 function convertToAngle( ) is called with the argument pres, and the returned value is used as the argument to the rotate action. * rotate convertToAngle(pres) To use the user-defined function capability, the developer should perform the following: · Create a "userfctns.c" module that includes: the user-defined functions with the proper parameters and return values; and the function userfctns_initialize( ); In the userfctns_initialize( ) function, include a call to the function gmsAddUserFctn( ) for each of the user-defined functions; The "userfctns.c" module is compiled to produce "userfctns.o" and then added to the Makefile for the developer's application and the application is re-linked. "userfctns.o" is added to the Makefile for the SL-GMS editor, as described in the section Adding a function to a SL-GMS editor on page 3-42, and the editor is re-linked.

·

·

·

The steps outlined above are described in the following sections.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-35

Dynamics

Creating a user-defined function

The DynProp shown in Figure 3-20: is attached to a Filled Rectangle object that displays the value of a variable. This DynProp will be used as an example of the procedure used to create a user-defined function and incorporate it into a developers application and into a SL-GMS editor. * stext temperature "%7.2f" fcolor 0 tcolor 7 ecolor 0 (temperature > hialarm) = 1 fcolor 3 tcolor 7 ecolor 0 (temperature > criticalT) = 1 fcolor 1 tcolor 0 ecolor 7

Figure 3-20: One unconditional and two conditional dynamic descriptions The value of temperature will be displayed whenever temperature, hialarm or criticalT changes. However, the fill color (fcolor), edge color (ecolor) and Text color (tcolor) of the Filled Text Rectangle will vary depending on the 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 temperature is greater than criticalT, the fill color is 1, edge color is 7 and the Text color is 0. If temperature is less than hialarm and criticalT then the edge color and fill color are 0 and the Text color is 7.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-36

Dynamics

The DynProp shown in Figure 3-20: on page 3-36 can be optimized 5 by providing a user-defined function, usr_set_color( ), to perform the conditional 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 other DynProps.

The usr_set_color( ) function is passed four arguments. The first argument is _ _self. _ _self is an internal SL-GMS variable set equal to the id of the object that has the associated DynProp attached to it. _ _self has to be passed (as an id data type) if an attribute of the object is to be changed or 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 the function. The other three variables are temperature, hialarm and criticalT.

5. Chapter 11 provides information concerning optimization and performance.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-37

Dynamics

The usr_set_color( ) function looks like: int usr_set_color(object, variable, hi_alarm, critical_alarm) id object; /* Text Rectangle object displaying value of variable */ double variable;/* value of variable being displayed */ double hi_alarm;/* hi alarm value */ double critical_alarm;/* critical alarm value*/ { /* check if value of variable is greater than the value of critical alarm value */ if (variable > critical_alarm) { gmsTColor (object, 0); gmsFColor (object, 1); gmsEColor (object, 7); } /* check if value of variable is greater 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 and hi alarm */ else { gmsTColor (object, 7); gmsFColor (object, 0); gmsEColor (object, 0);

Version 6.2a- 26 May 2006

SL-GMS Reference 3-38

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 increases performance. Less information is read from the ".m1" file and the execution is done in a compiled function, rather than interpreted at run time. In addition, if the conditional dynamic descriptions are to be used in other DynProps, only the call to the usr_set_color( ) function has to be typed instead of multiple lines to do the comparisons and set the different attributes.

Adding a function to an application

To utilize the usr_set_color( ) function a "userfctns.c" module is created by the developer which contains the definition of all of the user-defined functions. The "userfctns.c" module also includes the userfctns_initialize( ) function. Inside the userfctns_initialize( ) function, all of the calls to gmsAddUserFctn( ) are placed. User-defined functions are defined by the application program with gmsAddUserFctn( ) to identify the function, its name, return type, argument count, and argument type. 6 The gmsAddUserFctn( ) function is described in the SL-GMS Function Reference. There is no limit to the number of user-defined functions for an application.

The "userfctns.c" module

This 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 the definition of the userfctns_initialize( ) function. Each user-defined function 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-39

Dynamics

#include "gmsc.h"

int usr_set_color(object, variable, hi_alarm, critical_alarm) id object; /* Text Rectangle object displaying value of variable */ double variable; /* value of variable being displayed */ double hi_alarm; /* hi alarm value */ double critical_alarm;/* critical alarm value */ { /* check if value of variable is greater than value of critical alarm*/ if (variable > critical_alarm) { gmsTColor (object, 0); gmsFColor (object, 1); gmsEColor (object, 7); } /* check if value of variable is greater 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 and hi alarm*/ else { gmsTColor (object, 7); gmsFColor (object, 0); gmsEColor (object, 0); }

Version 6.2a- 26 May 2006

SL-GMS Reference 3-40

Dynamics

return 1; } (code continued on next page) int userfctns_initialize( ) { static int args1p3d[] = {G_POINTER, G_DOUBLE, G_DOUBLE, G_DOUBLE}; /* add function to set color of text and edge 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 then added to the Makefile for the user's own application. This will allow the user's application to execute the user-defined function at run time. The user-defined function can be added to dynamic descriptions of objects using a SL-GMS editor. However, if the Model containing the user-defined function is exercised using the Preview capability in the editor, 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's application program but it has not been linked into the SL-GMS editor

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-41

Dynamics

Adding a function to a SL-GMS editor

Linking the user-defined functions into the SL-GMS editor allows the user-defined functions to be executed whenever the Model is tested using the Preview capability in the editor.

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

UNIX Systems:

make

NT Systems:

nmake

Version 6.2a- 26 May 2006

SL-GMS Reference 3-42

Dynamics

Ranges in dynamics

In dynamic descriptions, each action may take a range rather than a single value. A range is a pair of values separated by a colon. The type of the two range parameters can be mixed because these values are handled internally as real numbers. Examples of Action Ranges 1:4 -12.5:14.0 0.:100. Ranges can be used in actions after the equal sign in a conditional description. For example, the following dynamic description is conditional upon the 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 range used 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 interpolated automatically by SL-GMS according to the value of the variable within the total range allowed by the variable's range. When pres equals 0, the fpercent is also 0, but when pres equals 200, the fpercent is 100. At the middle of the range, the fpercent is 50. In the following example, the object is scaled from 1 to 5 times in both the x and y directions, based upon the value of pres. If pres equals 100, the scaling is 5, and if pres equals 50, the scaling is 3 (halfway between the two values). pres = 0:100 scale 1:5

Version 6.2a- 26 May 2006

SL-GMS Reference 3-43

Dynamics

The second value of a range can be less than the first. In this case, the mapping of values works the same way, that is, the first value after the variable maps to the first value in the action range: pres = 0:200 fcolor 4:1 Values of the variable pres from 0 to 49 map to the color 4, from 50 to 99 map 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 to add dynamics to a Model object itself. In an SL-GML ".g" file, the DynProp for a Model is placed directly after the name of the Model, not, as might be expected, after the endm command that 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 selecting the Dynamics option in the Model Pull-Down Menu. The Model Dynamic Properties window is displayed, as shown in Figure 3-22: on page 3-45.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-44

Dynamics

Figure 3-22: "Model Dynamic Properties" window The dynamic scripting language (described in the section General syntax for display dynamic descriptions on page 3-27) is used to add dynamics to the Model. Type the dynamic script into the Model Dynamic Properties window and click the Apply button.

Erasing objects and holes

Objects are erased by either clearing the entire View where the objects appear or by redrawing the objects in the background color. Except in double-buffered applications, erasure by redrawing is the standard way of erasing objects. Erasure by redrawing is unnoticeable except when erasing one object leaves a "hole" in another object. Holes caused by erasures occur as a result of transformations and changes in visibility. If two objects overlap, a hole is created in the first object when the second object is drawn. This erasure is the default behavior. As the DynProps in the Model are being executed (The section DynProp execution on page 3-33 provides further information), the first object is marked for erasure and redrawn before the DynProp on the second object

Version 6.2a- 26 May 2006

SL-GMS Reference 3-45

Dynamics

is executed. This can be modified by grouping the two objects and using batch erasure. With batch erasure, as the DynProp for the Group is being executed, all objects which are marked for erasure are erased first and then they are redrawn (i.e. there are two passes through the nodes of the DynProp for the Group; one for erasure and one for redraw). Batch erasure is accomplished by using the batcherase action. The objects which are affected by the batch erasure must be in a Group or a separate Model (placing dynamics on a Model object is explained in the section 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 the Group is redrawn.

EXAMPLE

Figure 3-23: illustrates a diamond object with attached dynamics that move the 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 the line is erased. A "hole" marking each previous position of the diamond appears in the static line.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-46

Dynamics

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

In order to move the diamond without erasing portions of the line, dynamics must be attached that will erase both the line and diamond objects and then redraw them. This is the purpose of batcherase. In order to move the diamond without erasing portions of the line, dynamics must be attached that will erase both the line and diamond objects each time, x_pos, the variable driving the movex dynamic action of the diamond, changes and then redraw them. The line and the diamond are made into a Group. The dynamics for the line and diamond Group are as follows: group . repairflag 1 . batcherase 1 With the repair flag set to G_ON for the Group, whenever the diamond is redrawn the line is automatically redrawn. With the batcherase flag set to G_ON for the Group, both the line and the diamond are erased first and then redrawn as illustrated in Figure 3-25:. The diamond moves over the line without erasing it.

Figure 3-25: Diamond moving over the line

Version 6.2a- 26 May 2006

SL-GMS Reference 3-47

Dynamics

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

Double buffering

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

Software double buffering

Software double buffering is provided on X and Windows platforms and uses a pixmap (a rectangular array of pixels) to implement an off-screen buffer. This pixmap is attached to a Graphical Primitive object and is used as an intermediary display location or display assembly area, before the Workstation/Window is updated. The object and all its parts are completely drawn in the pixmap and the pixmap is then copied to the Workstation/Window for display on the screen. The pixmap is sized to the extent of the object and is initially cleared in the current background color. The pixmap for an object is freed whenever any of the following conditions occur: 1. the internal transformation matrix (move, scale, rotate) changes for an object (or for any object higher in the Graphical Modeling Hierarchy, 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( ))

Version 6.2a- 26 May 2006

SL-GMS Reference 3-48

Dynamics

The pixmap is reconstructed during the next display pass. In order to maximize program performance, the application programmer/screen builder should construct double-buffered objects so that the six conditions listed above rarely occur. Since software double buffering slows down the display of objects, only those objects that must be double-buffered should be marked. For example, it is better to make a Group and mark it than to simply mark the entire Model, since the pixmap for the Group will likely be smaller than the pixmap for the Model.

Error Message

If software double buffering is used on large objects or Workstation/Windows on some X servers, the following error message sequence 8 may appear:

X error 11 bad alloc X error 9 bad drawable mkpixmap: 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 buffering. As some platforms are limited in their off-screen drawables (which is what pixmaps are), the above error messages appear when double buffering occurs. These error messages result each time SL-GMS attempts to create a pixmap that the system cannot provide. The basic limitation is that the server runs out of off-screen drawable memory. If SL-GMS detects this error has occurred, it turns double buffering off for an object that is to be drawn using software double buffering for that particular display pass. Therefore, the object flashes as it is erased and redrawn.

Flagging Groups

In SL-GMSDraw, objects are marked for software double buffering using the doublebuffer option of the Object Flags window.9 The dbflag flag should not be set on individual objects being transformed; excessive overhead results because the pixmap for each object must be freed and recon8. 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-49

Dynamics

structed on each display pass. Rather, the objects should be grouped with the dbflag flag placed on the Group. The Group should have a background object (such as a Rectangle) with an extent large enough to cover all possible extents that may occur with the foreground object(s) traversal so that the extent of the Group does not change. In many cases, it is faster to avoid the erasure of foreground objects in a Group. This optimization can be accomplished by setting the noerase option of the Object Flags window on the Group and attaching the following DynProp 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 software double buffering; the command is described in the chapter SL-GML Reference of the SL-GMS Quick Reference. In an application program, the gmsDoubleBufferFlag( ) function enables or disables software double buffering on an object. The function is described in the section Dynamics -- double-buffering in the SL-GMS Function Reference. The dump code "2" is included in the permanent flags for the Prim class to indicate that an object is marked for software double buffering. Software double buffering can be set for Graphical Primitive and Workstation/Window objects.

Double-buffering Modes

Double buffering is set for Workstation/Window objects by means of the G_WS_DBUFF_ERASE or G_WS_DBUFF_CLEAR Workstation option bits as described in the gmsWorkst( ) function in the SL-GMS® Function Reference. In software double buffering, a pixmap sized to the extent of the window is used. SL-GMS has two Double-buffer Modes: Erase Update (set with G_WS_DBUFF_ERASE) and Clear Redraw (set with G_WS_DBUFF_CLEAR). Erase Update Mode is the SL-GMS default.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-50

Dynamics

In Erase Update Mode, Workstations/Windows are drawn in the back buffer in the same manner as in Single-buffer Mode: objects that have changed are erased and redrawn. After the buffers are swapped, or pixmap is copied, the drawing is repeated in the back buffer so that the two buffers are in phase. In Clear Redraw Mode, a Workstation/Window is cleared and completely redrawn in the back buffer before the buffer swap or pixmap copy. After the buffer swap, or pixmap copy, no drawing occurs in the back buffer/pixmap. Clear Redraw Mode is used for Workstations/Windows in which most of the objects are continually changing. Time is saved by avoiding a selective erase. In summary, Erase Update Mode is desirable when only a few objects on the screen are changing. Clear Redraw Mode is preferable when many objects 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);

Version 6.2a- 26 May 2006

SL-GMS Reference 3-51

Dynamics

Dynamics driven by array variables

In many applications that use SL-GMS, much of the data presented are in the form of arrays. These data may be arrays of text strings, arrays of integers or reals, or even arrays of user-defined structure types (which may contain other structures). SL-GMS provides the ability to reference array member elements from within dynamic expressions, using the standard "bracket" syntax: array[index] Referencing of array-member elements is particularly useful in accessing arbitrary array elements from different screen graphical elements. In addition to this basic capability, it is permissible to omit the index expression from within the brackets in a dynamic expression. When such a dynamic expression is evaluated, the index of the current part within the owning 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 index passed down is used to access the array. In this way, a single copy of a SubModel 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 effective way to optimize performance for any screen which contains rows or columns of information, either strings, integers, reals, or structures.

SL-GMD Syntax

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

Additional SL-GMD Action

(mark a Group, Model, or Instance so it passes the index of each part down as the traversal index to 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 dynarray

Version 6.2a- 26 May 2006

SL-GMS Reference 3-52

Dynamics

action provides for the default case where the Group, Model, or Instance is to 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 dynamics in this way.

Limitation

Array 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 are as follows: 1. Define the application's data structures. 2. For each structure, use gmsVarTypeDefine( ) to tell SL-GMS the size and structcode of each data structure. structcode must be in the range 0x200 - 0x2000. 3. Use g_struct_define( ) for each structcode to place them in the Structure Definition Table. The syntax is: int g_struct_define (structcode) int structcode; 4. Use g_struct_member_define( ) to define each member of each structure. The syntax is: int g_struct_member_define (structcode, member_name,member_offset, member_typecode, size1, size2) int structcode; char *member_name; char *member_offset; int member_typecode;

Version 6.2a- 26 May 2006

SL-GMS Reference 3-53

Dynamics

int size1; int size2; 5. Use gmsVarDefine( ) to inform SL-GMS of the address and type of each structure. A single variable name identifies the entire structure.

Limitations

The current implementation of DynProp structure access has the following limitations: · · · only single-level structures are allowed (i.e., var1.value) gmsVarChanged( ) must be called on the entire structure, not on individual members GISMOs do not work on structure members because GISMOs do not 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 data type for the expected structure member. 2. Create custom GISMOs that are limited to specific structure types, or 3. If a specific structure member must be accessed, create a standard variable name for it with gmsVarDefine( ) (i.e., for var.status, use var_status). As of this release, SL-GMS provides this interim version of the DynProp access to data structures which will be further enhanced in future releases. For example, the g_*( ) functions, to define structures, may be changed.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-54

Dynamics

Renaming variables

SL-GMS allows you to reuse Models and control objects through instancing. Model Instances, also called Instances or SubModels, retain the dynamic properties of the original Model. The various Instances are differentiated from the original by renaming variables -- the driving variables are renamed to different variable names. For example, when you develop a panel of gauges used to represent the same process variable coming from many different sites, a gauge Model is created with dynamic specifications driven by the variable volts. The panel Model would then be created with a collection of gauge Model Instances. The volts variable is renamed for each instance. For example, volts1, volts2, and so on. Use the Rename Vars tool in SL-GMSDraw to rename the variables of a SubModel that have been instanced into a Model. To use the Rename Vars tool, select an object, click on the Dynamics Pull-Down Menu, and select Object 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 selected object is not a Model Instance, the Object Renamed Variables window will be empty, since the object does not have any variables that need to be renamed.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-55

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 edited, either double-click on another value or hit the <ENTER> key. Click the Apply button to apply the renamed variables to the object. The Apply 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 multiple Model Instances are on the Select List, use the Loop Control buttons in the Main Menu bar (refer to the SL-GMS®Draw User's Guide) to select the next object on the Select List.

Hold, Release, and Clear

The Hold button holds the contents of the entire Object Renamed Properties window in a hold buffer. The contents in the hold buffer are held until quitting SL-GMSDraw or until changed

Version 6.2a- 26 May 2006

SL-GMS Reference 3-56

Dynamics

by clicking the Hold button again. Leaving the Object Renamed Variables window does not affect the hold buffer, nor does changing between Models affect it. The Release button replaces the current contents of the Object Renamed Variables window with the contents of the hold buffer. The Clear button clears the Renamed Variable strings of all the variables in the Object Renamed Variables window.

Error checking

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

RenamedVars and updating behavior

If a DynProp contains both unconditional and conditional dynamic descriptions and the Variable References in the conditional dynamic description are renamed as constants, the object is marked for update before the Variable Reference associated with the unconditional dynamic description is initialized. Unconditional dynamic descriptions are always performed when an object is marked for updating, regardless of the Variable Reference.

EXAMPLES

The fcolor action is unconditional, and the stext action in the example below is conditional:

Sample DynProp on a Filled Text Rectangle:

* fcolor box_color box_name = * stext box_name %s

Version 6.2a- 26 May 2006

SL-GMS Reference 3-57

Dynamics

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

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

box_color = * fcolor box_color box_name = * stext box_name %s

EXAMPLE

Objects are not marked for update during display of a Model or after a call to gmsDynInit( ) in an application program unless 1. all the variables in DynProps on the objects are renamed to constants, or 2. all variables are defined and have been marked for update with gmsVarChanged( ) 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-58

Dynamics

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

Nested variables

When SL-GMS Models are nested, their Renamed Variables are also nested. For example, an Instance of a Model containing an Instance of another Model would contain all variables of both Models. Intermediate renaming occurs when a SubModel's variables are renamed to other variables.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-59

Dynamics

EXAMPLE

A meter Model contains a DynProp that uses a variable value to rotate a needle. A panel Model contains two Instances of meter. In one Instance, value is renamed volts, in the other instance it is renamed amps: value::volts value::amps (RenamedVars for first Instance) (RenamedVars for second Instance) The Renamed

A master_control Model contains two Instances of panel. Variables for the two Instances might look like: volts::volts1 amps::amps1 volts::volts2 amps::amps2

(RenamedVars for first Instance)

(RenamedVars for second Instance)

NOTE: Variables that have been renamed to constants in a SubModel are an exception; they cannot be renamed further. The nested renamed variables feature enables rapid construction of dynamic objects with complex behaviors. Renamed variables may be attached to complex SubModels within Models to any level of nesting.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-60

Dynamics

Previewing the Dynamic Behavior of Objects

A Model must be saved if it has been edited, before the dynamics can be exercised. In addition, while it is being previewed, the Model cannot be edited or saved. After previewing, the Model is automatically reloaded so that any changes made by the dynamic updating are discarded. Selecting the Preview Options option of the Dynamics Pull-Down Menu in SL-GMSDraw, exercises the DynProps in the current Model using data contained 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 window must be invoked. This is done by clicking the Dynamics Pull-Down Menu and selecting the Edit Data File option. Text can then be entered in this window which will create or modify a ".dat" file. If a data file already exists for this Model, that data file is automatically displayed in the Edit Data File window. Clicking the Save File button writes the file to disk. Clicking the Open File button displays a dialog window which allows entry of the name of a data file.

Figure 3-27: "Edit Data File" window Further information about the format and use of ".dat" files is provided in thesections Variable types in "preview" on page 3-62, and Using test data for "preview" on page 3-63.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-61

Dynamics

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

Figure 3-28: "Preview Options" window

The Preview Options window controls the Timer Period (the number of milliseconds between each update). Click the Start button to load the "<modelname.dat" file 11 and begin previewing the Model. Clicking the Stop button terminates the preview. Clicking the Pause button suspends dynamic updating without leaving Preview Mode but the Model cannot be edited or saved. NOTE: If another Model is opened while a Model is being previewed, the newly-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, based upon the absence (integer) or presence (real) of a decimal point, or a string with the presence of double quotes. Trying to set the variable to a different type later results in an error because there is only one global name space for 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 3-62

Dynamics

Since some type checking is required by preview, variables and their corresponding values should be entered consistently. For example, the user may choose to use only real values with actions which cause transformations and integer values with actions which produce attribute changes.

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, or it can be an existing data specification file (which can also be edited in the Edit Data File window).12 Both methods require the same format for test data. A basic line of data contains a variable name and value pair, separated by a space, one pair per line. A blank line signals SL-GMSDraw to update the dynamic descriptions of objects. No changes appear in the Model until a 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 keywords can be used to automatically generate trigonometric, incremental, or random values for dynamic variables. The data format for preview is specified completely in the section Previewing dynamics of the SL-GMS Quick Reference manual.

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

Version 6.2a- 26 May 2006

SL-GMS Reference 3-63

Dynamics

Using the "source file" command for "preview"

The source file command is provided to load data in an array. Before the source file command can be used, the array variables must be declared, along with the size of each array. After the source file command, a data format is specified. For example, to load three arrays with high, low, and closing 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 three floating 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 data format section specifies that high, low, and closing values follow in this order until a blank line or <END-OF-FILE> is encountered, and that there may be up to 100 triplets of data. One, or many, triplets may be present on the same line and carriage returns, spaces, and tabs are ignored; however, a blank line terminates collecting data for the arrays. In the next example, a source file named "bridge" contains up to 365 integers representing the number of vehicles crossing a bridge for a year. A second set of data, also in the same file, represents the high temperature for the day. The step keyword is used to supply ascending date data and the source file keyword is used to read the file containing the counts and temperatures: int date[365] int counts[365] float temperature[365] date step 0 364 0 1 source 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."

Version 6.2a- 26 May 2006

SL-GMS Reference 3-64

Dynamics

temperature... endsource The "bridge" file should contain 365 integers for the vehicle counts, followed by a blank line, then 365 floating point temperatures. NOTE: If a source file does not contain as many data items as specified in the declaration, the size of the array is changed to reflect the number of points read. If there are more data items than fit in the array, the last element in the array continues to change until the last datum is read (a blank line or <END-OF-FILE> is encountered). When using the step or sine keywords with an array, the entire array is updated each time a blank line or <END-OF-FILE> is encountered. The source 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 specifications. float high[100] float low[100] float closing[100] source file "portfolio" high low closing... endsource int date[365] int counts[365] float temperature[365] date step 0 364 0 1 source file "bridge" counts... temperature... endsource

Version 6.2a- 26 May 2006

SL-GMS Reference 3-65

4

Introduction

Graphs

SL-GMS provides facilities for using a variety of Graph types in a flexible manner. In SL-GMS, Graphs are Models and are used by instancing them in another Model. After instancing a Graph, the Instance can be moved, rotated, or scaled. Finally, the variables which control scaling and labeling of the GraphAxes, and which drive the GraphTraces, are renamed to constants or to other variables. The SL Standard Graph Library contains the Graph types shown in the chapter The SL-GMS Graph Library of the SL-GMS Quick Reference. Each Graph is identified by its file name in the GRAPHS subdirectory. Most users are able to use one of the Standard Graph types; however, if an application requires a Graph type that is not listed in the chapter The SL-GMS Graph Library of the SL-GMS Quick Reference, it can be created by using any of the objects in SL-GMS. The section Designing new Graphs on 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 provides more information about instancing SubModels. The SL Standard Graph Types are stored in the GRAPHS subdirectory of the SL-GMS demo/graphs demo directory. The Reference Point used for positioning 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 lower left 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 variables are renamed. It is therefore advisable to leave room for them, below and to the left or right of the axes. The user should remember that when positioning Graphs, the rectangular area on which the values are plotted (inside the axes) overwrites any other

Version 6.2a- 26 May 2006 SL-GMS Reference 4-1

Graphs

objects. This rectangular area is erased when the Graph is initialized or the plots are cleared. Once the Graph SubModel has been instanced, the Instance can be moved, rotated, or scaled until it has the desired orientation and size. Before using a Graph from the Standard Graph Library, the user needs to copy the Graph Model file to the working directory. Any of the Graph Models in the GRAPHS subdirectory can be modified by other users on the system, or through future releases of SL-GMS. Making a copy of the Model guarantees that the Models which reference this Graph will continue to work as expected in the future.

Graph components

GraphAxis GraphTrace (Polyline) GraphTrace (Markers) GraphTrace (Polyline/Markers)

Reference Point

major tick

minor tick

tick label

GraphAxis

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

SL-GMS Graphs consist of two basic components: GraphAxes and GraphTraces. A GraphAxis consists of a Line, major and minor tick marks, and tick mark labels. When using the Standard Graph Library, the user need only choose

Version 6.2a- 26 May 2006

SL-GMS Reference 4-2

Graphs

the upper and lower limits for the GraphAxis and pick the spacing between the tick marks. SL-GMS creates the tick marks and tick mark labels. Most often the limits on the GraphAxis are known in advance. It is also possible to re-initialize a GraphAxis so that the limits and labels are modified and the axes and any plotted Points are re-displayed. GraphAxes that use date and time labels can also be created. Most Graph types also contain at least one GraphTrace. GraphTraces can be collections of Polylines, Markers, or both. The number of Points in each GraphTrace object is under user control, as is the color and style of the GraphTrace. Graphs usually also contain a background grid. The use of GraphAxes objects to construct a background grid is described in the section Grid GraphAxes on page 4-18. Graphs might also contain a background Rectangle and some sort of Text label.

Graph types

Four kinds of Graphs are established through the dynamic descriptions within the Graph: Plot Graphs, Trend Graphs, Bar Graphs, and Pie Graphs. 1. Plot Graphs are Graphs which plot data given a horizontal and a vertical position for each Point. Plot Graphs are the simplest type of Graph. 2. Trend Graphs work like the recording plotters which utilize a pen writing on a drum or roll of paper. In trend Graphs, only the vertical position of a Point to be plotted is specified. The horizontal position, the starting Point, stays the same. As more Points are added, the plot shifts left or right leaving the most recently plotted Point at the starting horizontal position. The direction which the trend plot shifts is under the user's control, as is the starting Point 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 Rectangles to display data. 4. Pie Graphs have no GraphTraces and use Filled Wedges of varying arc lengths to display data.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-3

Graphs

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

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 be displayed. The values of these required variables must be set before the Graph 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 Values

The range of values that can be plotted is determined by the minimum and maximum values for each axis. For example, if the values for the horizontal axis range from 0 to 1000, the minimum x value is 0 and the maximum x value 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 are real numbers and can have decimal parts. For example, it is possible to have a range from .120 to 1.115 if necessary. Some Graphs have date and time axes, which make it possible to label GraphAxes with ranges of date values (days, months, quarters, years) or time values (hours, minutes, seconds).

Tick Spacing and Labeling

The spacing between major and minor tick marks should be chosen so as to adequately mark the axes. The major tick marks, which have labels assigned to them, should be close enough to clearly identify positions on the axis. However, if the major spacing is too small, the labels will crowd -- even overwrite -- each other. For best results, tick marks should be chosen that divide evenly into the axis range. For example, if the range is 0 to 1000, using 100 as the major tick spacing produces eleven tick labels. Minor tick spacings should evenly divide into the major tick spacings. If 100 is the major tick spacing, 20 for the minor tick spacing creates four tick marks between each major (labeled) tick mark.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-4

Graphs

If the major tick spacings used do not evenly divide the range, one end of the 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 tick marks every 100, and minor tick marks every 20. The vertical axis ranges from .12 to 1.2, with a major tick spacing of .09 and a minor tick spacing of .03.

Graph showing use of tick spacing

Even with the unusual range on the vertical axis, both axes are neatly labeled. On the horizontal axis, the major spacing of 100 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 its maximum on an axis, a different major tick spacing is used, one which evenly divides the range.

Figure 4-2: Graph showing use of tick spacing

Using variables for axis limits

It is possible to use variables instead of constants when setting the value limits on GraphAxes and GraphTraces. These variables must be set to some value before the initialization of the Graph.

Version 6.2a- 26 May 2006 SL-GMS Reference 4-5

Graphs

Value limits on GraphAxes and GraphTraces can be reset. The Graphs in the SL Standard Graph Library include dynamic descriptions which clear and reset a Graph when these variables are changed, thus, a Graph can be dynamically rescaled after it is initialized. An application program can also arrange to autoscale Graphs by examining the data to be plotted and setting the variables appropriately.

Logarithmic GraphAxes

The SL logarithmic GraphAxis uses log 10. Certain constraints for Renaming Variables are used with logarithmic Graphs. Some of these constraints are based on the nature of logarithms: · The minimum value for a logarithmic GraphAxis must never be 0, and must always be a power of 10 (e.g., 1, 10, 100, 1000, and so on); The minor tick spacing for a logarithmic GraphAxis must be equivalent to the minimum value for that GraphAxis; The major tick spacing must always be -10 (to notify SL-GMS that the GraphAxis is logarithmic).

· ·

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

Renaming GraphTrace variables

Configuring the GraphTrace entails renaming the variables that "drive" the GraphTrace. These variables correspond to the horizontal (x) and vertical (y) values of the Points to be plotted. A pair of variables exists for each trace which appears in a Graph. This is not true of trend Graphs, where only the vertical (y) position is set, and for bar Graphs, where a variable for each bar must be renamed. In addition, the color and style of the Polylines or Markers which make up the GraphTrace can be changed. Sometimes it is desirable to display an array of Point values in a single update pass. Graphs have array variables for this purpose. The arrays are filled with the x and y values of the Points to be plotted, either by an application or by using a ".dat" file. The Graphs are then automatically updated to display a trace containing the specified Points. The application program must call gmsVarChanged( ) on both the x and y values.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-6

Graphs

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

Multi-color GraphTraces

Usually a GraphTrace is drawn in a single color. However, it is also possible to display a Polyline trace made up of different colored line segments. Multi-color GraphTraces for each update pass are created by placing an ecolor 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 template 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 negative 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 indices (integers). Each array element corresponds to the color of a line segment. The length of the array should be num_points -1. 3. The trace#_x_array and trace#_y_array variables are renamed to arrays of the x and y values to be plotted. More information about GraphTrace objects is provided in GraphAxis objects on page 4-16.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-7

Graphs

Multi-styled GraphTraces

Usually a GraphTrace is drawn in a single line style. However, it is also possible to display a Polyline trace made up of different line styles. Multi-styled GraphTraces for each update pass are created by placing an estyle action, which references an array of line style numbers, into the dynamic 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 bit set. 2. The trace#_style_array variable is renamed to an array of line styles (integers). Each array element corresponds to the line style of a line segment. The length of the array should be num_points -1. 3. The trace#_x_array and trace#_y_array variables are renamed to arrays of the x and y values to be plotted. For example, a multi-colored, 1 multi-styled trace with 11 points would have the numpoints (trace#_length) variable set to -11-32768, while a single-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 GraphAxis objects on page 4-16.

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-8

Graphs

Graph variables

A complete list of the variable names used in SL Standard Graphs is provided in the chapter The SL-GMS Graph Library of the SL-GMS Quick Reference.

Renamed Graph variables: an example

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

backgr_color :: 8 num_points :: 12 reset :: (x==13) trace_color :: 7 trace_x_array :: trace_x_value :: x trace_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 :: .5 y_tickminor :: .25

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-9

Graphs

Figure 4-3: Graph with variables renamed (after Previewing) Any variable can be used without renaming it, however, all Instances of Graphs which contain the same variable and have not been renamed are affected when that variable's value changes. To animate a Model containing an Instance of this Graph with the variables renamed as shown in the example above, a data file can be created containing the following information. Alternatively, this information can be entered interactively while using the Edit Data File option of the Dynamics Pull-Down Menu in SL-GMSDraw.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-10

Graphs

EXAMPLE Sample data for Previewing 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

The system is updated each time a blank line is encountered in the data. Each time the variable x changes, it triggers the plotting of the next Point in the GraphTrace. The value of y varies according to the sine of x/4, displaying a portion of a sine curve. To rescale a GraphAxis, the minimum and maximum values are changed for the axis the user wishes to rescale. The dynamic descriptions on the GraphAxis and GraphTrace in the SL Graph Library cause both the axis and the traces to be redrawn according to the new scaling. Any variables which apply to the Graph must be initialized before the Graph is updated for the first time. In this example, x is set to 0 before the first blank line. If a variable is not set to a particular value, it will contain some random value and a random Point may be plotted on the Graph.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-11

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).

backgr_color :: 8 num_points :: 12 trace_color :: 7 trace_x_array :: trace_y_array :: trace_y_value :: sin(x / 4) x_max_value :: 0. x_min_value :: 10. x_shift_val :: 1. x_start :: 0. x_tickmajor :: 2. x_tickminor :: 1. y_max_value :: 2. y_min_value :: -1. y_tickmajor :: .5 y_tickminor :: .25

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-12

Graphs

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

The direction of the shift in trend Graphs depends upon two elements: the values of the limits on the horizontal (x) axis, and the sign of the value of x_shift_val. Each time a new Point is plotted, the x_shift_val is added to the 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 axis began at 10. on the left, and ran to 0 on the right, thus, the plotted line shifted toward the left, as the x values increased toward 10. If the axis limits were from 0 to 10., the x_shift_val must be negative to cause the plotted trace to shift to the left. In general, if the value of x_start is greater than the value of x_max_value, the x_shift_val must be negative.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-13

Graphs

Designing new Graphs

SL-GMS supplies a variety of two-dimensional Graph templates. These templates are Models that are copied and used as Instances wherever Graphs are needed, however, the Graphs provided may not be sufficient for every user's purposes. This section explains how custom Graphs are designed.

The Graph template

The easiest method of creating a custom Graph is to create a new Graph template (".g" file). A Graph template is an SL-GMS Model which completely specifies the appearance and dynamic behavior for a single Graph type. The template is created using a text editor and the SL Graphical Modeling Language (SL-GML).2 The simplest way to design a new Graph template is to begin with a copy of an existing Graph template. Graph templates use two special objects that are applicable to Graphs only. The GraphTrace object corresponds to a plotted line, or trace, in a dynamically changing Graph where the oldest Point may disappear when a new Point is plotted. GraphTraces also include attributes appropriate for displaying plot lines. The second object, the GraphAxis, describes the parts which comprise an axis. A GraphAxis object includes templates for the line that makes up the axis and for tick marks and tick mark labels, and a range for the values that will be plotted against this axis. SL-GMS uses this range, or valuelimits, to label the tick marks on the axis appropriately. GraphTrace and GraphAxis objects are combined into the Graph template Model. Once a Graph template Model is designed, it can be used in many applications, or serve as an example for different Graph templates. Some SL-GML commands are associated only with building Graph templates, and others are associated with special dynamic actions used in the dynamic descriptions for GraphAxis objects and GraphTrace objects. Once the Graph template is constructed, it may be instanced in other Models, connected to process variables, and animated. The SL-GMSDraw interface is the easiest way to position Instances of Graph SubModels and to rename the variables associated with them. The sections Using Graphs

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-14

Graphs

on page 4-1 and Renaming the GraphAxis variables on page 4-4 provide additional 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 dummy objects) for constructing the Graph's axes, tick marks, and GraphTrace objects. These parts are copied when used in a GraphTrace or GraphAxis object; the template objects are not themselves visible in the SubModel. The GraphAxis and GraphTrace objects are created by SL-GML commands. The graphaxis and graphtrace commands use the template parts that were defined in the local SubModel. Other SL-GMS objects may also be added to the Graph template at this point. At a minimum, a dynamic description defines which variables are used to plot the Points in the GraphTrace. A dynamic description must exist for each GraphTrace in the Graph template. Usually, other parts of a Graph Model may be associated with formal variables, such as the value limits on a GraphAxis, or other SL-GMS objects that are part of the Graph. These formal variables are renamed when the Graph Model is instanced and allow the creation of Graphs with flexible axis ranges. On-line examples of Graph template Models are provided in the GRAPHS subdirectory. (GRAPHS is a subdirectory of the demo/graph directory.) Copies of these templates can be used as the starting Point for designing new Graph template Models. The user should choose the style of Graph template closest to that of the desired Graph.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-15

Graphs

GraphAxis objects

The GraphAxis object includes those parts that would be expected of a Graph's axis: a line, divided by tick marks and appropriate labels along the axis. A GraphAxis consists of a Polyline template, several template objects used for the tick division markers, and labels. An unlimited number of GraphAxis 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 command tells the SL-GML interpreter to create a GraphAxis object. axisline is the name of a template object that establishes the attributes used in the GraphAxis object. Two types of axis divisions, or tick marks, exist: major and minor. Major tick marks are labeled automatically when the Graph is displayed, using the ticklabel object as a template. Minor tick marks are displayed without labels. 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 the axisline at right angles and extend below or to the left a short distance. No constraints 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 marks appear in the same relative position when the template is copied along the axis. Tick marks should not extend above or to the right of the axes (within the coordlimits area); this is the display area used for the GraphTraces, and tick marks in the region may be erased or destroyed as the GraphTraces are updated. The ticklabel is the name of a text object that is copied and placed to identify each major tick mark. The ticklabel may be any object containing text. When the ticklabel template object is created, it should be positioned relative to the line used as the major tick mark template. The GraphAxis template objects (majortick, minortick, and ticklabel) specify the location and appearance of one or more objects relative to the Graph axis. For example, the object majortick specifies the location (relative to the axisline) and appearance (line style, line width, and line color) of all

Version 6.2a- 26 May 2006

SL-GMS Reference 4-16

Graphs

major tick marks on the axis. When SL-GMS constructs the Graph axis, the location of each major tick mark is computed and copies of majortick are made at the appropriate locations. SL-GMS also computes the values for the major tick labels, using the values given for major tick spacing and valuelimits. The format used in the tick label is based upon a formatting string that is inserted into the tick label template. For example, if the tick label is to be a real value with a minimum field width of four digits (including a decimal point), and two places to the right of the decimal point, it will contain the formatting string "%4.2f". The table of formatting codes is provided in the section Formatting strings of the SL-GMS Quick Reference. The following example shows the SL-GML commands required to produce a white horizontal axis. The axis has black major tick marks two units long below the axis, white minor tick marks one unit long which lie below the axis, and white raster text labels positioned below each major tick mark.

Portion of Graph template for axis template objects

temp: model ecolor 7 // black line estyle 1 // solid line ewidth 2.0// thick line xline: line 0 0 1 1// axis line template xmajor: line 0 -2 0 0// major tick template ewidth 1.0// thin line xminor: line 0 -1 0 0// minor tick template tcolor 7 // white text font 5 // text font 5 prec 0 // raster text align 2 1// center aligned text xlabel: text "%g" 0 -3// general-purpose fmt endmodel // Create the GraphAxis xaxis: graphaxis temp.xline temp.xmajor temp.xminor\ temp.xlabel

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-17

Graphs

Grid GraphAxes

The GraphAxis object is also used to construct a background grid for Graphs. The grid is constructed by creating a GraphAxis object with only a majortick 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 for this GraphAxis depend upon the minimum and maximum valuelimits of the x 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 designer to completely specify the format which is to appear as labels on major tick marks. The template designer simply places a format specification into the Text template object for the GraphAxis. The template designer then specifies a minimum and maximum range. The values for the minimum and maximum ranges take two forms -- one for date and one for time.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-18

Graphs

The date format requires integer numbers for values. Values are interpreted 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

EXAMPLE

The 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 limit on date-labeled GraphAxes, however, the upper range for dates should extend to 9999 (safely into the future). Dates with two-digit years with yy greater than 50 imply 19yy, while dates with yy less than or equal to 50 imply 20yy. The date calculation handles most vagaries of the Julian calendar correctly -- skipping leap years every 400 years -- however, the missing 12 days in September 1752 cause a problem and throw off the date GraphAxes day of week calculation into centuries prior to 1752. The time format requires real numbers for values. Values are interpreted as two digits of hour (hh), two digits for minutes (mm), two digits for seconds (ss), and fractions of a second (ff) after the decimal point: hhmmss.ff

EXAMPLE

Noon 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 can be included. Since base 60 is used for minutes and hours, values for seconds and minutes 60 or greater are modulo 60, that is, 60 becomes 0, 61

Version 6.2a- 26 May 2006

SL-GMS Reference 4-19

Graphs

becomes 1, 62 becomes 2, and so on. Similarly, values for hours greater than 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 also be a real number. Ten different types of GraphAxes exist: one numeric type and nine date/time types. Each type specifies the spacing that is to be used when the GraphAxis is labeled. The spacing for numeric GraphAxes is real number spacing. The spacing on a date GraphAxis is always integer and is measured in days, months, four quarters, and so on (the complete list is presented below). The spacing on time GraphAxes is always integer, and is measured in seconds. The base unit of spacing for a date GraphAxis is days, however, it is possible to use two different day bases: a seven-day week and a five-day (Monday 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, whichever corresponds to the data used. The ~numeric GraphAxes type is the default, and is used for labeling GraphAxes unless one of the other nine formats is specified. Formats are specified by using a type string to begin the format string in the Text label template object. The type strings are: ~numeric ~daily ~monthly ~quarterly ~yearly ~workdaily ~wdmonthly ~wdquarterly The default type, real number spacing Day labels, seven-day week spacing Month labels, seven-day week spacing Four quarters in a year, seven-day week spacing Year labels, seven-day week spacing Day labels, work-week (five days) spacing Month labels, work-week spacing Quarter labels, work-week spacing

Version 6.2a- 26 May 2006

SL-GMS Reference 4-20

Graphs

~wdyearly ~time Year labels, work -weeks spacing Time, seconds spacing

The type strings are followed by format description strings. By concatenating an integer to these format description strings, the number of characters displayed can be controlled. For example, using the string ~dayname3 limits the display of day names to three characters (Mon, Tue, and so on). The format description strings are: ~daynumber ~dayname Day of the month 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 ~yearnumber2 ~hour ~12hour ~24hour ~minute ~second ~realsecond ~ampm ~AMPM The year The last two digits of the year Hour part of the time (12 hour clock) Hour part of the time (12 hour clock) Hour part of the time (24 hour clock) Minute part of the time Second part of time Seconds with fractional part (to two decimal places) am/pm notation (lower case) AM/PM notation (upper case)

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

Version 6.2a- 26 May 2006

SL-GMS Reference 4-21

Graphs

EXAMPLE

To display hours, minutes, and seconds, separated by colons, with an AM/PM notation on the following line, the string: "~time ~hour:~minute:~second\n~AMPM" produces a tick label that looks like: 3:15:23 PM for three fifteen in the afternoon. The colons appear in the output between the formatted hour, minute, and seconds. The demo/graphs subdirectory contains two examples of date/time GraphAxes. The "xstockvol.m1" Model has an x GraphAxis labeled by workdays and months. (To produce dual labels, two overlapping GraphAxes are used.) The template for this Graph is named "stock2vol1.g" and is in the GRAPHS subdirectory. The Text template objects used to produce this x GraphAxis are shown below: x_axis_label_day: text "~workdaily ~daynumber" 0 -2.0 x_axis_label_mon: text "~wdmonthly ~monthname3" 0 -3.5 These template objects are included in the command that creates the GraphAxes: // X Date Axis: using "weekdaily" and "wdmonthly" axes x1_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.5 x1_axis majorspacing 7.0 x1_axis minorspacing 1.0 x1_axis dynprop\ (date_min (= *\ (valuelimits date_min -(date_total_days - 1))\ (majorspacing date_space_major)\ ))

Version 6.2a- 26 May 2006

SL-GMS Reference 4-22

Graphs

// Month Axis x2_axis: graphaxis temp.x_axis_line\ temp.x_axis_minortick\ nil\ temp.x_axis_label_mon x2_axis coordlimits 0. -0.5 80. -0.5 x2_axis majorspacing 1.0 x2_axis dynprop\ (date_min (= *\ (valuelimits date_min -(date_total_days - 1))\ )) Three variables to be renamed control the minimum, maximum, and label spacing on this Graph. The date_space_major variable is renamed as the constant 7, which places date labels every seven days. The date_min variable sets the beginning date for the xstockvol.m1 example. date_min has been renamed to the constant 880104, corresponding to the date of the beginning data in the data file. The maximum is defined by renaming date_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 is treated as a delta value; it is added to the minimum value to produce the maximum valuelimit. In the example, the maximum valuelimit will be date_min + 364. In other words, a negative maximum valuelimit works as a range. The values used for plotting a GraphTrace against a date/time GraphAxis must also be modified. Just as plotting a GraphTrace against a logarithmic GraphAxis requires using the log( ) function as an argument to the plotdata action, a function is required to convert time or date values into the scaled values used by the date/time GraphAxes. SL-GMS provides the following conversion functions for GraphTraces and GraphAxes displaying date and time values.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-23

Graphs

Date and time conversion functions

gms_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 the section Date and time functions recognized in DynProps of the SL-GMS Quick Reference. Use of specific conversion functions is demonstrated in the next example.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-24

Graphs

EXAMPLE

In a GraphTrace plotted against a GraphAxis in the x dimension, a conversion function is used to convert the first argument to the plotdata action. The following SL-GML commands are taken from the stock2vol1.g template (located in the demo/graphs/GRAPHS subdirectory) and demonstrate 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 be called 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)\ ))

Version 6.2a- 26 May 2006

SL-GMS Reference 4-25

Graphs

Non-Graphical components of GraphAxis objects

Associated with each GraphAxis object are several values which control the way in which the axis is drawn. One set of values determines the range for the axis; a second set establishes the coordinate space in which the axis will be drawn; another value sets the spacing between major tick marks; and a final value sets the spacing between the minor tick marks. name name name name valuelimits x_min_value x_max_value coordlimits xmin ymin xmax ymax majorspacing x_tickmajor minorspacing x_tickminor

The name field is the name of a GraphTrace object that was created with the graphtrace command. The valuelimits data field specifies the data values at the endpoints of the axis. Labels will be drawn along the axis depending upon these limit values. The valuelimits will correspond to the horizontal or vertical valuelimits for the GraphTraces plotted against this GraphAxis. The coordlimits set the endpoints of the axisline. The template axisline is only copied, and the points used when making the template axisline do not affect the positioning of the GraphAxis. Only the attributes (color, style, width) of the axisline template are used in the GraphAxis. Because plotting and clearing GraphTraces may affect the GraphAxis, it is good practice to offset the GraphAxis slightly (.5) from the coordlimit area used by the GraphTraces. For example, part of a thick GraphAxis line will be erased the first time a plotclear action, associated with a GraphTrace dynamic description, occurs. The majorspacing value specifies the distance between the major tick marks drawn along the axis. The units used correspond to the data values used 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 major and minor tick mark spacing should evenly divide the range set by the valuelimits.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-26

Graphs

EXAMPLE

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

In the example above, one major tick mark was drawn every 25.0 units along the axis, with one minor tick mark every 5.0 units along the axis. A label 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 axis rescaling by attaching a DynProp to the Graph Axis, which changes the minimum and maximum values, along with the tickspacing values. For example, a GraphAxis named xaxis might have the following dynamic description associated with it: xaxis dynprop\ (x_min_value (= * \ (valuelimits x_min_value x_max_value)\ (majorspacing x_tickmajor)\ (minorspacing x_tickminor))) Values assigned for the dummy variables (either through the Object Renamed Variables option of the Dynamics Pull-Down Menu in SL-GMSDraw or values assigned at run time by the application program) to the values listed below result in the following axis: x_max_value x_tickmajor x_tickminor x_min_value :: :: :: :: 250. 50. 25. 0.

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

Version 6.2a- 26 May 2006 SL-GMS Reference 4-27

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 an SL-GMS Polyline, Marker, or both. An example (template) Polyline and/or Marker are used during the creation of a GraphTrace object. An unlimited number 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 objects are copied when the template objects are used. The template objects themselves are never displayed because they are parts in a SubModel that is not instanced. (SubModels are never displayed unless the SubModel is referred 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 names work 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 this GraphTrace object. As a GraphTrace object is updated, the plotted Points are added to the object. Only maxtracelength number of Points is kept, and, when a Point is added when there are already maxtracelength number of Points, the oldest plotted Point is discarded and that part of the trace is erased. The traceline is the name of a Polyline that has the attributes desired in the GraphTrace object. The tracemarker is a Marker that has the attributes desired in the GraphTrace object. If a GraphTrace without a Polyline is needed, rather than using the traceline object, the keyword nil is used in place of the name of a Polyline. Or the tracemarker name can be nil and only a Polyline will mark the plotted Points. The same traceline or 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-28

Graphs

These objects are used as templates only, and are not "consumed" when the GraphTrace is built. The following example shows the SL-GML commands required to draw a solid, single-width, green trace with blue markers. Comments to the SL-GML commands follow the double slashes (//).

EXAMPLE

// Set up a local SubModel with trace // template objects. graph_ex: model temp: model ecolor 2 // green line estyle 1 // solid line style ewidth 1.0 // normal line width tr_line: line 0 0 1 1// trace line template // with dummy end points mcolor 4 // blue marker color mstyle 3 // asterisk marker style msize 1.0 // normal-size markers tr_marker: mark 0 0// trace marker template // with dummy point endm // end local submodel // Create a GraphTrace with a history of 10 points trace1: graphtrace 10 temp.tr_line temp.tr_marker // Create a second GraphTrace with red markers only temp.tr_marker mcolor 1 trace2: graphtrace 20 nil temp.tr_marker // GraphTrace using different colors temp.tr_line ecolor 3// yellow trace line temp.tr_marker mcolor 5// magenta trace markers trace3: graphtrace 6 temp.tr_line temp.tr_marker // GraphTrace using dashed line and no markers temp.tr_line estyle 2// dashed line trace4: graphtrace 15 temp.tr_line nil Later, the graphtrace command and the creation of the template objects will be shown in the context of a Graph template.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-29

Graphs

Non-Graphical components of GraphTraces

Associated with each GraphTrace object are several values which control the way in which data are plotted. One set of values determines the range of data that will be accepted, and another establishes the limits within the Graph template Model space within which the data will be plotted. The following SL-GML example shows the commands used to initialize these fields:

EXAMPLE

name xvaluelimits x_min_value x_max_value name yvaluelimits y_min_value y_max_value name coordlimits xmin ymin xmax ymax The xvaluelimits and yvaluelimits data fields specify the minimum and maximum x and y data values which are plotted on the Graph. Data values which fall outside these limits are constrained so that they are plotted within the valuelimits for this GraphTrace. For example, if the maximum x value is 100, an x value greater than 100 is treated as if it were 100. These value limits normally correspond to the limits defined for the GraphAxis objects. The coordlimits (coordinate limits) data field specifies the minimum and maximum x and y SL-GMS World Coordinates for the GraphTrace. (The SL-GMS coordinate systems are explained in the section Coordinate systems on page 8-1.) These values establish a rectangular area that all plotted Points will appear within, and are used to map the data values into SL-GMS World Coordinates.

EXAMPLE

trace1 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 Graph Point (0., 0.) and the data Point (125., 500.) would be plotted at Graph Point (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 be utilized. The Graph template can be reduced in size by scaling when it is

Version 6.2a- 26 May 2006

SL-GMS Reference 4-30

Graphs

positioned by instancing it within another Model. Even though the Graph template has been scaled and positioned within another Model, the coordinates used within the Graph Model are the same as when the Graph was created. Thus, the Graph template designer is not concerned with the eventual position of a Graph in a Model when choosing the coordlimits. The coordlimits are picked while creating the Graph template, and should correspond to the appearance and aspect that the final Graph will have, not its eventual position in other Models or screens. It should be noted that scaling of Graph template Models adds overhead that is better avoided. Each Point in a scaled Graph template must be transformed (which involves floating point arithmetic), so it is best to design Graph templates with the coordlimits established corresponding to the eventual size of the instanced Graph. For example, if the user plans to fit four Graphs on a screen, each Graph template should fit in one quarter of the screen (leaving room for the labels and tick marks) for best system performance. The coordlimits are always set after the GraphTrace object is created, and remain the same within the Graph template Model. The valuelimits for a GraphTrace can be adjusted through the use of dynamic descriptions and renamed variables. The valuelimits establish a range of x data values and 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 the axes. To create truly flexible Graph templates, it is now necessary to be able to adjust 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 renamed when an Instance of the Graph is made. The actions affecting GraphTrace objects are described next.

Creating GraphTrace dynamics

A single DynProp must be specified for each GraphTrace, in order to associate actual data variables with the GraphTrace. Usually, the x and y data values for a plotted Point will be specified by different variables. In order to plot a single Graph Point, the following dynamic description could be used: trace1 dynprop \ (trace1_x_value (= *\

Version 6.2a- 26 May 2006

SL-GMS Reference 4-31

Graphs

(plotdata trace1_x_value trace1_y_value))) The plotdata action keyword instructs the GraphTrace object to plot a new data Point (with x and y values specified by the data variables trace1_x_value and trace1_y_value) whenever either of the variables trace1_x_value or trace1_y_value changes. The application program is responsible for ensuring that both variable values are correct before updating the GraphTrace. Updating the GraphTrace when only one variable value has been received causes the GraphTrace to use the old value of the other variable -- which almost certainly will cause undesired results. The gmsVarChanged( ) function should be called on both GraphTrace variables at the same time. In addition to plotdata, there are seven other actions that apply to GraphTrace objects. The xvaluelimits and yvaluelimits actions can be associated with a GraphTrace so that these data ranges can be set to constant values after the Graph Model has been instanced.

EXAMPLE

The following dynamic description associates the values x_min_value and x_max_value to the range for xvaluelimits, and y_min_value and y_max_value to the range for yvaluelimits. The following dynprop replaces the dynamic description shown earlier for trace1.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-32

Graphs

Dynamics used for a single incrementing GraphTrace

trace1 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 dummy variables must be renamed as constants. (Renaming variables can be done from a SL-GMS drawing editor; the SL-GML syntax is shown here as an example.)

EXAMPLE

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

These valuelimits would be appropriate when used with GraphAxis objects having 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 value of these variables when the x_min_value variable is changed will establish the valuelimits used with this GraphTrace. These valuelimits can be modified by changing the values of the associated variables. Other aspects of GraphTrace objects can be changed dynamically. The tracelength action can be used to set the number of Points kept in the

Version 6.2a- 26 May 2006

SL-GMS Reference 4-33

Graphs

GraphTrace. The plotreset action removes all of the Points kept in the GraphTrace object. The plotclear action erases the rectangular region described by the coordlimits. There are two plot shift actions. The plot shift actions are used in trend Graphs to shift each Point in the GraphTrace over when a new Point is added. If there are already tracelength number of Points in the GraphTrace, the oldest Point is discarded. The GraphTrace is shifted in the horizontal (x) direction by plotshiftx, and in the vertical (y) direction by plotshifty. The value that follows these actions determines which direction and the amount the Points will be shifted. Essentially, the value following the action is added to either the x values (in plotshiftx) or the y values (in plotshifty) in all the Point pairs, then a new Point is plotted. This has the desired effect of shifting the GraphTrace. The following dynprop defines actions appropriate for a trend Graph.

Dynamics for single trend-style GraphTrace

trace1 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 (= *\ (ecolor trace1_color)\ )) In the above example, a plotclear 4 action was used to erase all the Points before the plotshiftx action shifted the Points.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-34

Graphs

When two GraphTraces are in a Graph template Model, the second GraphTrace object's dynamic description does not have a plotclear action. The following dynamic descriptions are for two 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 (= *\ (ecolor trace1_color)\ )) trace2 dynprop\ (x_min_value (= *\ (xvaluelimits x_min_value x_max_value)\ (yvaluelimits y_min_value y_max_value)\ (tracelength trace2_length)\ (plotreset)\// No plotclear here ))\ (trace2_x_value (= *\ (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.

Version 6.2a- 26 May 2006

SL-GMS Reference 4-35

Graphs

(ecolor trace2_color)\ )) The next set of dynamic descriptions is appropriate for a pair of GraphTrace objects that will be loaded with an array of data. In array-load GraphTrace objects, all the Points are replaced each time the data are updated.

Two GraphTraces loaded with arrays

trace1 dynprop\ (x_min_value (= *\ (xvaluelimits x_min_value x_max_value)\ (yvaluelimits y_min_value y_max_value)\ (tracelength trace1_length)\ (plotreset)\ (plotclear)\ ))\ (trace1_x_value (= *\ (plotreset)\// Discard old points (plotclear)\// Clear coordlimit area (plotdata trace1_x_value trace1_y_value)\ ))\ (trace1_color (= *\ (ecolor line_color1)\ )) trace2 dynprop\ (x_min_value (= *\ (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)\ ))\

Version 6.2a- 26 May 2006

SL-GMS Reference 4-36

Graphs

(trace2_color (= *\ (ecolor trace2_color)\ ))

Graph template structure

The following example shows the structure of a general Graph template. A discussion about each component follows. // Define the Graph type graphtype: model // Define local SubModel for templates templates: model // Define templates for axes, labels, traces xaxisline:line ... xmajortick:line ... xminortick:line ... xticklabel:text ... yaxisline:line ... ymajortick:line ... yminortick:line ... yticklabel:text ... traceline:line ... tracemarker:mark ... endm // define Graph components header: text ... xlabel: text ... ylabel: text ... // Create two GraphAxes xaxis: graphaxis ... yaxis: graphaxis ... // Create the GraphTraces trace1: graphtrace ... trace2: graphtrace ... // Initialize GraphAxis Non-Graphic components xaxis valuelimits ...

Version 6.2a- 26 May 2006

SL-GMS Reference 4-37

Graphs

xaxis coordlimits ... xaxis majorspacing ... xaxis minorspacing ... yaxis valuelimits ... yaxis coordlimits ... yaxis majorspacing ... yaxis minorspacing ... *** continued on next page *** // Initialize GraphTrace Non-Graphic components trace1 xvaluelimits ... trace1 yvaluelimits ... trace1 coordlimits ... trace2 xvaluelimits ... trace2 yvaluelimits ... trace2 coordlimits ... // Specify GraphAxis dynamics xaxis dynprop (x_min_value (= *\ (valuelimits x_min_value x_max_value)\ (majorspacing x_tickmajor)\ (minorspacing x_tickminor))) yaxis dynprop (y_min_value (= *\ (valuelimits y_min_value y_max_value)\ (majorspacing y_tickmajor)\ (minorspacing y_tickminor))) // Specify GraphTrace dynamics trace1 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 template is required for each type of Graph (xy plot, trend, scatter plot) used by the application. The SubModel named templates includes the definition of the GraphAxis and GraphTrace template objects. These objects are used to provide SL-GMS with descriptions of the appearance and relative location of vari-

Version 6.2a- 26 May 2006

SL-GMS Reference 4-38

Graphs

ous Graph components. Because the template objects are defined in a local SubModel, they are not drawn when the Graph is displayed. The components of the Graph are defined (in the graphtype Model), initialized, and linked to process variables. Any number of GraphTrace objects, GraphAxis objects, Graph labels, and other SL-GMS objects may be included in the Graph template. The DynProp which accompanies each GraphTrace object makes the association to the process variables. Optional dynamics may be specified for GraphAxis objects (to support rescaling, clutter control, and so on). Other objects can be added to the Graph templates, such as percent-filled Rectangles, and animated using dynamic descriptions. The variables defined in the Graph template's dynamic descriptions are formal (or dummy) variable names which may be replaced with actual variable names when the Graph type is instanced. The Object Renamed Variables option of SL-GMSDraw's Dynamics Pull-Down Menu is used to rename formal variables in Instances of Graph Models.

Example Graph template Model

Graph: model // =============================================== // Define templates for Graph components // =============================================== temp: model // templates for x, y axes ecolor 7 estyle 1 ewidth 2.0 xaline: line 0 0 1 0 yaline: line 0 0 0 1 // tick marks relative to (0, 0) xtmajor: line 0 -2 0 0 ytmajor: line -2 0 0 0 ewidth 1.0 xtminor: line 0 -1 0 0 ytminor: line -1 0 0 0 // axis labels tcolor 7

Version 6.2a- 26 May 2006

SL-GMS Reference 4-39

Graphs

font 5 prec 0 path 1 height 2.0 size 0 0 align 2 1 xtlabel: text "%g" 0 -3 align 3 3 ytlabel: text "%g" -3 0 // template for trace lines estyle 1 ewidth 1.0 ecolor 1 traceline: line 0 0 1 1 // template for trace markers mstyle 3 msize 2.0 mcolor 1 tracemark: mark 0 0 endm // end template SubModel // Define Graph axes xaxis: graphaxis temp.xaline temp.xtmajor\ temp.xtminor temp.xtlabel xaxis coordlimits 0.0 -.5 30.0 -.5 xaxis 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.ytlabel yaxis coordlimits -.5 0.0 -.5 22.0 yaxis dynprop\ (y_min_value (= * \ (valuelimits y_min_value y_max_value)\ (majorspacing y_tickmajor)\

Version 6.2a- 26 May 2006

SL-GMS Reference 4-40

Graphs

(minorspacing y_tickminor)\ )) // Define trace with Lines trace1: graphtrace 25 temp.traceline nil trace1 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 (= *\ (ecolor trace1_color)\ )) // Define trace with markers trace2: graphtrace 25 nil temp.tracemark trace2 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)\ ))\ (trace2_x_value (= *\ (plotdata trace2_x_value trace2_y_value)\ ))\ (trace2_mcolor (= *\ (mcolor trace2_mcolor) \ )) endm

Version 6.2a- 26 May 2006

SL-GMS Reference 4-41

5

Introduction

GISMOs

Objects with input dynamics and optional display dynamics are called GISMOs. SL-GMS GISMOs (Graphical Interactive Screen Management Objects) provide a means of directly manipulating application data, displaying data, and defining other aspects of interactive behavior. GISMOs are used 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 function key; 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 mouse button. To use the middle mouse button to activate a GISMO, the Workstation option, G_WS_NOPASTE, must be set in gmsWinFlags( ).2 In addition to specifying a list of actions to be performed whenever an input event occurs (input dynamics), the attributes of the elements that comprise a GISMO are also able to change in response to changes in one or more application variables (output dynamics). A large number of ready-to-use, predefined GISMOs are provided in the SL-GMS GISMO Library and described completely in Appendix A. GISMOs may be instanced multiple times on multiple screens. Each time a GISMO is replicated (instanced), the variables associated with it may be changed using the standard RenamedVars functionality. Renaming variables on page 3-55 contains a description of the Rename Vars functionality.

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

Version 6.2a- 26 May 2006

SL-GMS Reference 5-1

GISMOs

GISMO Construction

GISMO DynProps are generally placed on the GISMO Model, 3 although the DynProp may also be placed on any Model part such as a Group or an individual object. The DynProp attached to a GISMO generally consists of two logical parts: 1. input dynamics following the pound-sign (#) which call functions 4 to manipulate SL-GMS internal or application program variable(s) and are performed when the GISMO is selected, and 2. output dynamics which include highlighting action(s) to be performed when the GISMO is selected. Typically these highlighting Actions are driven by the change in the SL-GMS internal or application program variable(s).

GISMO DynProp call function in response to input event * do Action(s) in response to change in value of SL-GMS internal or application program variable(s) set value

SL-GMS internal or application program variable(s) changed value

Figure 5-1: General structure of a GISMO DynProp

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.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-2

GISMOs

The syntax of a GISMO DynProp is:

SL-GMSDraw Syntax # call to input-event function . . . * action <argument> . . .

SL-GML Syntax (#\ (call to input-event function)\ (...)) (*\ (action <argument>)\ (...))

Figure 5-2: Syntax of a typical GISMO DynProp

Often, the input-event function calls used in GISMO DynProps are 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 GISMO Action Functions provide optimized, special-purpose actions for behaviors that are often used. An SL-GMS GISMO Action Function is used exactly the same way as any valid SL-GMS action keyword, such as fcolor, vis, movex, and so on. The GISMO designer can think of the SL-GMS GISMO Action Functions as extensions to actions valid in DynProps. For example, the function gms_hilite_percent1( ) is really an extension to the move Action -- it performs move given a variable and a range. The only difference between the SL-GMS GISMO Action Functions and action keywords is that SL-GMS GISMO Action Functions are function calls. A complete list of the SL-GMS GISMO Action Functions is provided in the section SL-GMS GISMO Action Functions on page A-81.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-3

GISMOs

NOTE: Application programs not using gmsMainInit( ) must have a call to gmsInitGismos( ) in order to have the GISMO Action Functions recognized as action keywords in DynProps. Typically, the input-event functions calls used in GISMO DynProps provide variable 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 are generally functions which describe highlighting behaviors (usually following a 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 to one that is always displayed ("vis" highlighting) or selecting between two different representations of an object ("flip" highlighting). Additional types of highlighting may be defined by the user, but the types provided with the distributed SL-GMS GISMO Library cover most uses. Other highlighting behavior can be supplied either by adding to the set of supporting functions or by defining the highlighting in terms of actions attached to DynProps. For example, the DynProp shown below works by setting and testing the SL-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 locator press and the gms_hilite_color( ) function responds to the value of _ _button_hilite. If _ _button_hilite is set to 1, gms_hilite_color( ) performs fill highlighting with hc. Next, gms_flash( ) resets _ _button_hilite to 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-4

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 into three 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_*( ) functions which provide an extension to standard SL-GMS Actions performed on any object using DynProps. In a formal SL-GMS GISMO, the highlighting must often be controlled by an application variable, in many cases simply a Boolean variable. In addition, it may even be desirable to parameterize the highlighting colors in order to allow global changes. A common DynProp to control such highlighting might look like: variable = 1 fcolor tcolor = 0 fcolor tcolor (highlight) hicolor hicolor (unhighlight) uncolor uncolor

Constructing such descriptions in DynProps is not a complex task, but if many 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 actions with a function that performs the same action. The following equivalent function, provided in SL-GMS and used in a DynProp, provides essentially the same functionality without the overhead on each DynProp: * call gms_hilite_color(&variable, hicolor, uncolor)

Version 6.2a- 26 May 2006

SL-GMS Reference 5-5

GISMOs

In the function, the variable is passed along with the highlight color and the unhighlight color; the object graphics are changed whenever gmsDynUpdate( ) is called. The example above is simple, but many of the most common types of GISMOs require a Group of objects to be operated upon, not just a single object. For example, a CHECK GROUP GISMO is usually constructed as a collection of individual buttons, each being highlighted or unhighlighted according to a Boolean variable contained in an array, where each element corresponds to a member of the Group. The gms_hilite_color( ) function, shown in the above example, is designed so that the object on which the function is being performed (the object which is being DynUpdated) may be either an individual object or a collection 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 element of the array is applied to each member of the Group. The calling syntax for the gms_hilite_*( ) functions is described in the section SL-GMS GISMO Action Functions on page A-81.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-6

GISMOs

Sample construction of a GISMO

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

Figure 5-3: Light switch

Version 6.2a- 26 May 2006

SL-GMS Reference 5-7

GISMOs

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

circle with a black line fcolor of circle = 24

large rectangle ecolor = 7 fcolor = 10

small rectangle ecolor = 7 fcolor = 24

circle with a black line fcolor of circle = 24

Figure 5-4: Background pieces of the light switch

Version 6.2a- 26 May 2006

SL-GMS Reference 5-8

GISMOs

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

Figure 5-5: Assembled background of the light switch

Version 6.2a- 26 May 2006

SL-GMS Reference 5-9

GISMOs

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

small rectangle fcolor 4 ecolor 17

large rectangle fcolor 17 ecolor 7

before

after

Figure 5-6: First part of GISMO

Version 6.2a- 26 May 2006

SL-GMS Reference 5-10

GISMOs

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

line ecolor = 4

line ecolor = 4

Figure 5-7: Two lines added to switch object

The four objects in Figure 5-7: (the large and small rectangle, and the two lines) 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-11

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 Figure 5-8:.

"off_state"

"on_state"

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" object 8 is selected, then the "off_state" object, and the two objects are made into a Group. The following input dynamics are attached to the Group. # call gms_cycle_var(callback, &var) * call gms_hilite_cycle(&var) The above DynProp calls the gms_cycle_var( ) GISMO action function whenever the "off_state"/"on_state" Group is selected. The gms_cycle_var( ) function cycles var based upon the number of parts in the selected 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-12

GISMOs

The gms_hilite_cycle( ) function highlights an object in a Group or part using visibility. The object whose part index is the same as the value of var is made visible. Other objects in the part (which could be a Group) are made invisible. In a Group, the order of the objects is dependent on what order the objects were 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, therefore, it is index 1. The "off_state"/"on_state" Group is centered on top of the small rectangle in the light switch background, as shown in Figure 5-9:.

light switch

background

"off_state" "on_state" Group

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

Version 6.2a- 26 May 2006

SL-GMS Reference 5-13

GISMOs

To see how the light switch GISMO action functions work, place an Instance of the light switch into a Model. Add a filled Circle to the Model. Attach the following dynamics to the filled Circle. var = 1 fcolor 7 = 0 fcolor 3 The above dynamics state "whenever the value of var equals one change the fill color of the filled circle to the color index 7 (black), and when the value of var equals zero, change the fill color of the filled circle to the color index 3 (yellow)". Test the Model by selecting Preview Options on the Dynamics Pull-Down Menu. Select Edit Data File in the Dynamics Pull-Down Menu, and type the following line into the Edit Dynamics Window. var 1 The line shown above sets the initial value of var equal to one. When var is equal 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 set equal 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, the value of var is cycled between the values of one and zero.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-14

GISMOs

Toggle Group

0 1 2

Figure 5-10: Examples of BUTTON GROUP type GISMOs A GISMO Toggle Group is a group of objects cooperating with each other in 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 one time

Any set of objects can be grouped together to create a toggle group with either radio or check behavior. Several GISMO models are provided in the GISMO library to help construct a toggle GISMO group. These "GISMO helpers" are shown below:

Figure 5-11: "GISMO helper" buttons

Version 6.2a- 26 May 2006

SL-GMS Reference 5-15

GISMOs

Each "GISMO helper" button is stripped of its input dynamics (and strictly speaking, by itself is not a GISMO) but can still have renamed variables which control its outward appearance. The radio or check behavior is provided by grouping the "GISMO helper" SubModels together and attaching a DynProp to the Group.

Constructing a "GISMO helper"

For this example the md_button SubModel will be used. The md_button is one of the "GISMO helpers" with the Motif diamond look. The appearance of the md_button SubModel is created with two objects called state_0 and state_1. Each of these objects is a Group that contains a Filled Polygon object and two Polyline objects. The state_0 object controls the appearance of the button when it is unselected. The state_1 object 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, since these variables differentiate the appearance of the different objects. state_0: group fcolor 13 ecolor 0 estyle 0 plate_0: poly 0 2 2 4 4 2 2 0 . filled 1 fcolor 0 ecolor 15 estyle 1 lower_0: line 0 2 2 0 4 2 ecolor 12 upper_0: line 0 2 2 4 4 2 endg

Version 6.2a- 26 May 2006

SL-GMS Reference 5-16

GISMOs

upper_0

lower_0

plate_0

state_0

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 differentiate the appearance of the different objects. The state_1 Group is normally invisible (vis 0). vis 0 state_1: group fcolor 14 ecolor 0 estyle 0 plate_1: poly 2 0 0 2 2 4 4 2 . filled 1 fcolor 0 ecolor 15 estyle 1 upper_1: line 0 2 2 4 4 2 ecolor 12 lower_1: line 0 2 2 0 4 2 endg

Version 6.2a- 26 May 2006

SL-GMS Reference 5-17

GISMOs

upper_1

lower_1

plate_1

state_1

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

* stext button_label "%s" theight text_height

Description 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

Version 6.2a- 26 May 2006

SL-GMS Reference 5-18

GISMOs

A DynProp is put on the Model itself (not any individual part of the Model). DynProp for the md_button Model SL-GMSDraw Syntax

* ewidth edge_width

Description 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

The md_button Model does not contain any input dynamics. The state_1 and the state_0 objects are not grouped together because this Model will be used as a SubModel and will be grouped with other Instances of this SubModel to produce a BUTTON GROUP type GISMO.

RADIO GROUP GISMO

RADIO GROUP GISMOs are created by grouping a set of objects together and attaching the radio behavior to them. The md_button "GISMO helper" will be used for this example. The md_button SubModel is instanced in a Model and the variables are renamed. For this example, three Instances will be placed in the Working View and their variables renamed as follows: RenamedVars for Instance #1 button_label :: "0" edge_width :: 3 text_height :: 2 RenamedVars for Instance #2 button_label :: "1" edge_width :: 3 text_height :: 2 RenamedVars for Instance #3 button_label :: "2" edge_width :: 3 text_height :: 2

Version 6.2a- 26 May 2006

SL-GMS Reference 5-19

GISMOs

BEFORE md_button md_button md_button

AFTER 0 1 2

Figure 5-14: Three Instances before and after renaming variables The three Instances are then grouped together. The order of the grouped objects is important; they should be selected in sequence when grouped (or ordered using the commands in the Order Pull-Down Menu), so that they accurately reflect the value of the array or variable associated with the GISMO. For this example, the Instances will be selected from top to bottom ("0", "1", and "2").

Version 6.2a- 26 May 2006

SL-GMS Reference 5-20

GISMOs

GISMO 0 1 2

arrayvar 0 0 1

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 control GISMO highlighting and application behavior. For an array variable (arrayvar in the example below), the function which highlights the GISMO may 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 an array variable. DynProp for the Group SL-GMSDraw Syntax

# call gms_radio_array(callback, &arrayvar, 0) * call gms_hilite_vis (&arrayvar)

Description when the GISMO is selected call the function gms_radio_array( )

call the function gms_hilite_vis( ) and pass it the address of the variable arrayvar; this will highlight the appropriate part of the GISMO

Version 6.2a- 26 May 2006

SL-GMS Reference 5-21

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). It sets the value of no more than one element of the array to 1 (selected) and sets 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 the md_button SubModel, the state_0 object (unselected) is normally visible and the state_1 object (selected) is normally invisible. The gms_hilite_vis( ) function will change the visibility of each member of a Group containing two objects. The visibility 9 of the first object always starts at 1. The visibility of the second object is set to 1 or 0, depending upon the value of the associated array variable (arrayvar in the example above). In the RADIO GROUP GISMO described above, there are three Instances (members) of the md_button SubModel in the Group and each of these Instances of md_button has two objects; state_0 and state_1. This is why the state_0 and the state_1 objects were not grouped together. If they were grouped together, the gms_hilite_vis() function would not work properly.

9. An object is visible if its visibility is set to 1. It is invisible if its visibility is set to 0.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-22

GISMOs

A RADIO GROUP GISMO can also use an index variable (indexvar in the following example). The value of the index variable determines which object in a GISMO is highlighted (index is 0 relative).

GISMO 0 1 2

indexvar 2

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 an index variable. DynProp for the Group SL-GMSDraw Syntax

# call gms_radio_var(callback, &indexvar, 0) * call gms_hilite_vis_var (&indexvar)

Description when the GISMO is selected call the function gms_radio_var( )

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

The gms_radio_var( ) function associates an index variable (indexvar in the example above) with a set of radio buttons (the Group of three Instances of md_button). The function sets the value of the index variable to the

Version 6.2a- 26 May 2006

SL-GMS Reference 5-23

GISMOs

index of the selected object. The gms_radio_var( ) function is described on pages A-25 and A-95. The gms_hilite_vis_var( ) function highlights by changing the visibility of each member of a Group (each of the three Instances of md_button grouped together) containing two objects (e.g., state_1 and state_0). The visibility of the first object always starts at 1. The visibility of the second object 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 GISMO

CHECK GROUP GISMOs are created by grouping a set of objects together and attaching the check behavior to them. For this example the ms_button SubModel will be used. ms_button is one of the "GISMO helpers". The ms_button SubModel is built and grouped into a set of objects similar to the md_button SubModel (pages 5-16 through 5-20 describe the md_button SubModel and its grouping into a set of objects). A CHECK GROUP GISMO uses an array variable to control GISMO highlighting and application behavior. For an array variable (arrayvar in the example below), the function which highlights the GISMO may be made to affect the attributes of a Group of SL-GMS objects. Unlike a RADIO GROUP GISMO, more than one member of the Group can be highlighted at any one time (i.e., more than one element of arrayvar can be set to 1).

GISMO 0 1 2

arrayvar 1 0 1

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

Version 6.2a- 26 May 2006

SL-GMS Reference 5-24

GISMOs

The DynProp shown below is attached to the Group of three Instances. These input dynamics produce a CHECK GROUP GISMO driven by an array variable. DynProp for the Group SL-GMSDraw Syntax

# call gms_toggle_array(callback ,&arrayvar) * call gms_hilite_vis (&arrayvar)

Description 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

The gms_toggle_array( ) function associates the array variable, arrayvar, with a set of check buttons (the Group of three Instances of ms_button). It sets the value of each element of the array to 1 (selected) or 0 (unselected). The gms_toggle_array( ) function is explained in greater detail on page A-106. The gms_hilite_vis( ) function (refer to page 5-22) performs the same for the CHECK GROUP GISMO as it does for the RADIO GROUP GISMO using an array variable.

BUTTON GROUP type GISMO highlighting

The 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 two groups, state_0 and state_1, with state_0 normally visible and state_1 normally invisible. Therefore, the gms_hilite_vis( ) or gms_hilite_vis_var( ) functions would be used for all of these "GISMO helpers" to provide highlighting. Other types of highlighting can be used with the BUTTON GROUP type GISMOs to correspond with the type of objects being grouped. For example, the radio3 (RADIO GROUP) and toggle3 (CHECK GROUP) GISMOs are each a group of three Filled Text Rectangles that use

Version 6.2a- 26 May 2006

SL-GMS Reference 5-25

GISMOs

"edge" highlighting by calling the gms_hilite_edge( ) function. Page A-25 provides further information about RADIO GROUP GISMOs and their highlighting types. Page A-32 provides further information about CHECK GROUP GISMOs.

Using GISMOs

To use an SL-GMS GISMO, an Instance of the GISMO SubModel is placed in the Working View using SL-GMSDraw and its variables are renamed by selecting the Object Renamed Variables option of the Dynamics Pull-Down Menu. To place an Instance of an SL-GMS GISMO into the Working View using SL-GMSDraw select the Available SubModels option of the Palettes Pull-Down Menu to bring up the Available Submodels window.10 Select the GISMO from the listing in the Available Submodels window and make an Instance of the GISMO SubModel. Appendix A, starting on page A-1, provides information about renaming GISMO variables for each of the different type of GISMOs. Any GISMO in the SL-GMS GISMO Library can be customized by changing its graphical characteristics with SL-GMSDraw. Functional behavior can also be modified by defining user callback functions and calling them directly in the DynProp. Any additional user callback functions must be declared to SL-GMS with the gmsAddUserFctn( ) call. Alternatively, if the range of GISMO behaviors provided via the SL-GMS GISMO Action Functions (listed beginning on page A-81) is not sufficient, a user can provide an enhanced set of functions to perform more specific behavior. These enhanced functions are accessed in the same manner as the other user-defined functions available in SL-GMS. In summary, · using RenamedVars on Instances of GISMOs in the SL-GMS GISMO Library allows for each Instance to have different variables and values control the highlighting and application behavior; altering the DynProps of the GISMOs in the SL-GMS GISMO Library allows for changing the type of GISMO highlighting;

·

10. The SL-GMS®Draw Tutorial provides examples on using SubModels.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-26

GISMOs

· creating user-defined functions (to supplement the SL-GMS GISMO Action Functions) and using them in the DynProps of GISMOs allows for customizations of GISMO behavior.

The GISMO Library

To allow users of SL-GMS to build dynamic graphics screens easily, a large number of ready-to-use, predefined GISMOs are provided in several subdirectories of the demo directory. These GISMOs can be used, unaltered, to control many different kinds of data by selecting the desired GISMO from a list of SubModels. The GISMOs can also be customized. A table detailing the contents of the SL-GMS GISMO Library is provided on the following pages.

Version 6.2a- 26 May 2006

SL-GMS Reference 5-27

GISMOs

The SL-GMS GISMO Library GISMO Category BUTTON Model Names f_call m_call ma_call md_call ms_call Functional Behavior calls an application callback function with no highlighting On-line Examples airports cockpit colordef examples gismos sltrader structdemo tutor3 tutor4 viewtest diverse dynactions examples graphs process states tutor1 colordef states

GISMO CALL

See Page A-4

DATSCREEN f_dscrn m_dscrn md_dscrn ms_dscrn

displays a new screen; activates the screen's .dat file for dynamics displays a popup menu or dialog box

A-7

POPUP

f_popup m_popup ma_popup

A-10

Version 6.2a- 26 May 2006

SL-GMS Reference 5-28

GISMOs

The SL-GMS GISMO Library

(continued)

GISMO Category

GISMO

Model Names f_quit m_quit

Functional Behavior exits application program

On-line Examples ccpdemo1 cockpit diverse dynactions examples fplan gismos gmsdemo gmsrun graphs network process radar sltrader states tutor3 tutor4 viewtest examples gismos process sltrader states tutor1

See Page A-13

BUTTON QUIT (continued)

RETURN

f_return m_return

returns to previous screen

A-15

SCREEN

f_scrn m_scrn md_scrn ms_scrn f_state m_state md_state ms_state

displays a new gismos screen states

A-17

STATE

invoke a State process of a specified State class

A-20

Version 6.2a- 26 May 2006

SL-GMS Reference 5-29

GISMOs

The SL-GMS GISMO Library

(continued)

GISMO Category BUTTON GROUP

GISMO RADIO TOGGLE (button helper)

Model Names m_button ma_down ma_left ma_right ma_up md_button ms_button

Functional Behavior

On-line Examples

See Page 5-16

Grouped in a gismos GISMO GROUP under a DynProp with radio behavior Grouped in a gismos GISMO GROUP under a DynProp with check behavior calls an gismos application callback function with "radio" highlighting (only one GISMO element highlighted at a time) calls an application callback function with "check" highlighting (any GISMO element toggled on or off) gismos

CHECK TOGGLE (button helper)

5-24

RADIO GROUP

radio3

A-25

CHECK GROUP

toggle3

A-32

Version 6.2a- 26 May 2006

SL-GMS Reference 5-30

GISMOs

The SL-GMS GISMO Library

(continued)

GISMO Category SPECIAL PURPOSE

GISMO CYCLE

Model Names cycle1 cycle2

Functional Behavior

On-line Examples

See Page A-37

calls an gismos application callback function with a variable cycled through a set of values calls an colordef application gismos callback function with a variable manipulated through a range of values scroll lines of gismos text; allow gmsrun selection of a single line (m_sboxs) or multiple lines (m_sboxm); optionally call user function(s) upon scrolling and/or selection

FILLPERCENT

f_fill m_fill

A-40

SCROLLBOX m_sboxs (SINGLE and m_sboxm MULTIPLE SELECTION)

A-44

Version 6.2a- 26 May 2006

SL-GMS Reference 5-31

GISMOs

The SL-GMS GISMO Library

(continued)

GISMO Category

GISMO

Model Names f_slide m_slideh m_slidev

Functional Behavior

On-line Examples

See Page A-55

SPECIAL SLIDER PURPOSE (continued)

calls an gismos application radar callback function with a variable manipulated through a range of values calls an application callback function with arrays of fields, type integer, float, or string calls an application callback function with individual fields, type integer, float, or string gismos

TEXTENTRY ARRAY

A-59

TEXTENTRY f_textv VAR m_textv textentry

examples gismos sltrader tutor4

A-67

NON COLORCELL colorcells STANDARD S colarr4

calls an gismos application callback function with a color index variable equal to the color index of the object picked

A-76

Version 6.2a- 26 May 2006

SL-GMS Reference 5-32

6

Introduction

· · · · ·

The Enhanced State Management System

SL-GMS contains a library of new State Classes. These State Classes provide standard ways to manage various aspects of a real-time dynamic graphics 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 Class Library Reference and in the SL-GMS® Enhanced State Management.

Version 6.2a- 26 May 2006

SL-GMS Reference 6-1

7

Introduction

Event Handling

This chapter takes a close look at how Events are processed, both within SL-SMS and outside of it. It describes the functions used to set up Event handlers for input Events and timer Events.

Event Handling in SL-SMS

In SL-SMS, all Events are dispatched automatically to Event-handler methods defined by State classes, so very little programming is required. In situations where some special functionality is desired, State class methods for handling Events may be defined, as described in SL-GMS® State Class Library Reference. Within SL-SMS, Events are dispatched to State class methods, to GISMO action functions, or to user-defined functions. The sequence of Event processing 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 looks in the State Instance's Models to determine if an object has been selected. If the gismoflag is set to G_OFF, the Event is passed to 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 function is called. Native Control Objects are another way into SL-SMS to simplify event handling. Control objects intercept Events directly from Motif and Windows, and translate the Events either into State messages or into variable changes. The SL-GMS® State Class Library Reference provides a discussion of event processing in SL-SMS. More information about GISMO action functions is provided in Appendix A.

Version 6.2a- 26 May 2006

SL-GMS Reference 7-1

Event Handling

Event handling is illustrated in Figure 7-1.

gmsWsAddEvent( ) Event SL-SMS Event Dispatcher

System Event Dispatcher

State methods (Event handlers)

GISMO Processor

Native Control Object

Event

Figure 7-1: Event-handling

Version 6.2a- 26 May 2006

SL-GMS Reference 7-2

Event Handling

Event codes

The following are the Event codes permitted in the second argument of the gmsWsEventFctn( ) function. These codes are defined in the include file "gmscodes.h".

.

gmsWsEventFctn( ) -- Valid Codes for "eventcode" Argument Event Type Locator Events Character Events Window Events Codes G_LOC_PRESS G_LOC_RELEASE G_LOC_MOTION G_KEY_FILTER G_KEY_PRESS G_KEY_RELEASE G_WIN_EXPOSE G_WIN_RESIZE G_WIN_FOCUS_IN G_WIN_FOCUS_OUT G_WIN_ENTER G_WIN_LEAVE G_WIN_MAP G_WIN_UNMAP G_WIN_DESTROY G_MSG_CLIENT G_USER_EVENT Description Locator press Locator release Locator motion any key press any key press any key release Window exposure Window resize Window focus in Window focus out Window enter Window leave Window map Window unmap Window destroy ??? ???

Other Events

Version 6.2a- 26 May 2006

SL-GMS Reference 7-3

Event Handling

Event modifier codes

In addition to the Event codes listed above, SL-GMS provides Event modifier codes. Event modifiers are the buttons or keys held down at the time of an Event. Event modifiers provide additional information about Locator and Keyboard Events. These Event modifier codes are contained in "gmscodes.h". These codes are bitwise AND'd with the Event Codes listed in the table, gmsWsEventFctn( ) -- Valid Codes for "eventcode" Argument. Examples of the use of Event codes are provided in the section Using the event query functions -- examples. Event Modifier Codes Code G_LOC_BUTTON_1 G_LOC_BUTTON_2 G_LOC_BUTTON_3 G_LOC_BUTTON_4 G_LOC_BUTTON_5 G_LOC_BUTTON_LEFT G_LOC_BUTTON_MIDDLE G_LOC_BUTTON_RIGHT G_DOUBLE_CLICK G_SHIFT_KEY G_LOCK_KEY G_CONTROL_KEY G_MOD1_KEY G_MOD2_KEY G_MOD3_KEY G_MOD4_KEY G_MOD5_KEY G_BPAD_BUTTON_0 G_BPAD_BUTTON_1 G_BPAD_BUTTON_2 G_BPAD_BUTTON_3 Description Mouse button 1 Mouse button 2 Mouse button 3 Mouse button 4 Mouse button 5 (syn. for G_LOC_BUTTON_1) (syn. for G_LOC_BUTTON_2) (syn. for G_LOC_BUTTON_3) Mouse button double-click <SHIFT> key <SHIFT LOCK> key <CONTROL> key Workstation-dependent modifier key 1 Workstation-dependent modifier key 2 Workstation-dependent modifier key 3 Workstation-dependent modifier key 4 Workstation-dependent modifier key 5 Bitpad button 1 Bitpad button 2 Bitpad button 3 Bitpad button 4

Version 6.2a- 26 May 2006

SL-GMS Reference 7-4

Event Handling

SL-GMS supports reporting of mouse "double-click" events on both Windows and Unix (X Window System) platforms. The report takes the form of an additional "modifier" flag for G_LOC_PRESS and G_LOC_RELEASE events: 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 the user's current "double click time". Only Windows provides a "double click proximity" filter, so SL-GMS mimics that behavior on X. Windows programs using the traditional win32 API for double-click only receive those events for the left (or "select") button, so SL-GMS avoids that API in order to report double-clicks on any mouse button. (This means that Windows applications which create their own windows for SL-GMS must NOT include the "CS_DBLCLKS" identifier when initializing the style field of the window class structure.) Neither system directly supports any kind of notification that a mouse release event is associated with a double-click; SL-GMS adds the G_DOUBLE_CLICK flag to G_LOC_RELEASE events if the previous G_LOC_PRESS was a double-click and if the release occurs within a radius twice as large as that used to identify the double-click G_LOC_PRESS. Assuming that an application has enabled both G_LOC_PRESS and G_LOC_RELEASE events, it will see the double-click reported as a sequence of four locator events: G_LOC_PRESS G_LOC_RELEASE G_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 via the Control Panel. On X systems, the time limit defaults to 500 milliseconds but can be changed before application startup via the X Resource "multiClickTime" (which many environments use by default but which users can add to their environment using "xrdb -merge".) Finally, note that G_LOC_PRESS and G_LOC_RELEASE events are SL-GMS "highlevel workstation" events and as such do not apply to those events which occur inside NCOs ("native control objects"). Proper double-click handling for those objects is NCO-specific.

Version 6.2a- 26 May 2006

SL-GMS Reference 7-5

Event Handling

State class event-handlers and events

Any State class event-handler functions (except the KeyEvent callbacks which return an idLinkRef -- as shown below) must return int and take a single argument, the Event: int callback (event) id event;

/* an Event object */

Inside the State class Event-handler method, it is often desirable to obtain more information about the Event. If it is a Locator Event, in which View did it occur? If it is a Keyboard Event, which key was pressed? SL-GMS provides Event Query functions for this purpose. Each Event object is a subclass of the G_WsEvent class. The G_WsEvent object contains a pointer to the Workstation on which this Event occurred, its Event code, and a time stamp. Additional information about the Event is contained in each subclass. The actual class of the Event depends upon the type of information required by the callback function. There are four classes of events. · · · · G_LocEvent -- contains information concerning mouse cursor location G_KeyEvent -- contains information concerning single and multiple key presses G_StrEvent -- contains the character string entered and the Text Edit object used to enter the string G_WinEvent -- window extent

A KEY_FILTER callback must return a idLinkRef containing the KeyEvent object. KEY_PRESS and KEY_RELEASE callbacks return an int indicating the key which was pressed or released.

Version 6.2a- 26 May 2006

SL-GMS Reference 7-6

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( ) . These functions are used together inside an Event handler to determine which combination of buttons and keys have been pressed.

Example 1

The user presses the LEFT mouse button, moves the mouse, and releases the LEFT mouse button. In the G_LOC_PRESS Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT 0

In the G_LOC_MOTION Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) 0 G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT Returns

In the G_LOC_RELEASE Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT

Version 6.2a- 26 May 2006

SL-GMS Reference 7-7

Event Handling

Example 2

While holding down the <CONTROL> key, the user presses the LEFT mouse button, moves the mouse, and releases the LEFT mouse button. In the G_LOC_PRESS Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT G_CONTROL_KEY

In the G_LOC_MOTION Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) 0 G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT and G_CONTROL_KEY Returns

In the G_LOC_RELEASE Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT and G_CONTROL_KEY

Version 6.2a- 26 May 2006

SL-GMS Reference 7-8

Event Handling

Example 3

While holding down the <SHIFT> key and the MIDDLE mouse button, the user presses the LEFT mouse button, moves the mouse, and releases the LEFT mouse button. In the G_LOC_PRESS Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE G_LOC_BUTTON_MIDDLE and G_SHIFT_KEY

In the G_LOC_MOTION Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) 0 G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE G_SHIFT_KEY and G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE Returns

In the G_LOC_RELEASE Event-handler: Function gmsQEvTrigger( ) gmsQEvButtons( ) gmsQEvModifiers( ) Returns G_LOC_BUTTON_LEFT G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE G_SHIFT_KEY and G_LOC_BUTTON_LEFT and G_LOC_BUTTON_MIDDLE

Version 6.2a- 26 May 2006

SL-GMS Reference 7-9

Event Handling

Example 4

The user presses the "a" key, then releases it. In the G_KEY_PRESS Event-handler: Function gmsQEvKeysym( ) gmsQEvStringC( ) gmsQEvModifiers( ) 0 G_SUCCESSFUL, buffer[0] = a 0 Returns

In the G_KEY_RELEASE Event-handler: Function gmsQEvKeysym( ) gmsQEvStringC( ) gmsQEvModifiers( ) 0 G_SUCCESSFUL, buffer[0] = a 0 Returns

Example 5

While holding down the <SHIFT> key and the MIDDLE mouse button, the user presses the "A" key then releases the "A" key. In the G_KEY_PRESS Event-handler: Function gmsQEvKeysym( ) gmsQEvStringC( ) gmsQEvModifiers( ) 0 G_SUCCESSFUL,buffer[0] = a G_SHIFT_KEY and G_LOC_BUTTON_MIDDLE Returns

In the G_KEY_RELEASE Event-handler: Function gmsQEvKeysym( ) 0 Returns

Version 6.2a- 26 May 2006

SL-GMS Reference 7-10

Event Handling

Function gmsQEvStringC( ) gmsQEvModifiers( ) Returns G_SUCCESSFUL, buffer[0] = a G_SHIFT_KEY and G_LOC_BUTTON_MIDDLE

Version 6.2a- 26 May 2006

SL-GMS Reference 7-11

Event Handling

Simulating Events

Several functions are available in the SL-GMS API to support user creation, modification, query and addition of SL-GMS events to the "high level workstation" event queue. To create an event, use gmsEvent( ): id gmsEvent (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 into four groups and include:

G_LOC_PRESS/* locator events */ G_LOC_RELEASE G_LOC_MOTION G_KEY_PRESS/* keyboard events */ G_KEY_RELEASE G_WIN_EXPOSE/* window events */ G_WIN_EXPOSE_RECT G_WIN_RESIZE G_WIN_FOCUS_IN G_WIN_FOCUS_OUT G_WIN_ENTER G_WIN_LEAVE G_WIN_MAP G_WIN_UNMAP G_WIN_DESTROY G_MSG_CLIENT/* message events */ G_USER_EVENT

Version 6.2a- 26 May 2006

SL-GMS Reference 7-12

Event Handling

The second argument is an SL-GMS workstation object. The third argument is a pointer to an optional "destroy callback" function for SL-GMS to call when it has finished processing the event. If NULL or if when called the callback returns 0, SL-GMS will deallocate the event. If successful, gmsEvent( ) returns a typed event object; otherwise it returns NULL. When an event is ready to be added to the workstation queue,use

gmsWsAddEvent( ) :

int gmsWsAddEvent (workst, event) id workst; id event; To prepare an event for processing by gmsWsAddEvent( ), type-specific data usually needs to be attached to the event. For instance, locator events need a Point object, keyboard events need a key, window events need an extent, and message events should have data. The API for setting these 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 */ int gmsEvAction (event, action) id event; intaction; /* set data for message events */ int gmsEvData (event, data) id event; longdata; /* set extent for window events */ int gmsEvExtent (event, extent)

Version 6.2a- 26 May 2006

SL-GMS Reference 7-13

Event Handling

id event; idLinkRefext_list; /* set keysym for keyboard events */ int gmsEvKeysym (event, keysym) id event; unsigned longkeysym; /* set modifier keys for keyboard or locator events */ int gmsEvModifiers (event, modifiers) id event; unsigned int modifiers; /* set object for keyboard or locator events */ int gmsEvObject (event, object) id event; id object; /* set point for locator events */ int gmsEvPoint (event, point) id event; id point; /* set "char *" string for keyboard events */ int gmsEvStringC (event, char_str) id event; char*char_str;

/* set "string object" for keyboard events */ int

Version 6.2a- 26 May 2006

SL-GMS Reference 7-14

Event Handling

gmsEvStringSO (event, str_obj) id event; id str_obj; /* set timestamp for any event */ int gmsEvTime (event, sec, usec) id event; unsigned longsec, usec; /* set trigger button for locator events */ int gmsEvTrigger (event, trigger) id event; inttrigger; /* set event type for any event */ int gmsEvType (event, type) id event; inttype; /* set view for keyboard or locator events */ int gmsEvView (event, view) id event; id view; /* set workst for any event */ int gmsEvWorkst (event, workst) id event; id workst; In addition to the foregoing "set" functions, query functions are provided as follows:

Version 6.2a- 26 May 2006

SL-GMS Reference 7-15

Event Handling

/* query action for message events */ int gmsQEvAction (event) id event; /* query buttons for locator events */ int gmsQEvButtons (event) id event; /* query data for message events */ int gmsQEvData (event) id event; /* query extent for window events */ idLinkRef gmsQEvExtent (event) id event; /* query keysym for keyboard events */ unsigned long gmsQEvKeysym (event) id event; /* query modifier keys for keyboard or locator events */ int gmsQEvModifiers (event) id event; /* query object for keyboard or locator events */ id gmsQEvObject (event) id event;

Version 6.2a- 26 May 2006

SL-GMS Reference 7-16

Event Handling

/* query point for locator events */ id gmsQEvPoint (event) id event; /* query "char *" string for keyboard events */ int gmsQEvStringC (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 */ int gmsQEvStringSO (event, buffer) id event; id buffer; /* query timestamp for any event */ int gmsQEvTime (event, sec, usec) id event; unsigned long*sec, *usec; /* query trigger button for locator events */ int gmsQEvTrigger (event) id event; /* query event type for any event */ int gmsQEvType (event) id event;

Version 6.2a- 26 May 2006

SL-GMS Reference 7-17

Event Handling

/* query view for keyboard or locator events */ id gmsQEvView (event) id event; /* query view index for keyboard or locator events */ int gmsQEvViewIndex (event) id event; /* query workst for any event */ id gmsQEvWorkst (event) id event;

Version 6.2a- 26 May 2006

SL-GMS Reference 7-18

8

Overview

Display of Models

The WinModState controls the display of a Model in a window. The WinModState also provides attributes which control the way in which the Model is displayed in the window when the window is created or resized. The WinModState invokes a hierarchy of standard subStates, each of which manages a specific resource such as a Model, View, or Window. Like all aggregate States, the WinModState directs application messages it receives to its subStates. For example, an application can set the window frame components, the name of the Model to display, or the size and position of the Window on the Screen by sending messages directly to the WinModState. Refer to the SL-GMS® State Class Library Reference.

Coordinate systems

There are several coordinate systems used in the display of Models on a display screen. Mapping between these coordinate systems allows representation of Points as real numbers that apply to the application design rather than numbers constrained to an arbitrary scale. The table below summarizes the different coordinate systems. The individual coordinate systems are described in the following sections.

Coordinate System World Coordinates (WC) Normalized Device Coordinates (NDC)

Use

Range

Description

Specification of (-32,768., -32,768.) page 8-4 Points in to Models (32,767., 32,767.) Specification of 0.0 to 1.0 Points on an idealized device-surface page 8-5

Version 6.2a- 26 May 2006

SL-GMS Reference 8-1

Display of Models

Coordinate System Normalized Screen Coordinates (NSC) Use used for window size and position Range 0.0 to 1.0 Description page 8-8

Normalized Window specification of 0.0 to 1.0 Coordinates (NWC) the anchor point used to position the window on the display screen Device Coordinates (DC->IPC)

page 8-10

Device-depend platform dependent page 8-3 ent specification of Points SL-GMS-intern (-2,147,483,648, al use for -2,147,483,648) performance to optimization (2,147,483,647, 2,147,483,647) page 8-2

SL-GMS Internal Coordinates (IC)

SL-GMS Internal Coordinates (IC)

Using integers for internal representation of Points allows SL-GMS applications to run faster because of the performance advantage of integers over floating-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 multiplying each 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 of 65,536 for the World Coordinate Scale Factor). The World Coordinate Scale Factor can be changed using the gmsWCScale( ) function.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-2

Display of Models

Normalized Device Coordinates (NDC) are also converted to Internal Coordinates by multiplying each NDC by the Normalized Device Coordinate Scale Factor (NDCSF), which is 100 times the WCSF by default. The Normalized Device Coordinate Scale Factor can be changed using the gmsNDCScale( ) function.

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.

Specifying coordinates to SL-GMF functions

Often in SL-GMF, parallel functions are provided to allow for two approaches to coordinate specification: as a number or as a Point object. When numbers are specified, the user must keep track of which coordinate system the function call requires, and SL-GMS multiplies the coordinates by one of two scaling factors: the WCSF or the NDCSF. When a Point object is specified, the Point object must be created using a function such as gmsNPXY( ). Of course, the function which creates the Point expects a certain coordinate system (WC, NDC). However, once the Point is created, it is comprised of SL-GMS Internal Coordinates (IC) and can be used to specify equivalent WC and NDC spaces.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-3

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 centered at the origin, (0., 0.), and extends both positively and negatively out to limits related to the World Coordinate Scale Factor (WCSF) (65,536 by default). 1 The default WCS limits are (-32,768., -32,768.) to (32,767., 32,767.). World Coordinates are multiplied within SL-GMS by the World Coordinate Scale Factor and converted into 32-bit integers for internal representation. Figure 8-1: shows a Model with a default size of 72 x 54 WC units, with its lower-left corner at (0., 0.).

World Coordinate Space (WC) (-32.768., -32.768.) (32.767., 32.767.)

WC-window (WC) (0., 0.) (72., 54.)

Model

Figure 8-1: A Model in World Coordinate space

1. 0x10,000 = 16 4 = 2 16 = 65,536

Version 6.2a- 26 May 2006

SL-GMS Reference 8-4

Display of Models

Views

Models are displayed in a View within a window. The View is defined by two extents; a World Coordinate (WC) extent, and a Normalized Device Coordinates (NDC) extent, as shown in Figure 8-2:.

World Coordinate Space (WC) (-32.768., -32.768.) (32.767., 32.767.)

Model Extent (WC) (0., 0.) (72., 54.)

Model

View (0., 0.) (72., 54.) WC-extent (0., 0.) (0.72, 0.54) NDC-extent

Normalized Device Coordinate Space (NDC) intended to be (0.0, 0.0) to (1.0, 1.0)

Figure 8-2: Mapping a Model into a View object 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. For instance, in Figure 8-2:, the WC-extent of the View 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 same Model. In "View1" the WC-extent of the View is the same as the WC-extent of the Model, (0.0, 0.0) (72.0, 54.0), therefore, the entire Model is displayed 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 within that extent are displayed in the View.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-5

Display of Models

(72.0, 54.0) tank 2 Model tank 1 (0., 0.) View1 tank 2 tank 1 (0., 0.) (0., 0.) (72.0, 54.0) tank 1 (36.0, 0.) View2 (36.0, 27.0)

Figure 8-3: Two different View WC-extents The size of the View's WC-extent is set using the view_wc_extent attribute 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 Normalized 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 represented as 0.0 NDC units. The size of the View in NDC is set using the view_ndc_extent attribute of the WinModState, and the default View starts at (0., 0.) and goes to (0.72, 0.54) NDC units. It should be noted that these coordinates are exactly 1/100 the size of the View's default WC extent, which runs from (0., 0.) to (72., 54.), because the default NDCSF is 100 times the WCSF . When the NDCSF is set to anything other than 100 times the WCSF , then the NDC coordinates will not be 1/100 the size of View's WC extent, and SL-GMS has to perform an extra transformation when the View is displayed. NOTE: The View's WC coordinates do not have to correspond to 100 times the View's NDC coordinates; only the aspect ratios between the View's WC extent and the View's NDC extent must stay the same.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-6

Display of Models

The aspect ratio, the ratio of width to height, must be exactly the same in the View's WC and NDC extents. If the aspect ratio is not the same between the View's WC-extent and the View's NDC-extent, objects displayed in this View are scaled unevenly and appear distorted.The keep_aspect_flag attribute of the WinModState is set equal to one if the aspect ratio of the View's WC-extent and the View's NDC-extent are to be maintained when the window is resized.

Windows

The window is positioned, and sized on the display device using different attributes of the WinModState. Each of the attributes of the WinModState are further defined in the SL-GMS® State Class Library Reference manual. Figure 8-4: illustrates the mapping of a Model in World Coordinate space into a View, and then into the window.

WC-window (WC) (0., 0.) (72., 54.)

World Coordinate Space (WC) (-32.768., -32.768.) (32.767., 32.767.)

Model

Device Coordinate Space (DC) display device (pixels)

View (0., 0.) (0.72, 0.54) NDC-e (0., 0.) (72., 54.) WC-exte

Model

window

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

Version 6.2a- 26 May 2006

SL-GMS Reference 8-7

Display of Models

Specifying the size of the window

The size of the window is specified using the win_size attribute of the WinModState. The win_size attribute specifies the width and height of either the window frame and drawing area, or the window drawing area by itself, in Normalized Screen Coordinates. Normalized Screen Coordinates (NSC) are real values 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 the Model "mymodel". The size of the window should have a 4 to 3 aspect 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 the example above) on the display screen.

1.0 display screen NSC 0.3 Model 0.0 0.0 0.4 Normalized Screen Coordinates (NSC) win_size equal to (0.4, 0.3) 1.0 window

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

Version 6.2a- 26 May 2006

SL-GMS Reference 8-8

Display of Models

If the width and the height of the window are not specified, the WinModState uses the World Coordinates extent of the View and the mapping factor to make up the window dimensions. If the World Coordinates extent is not available, the WinModState gets it by loading the Model and approximating the View extent from the Model dimensions. The mapping_factor attribute specifies the relationship between the World Coordinates used in the Model and the Normalized Screen Coordinates used to position and size the Window. The mapping_factor indicates the number of World Coordinate units that can be displayed along the width of the Screen. The default value for the mapping factor is 100.0. With this mapping_factor, a full-screen Window would display a Model with a World Coordinate width of 100.0 units, and a Model with the default width of 72.0 WC units would take 72% of the width of the screen.

Setting the location of the window

The win_position attribute of the WinModState defines the location on the screen of the window frame corner specified by the win_position_offset attribute. The win_position location is specified using Normalized Screen Coordinates (NSC). The default window position is at the lower-left corner of the screen. The following example creates a window whose lower-left corner is located at the middle of the bottom edge of the screen and displays 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.0 0.0", NULL); Figure 8-6: on page 8-10 illustrates the placement of the window (created in the above example) on the display screen.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-9

Display of Models

1.0 display screen NSC window Model 0.0 Normalized Screen Coordinates (NSC) 1.0 win_position equal to (0.5, 0.0)

Figure 8-6: A "win_position" equal to (0.5, 0.0) Unless specified otherwise, the win_position_offset attribute has for the default value the lower-left corner of the window frame. At times, it may be necessary to position the window by its upper-left corner or to center the window around a point on the screen. The win_position_offset is provided for this purpose. The win_position_offset attribute specifies an anchor point in the window. The anchor point is the point by which the window is positioned on the screen. The point is specified in Normalized Window Coordinates. Normalized Window Coordinates (NWC) are real numbers in the range of 0.0 to 1.0, as shown in Figure 8-7:.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-10

Display of Models

1.0 window NWC Model

0.0

Normalized Window Coordinates (NWC)

1.0

Figure 8-7: Normalized Window Coordinates (NWC) The x-coordinate of the win_position_offset attribute is specified as a percentage of the width of the window frame ranging from 0.0% (use the value 0.0 for the leftmost edge of the window frame) to 100.0% (use the value 1.0 for the rightmost edge of the window frame). The y-coordinate of the win_position_offset attribute is specified as a percentage of the height of the window frame ranging from 0.0% (use the value 0.0 for the bottom edge of the window frame) to 100.0% (use the value 1.0 for the top edge of the window frame). Several examples are shown in Figure 8-8:. The anchor point is represented by the black dot.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-11

Display of Models

Model

Model

(0.0, 0.0)

(1.0, 0.0)

Model Model

(0.0, 0.5)

(0.5, 0.5)

Figure 8-8: Some common "win_positin_offset" values Other common values are: (0.0, (1.0, (0.5, (1.0, (0.5, 1.0) 1.0) 1.0) 0.5) 0.0) = = = = = upper-left corner upper-right corner middle of top edge middle of right edge middle of bottom edge

The default value is set to (0.0, 0.0) so that the position of the lower-left corner of the window frame is specified by the coordinates of the win_position attribute.

Setting the name of the Model

The model_name attribute of the WinModState specifies the name of the Model to display in the View. The model_name attribute is the only attribute that needs to be specified. This attribute is enough for the WinModState to calculate the size and position of the window and the drawing area.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-12

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 zooming

Panning or zooming over a Model is best conceived as a series of WC-extents being progressively redefined and mapped successively into the same View. When panning, the WC-extent remains the same size, but its position is changed. When zooming, the WC-extent changes size. Panning and zooming is handled by the ViewMgrState. The application invokes an Instance of the ViewMgrState as a substate of the WinModState that is displaying the Model. State messages are sent to the ViewMgrState to control the zooming and panning. The ViewMgrState section of the SL-GMS State Class Library Reference manual describes the various action methods that are available to control zooming and panning. The following example sends the "zoomrect" message to the ViewMgrState. The zoomrect method prompts the user to select (using the left mouse button) the two corners of a rectangle extent. The view_wcextent is then adjusted to the extent defined by the rectangle. STMSG(viewmgr_statename, "zoomrect", " ");

Externally created windows

Models can also be displayed in a window that is externally created (i.e., in a window that is created by the application and not by SL-GMS). The application creates the window and then sends the "app_window_handle", "app_subwindow_handle", and "model_name" messages to the WinModState. Several examples of creating an external window and displaying a Model in it, are described in the SL-GMS Examples Manual. Two of the examples can be found in the Framework Enhancement on page E-8 and Appendix D -- Detailed Analysis: myproject_motif.

Version 6.2a- 26 May 2006

SL-GMS Reference 8-13

9

Introduction

Text

In SL-GMS, Text is rendered according to its precision, font index within that precision and, if appropriate, workstation class. Although most workstation types support only the first two, SL-GMS currently supports three distinct 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 "fontdef.dat" entry. See the section, Specifying alternative and additional fonts on page 9-5, for a description of usage of the "fontdef.dat" font configuration file. Figure 9-1: shows PostScript printer output for each font index of the thirteen default precision 0 fonts used by the PostScriptWs layer of SL-GMS.

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)

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

Version 6.2a- 26 May 2006

SL-GMS Reference 9-1

Text

A Text object's precision determines its behavior. The following table summarizes the behavior of the three Text precisions. Text Precisions in SL-GMS Precision 0 Description 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. This precision uses workstation-independent "Hershey" fonts. All SL-GMS transformations are applied to the text. This precision uses workstation-dependent fonts. All SL-GMS transformations are applied to the text.

1

2

Text sizing behavior

The height attribute of a Text object, transformed into device coordinates, determines the font size that SL-GMS will use. The "ink extent height of the capital letter 'A'" provides the reference measurement that SL-GMS uses to portably size text. Precision 1 fonts are completely scalable and behave identically across platforms. Precision 0 fonts are platform dependent and may or may not be scalable. If the font is not scalable, then SL-GMS must choose among one or more fixed sizes. The size selected will be the largest size available that is smaller than or equal to the desired size. If the desired size is smaller than the smallest available, the smallest available will be used. For example, suppose that the non-scalable Courier Bold 20 font exactly matches the desired height for a label's text. If the user resizes the window to half its former height, SL-GMS searches first in the Courier Bold family for a font of size 10. If a size 9 is found, but no size 10 is found, the size Courier Bold 9 font is used.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-2

Text

Default Fonts

SL-GMS supports many workstation classes and attempts to provide a consistent font interface across all platforms, graphics packages, and output devices. Since it is not possible to guarantee that text will appear exactly the same when applications are moved from workstation to workstation, SL-GMS provides workstation-dependent default definitions for the non-PostScript workstation types that match as closely as possible with the default PostScript fonts. Figure 9-2: lists the default names for the SL-supported workstation classes.

Index 1 2 3 4 5 6 7 8 9 10 11 12 13

PostScript Helvetica Courier-Bold Courier Times-Roman Courier-Oblique Times-Bold Helvetica-Bold Helvetica-Oblique Times-BoldItalic Times-Italic

X helvetica-medium-r courier-bold-r courier-medium-r times-medium-r courier-medium-o times-bold-r helvetica-bold-r

Windows NT Arial Courier New-Bold Courier New Times New Roman Courier New-Italic Times New Roman-Bold Arial-Bold

helvetica-medium-o Arial-Italic times-bold-i times-medium-i Times New Roman-Bold-Italic Times New Roman-Italic Arial-Bold-Italic Courier New-Bold-Italic Symbol

Helvetica-BoldOblique helvetica-bold-o Courier-BoldOblique Symbol courier-bold-o symbol-medium-r

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

Version 6.2a- 26 May 2006

SL-GMS Reference 9-3

Text

Precision 1 fonts

Precision 1 text is rendered by SL-GMS using Hershey text fonts. They are public domain vector text created by A.V. Hershey and distributed by the National Bureau of Standards, Report No. NBS SP-424. SL-GMS provides 18 Hershey fonts 1 in the "$GMS_HOME/lib" directory as "* .fnt" files. By default, no precision 1 fonts are operative. To make precision 1 fonts operative, they must be specified in the "fontdef.dat" file. Figure 9-3: shows the set of Hershey fonts with the names as used in the "fontdef.dat". "fontdef.dat" Names SimpRom CompRom DupRom CartRom CompCyr CompGreek CompItal CompScr GothEng GothGerm GothItal SimpGreek SimpScr Symbol1 Symbol2 Symbol3 TripItal 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-4

Text

See the section, Specifying alternative and additional fonts on page 9-5 for how to specify fonts using the "fontdef.dat" file. Figure 9-4: shows an example 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 specify additional fonts of any supported precision through the use of a "fontdef.dat" file. SL-GMS reads at most one "fontdef.dat" file, searching first in the current directory, then in directories added via application program calls to the function, gmsAddLibPath( ), and finally, in the "$GMS_HOME/lib" directory. The "$GMS_HOME/lib" directory holds a default "fontdef.dat" file, which specifies four Hershey fonts used by some SL-provided demos. The actual format of a "fontdef.dat" entry is platform-dependent, although Hershey fonts are specified identically across platforms. Refer to the subsections below that discuss characteristics of specific workstations. A sample "fontdef.dat" file defining four precision 1 fonts is shown in Figure 9-4:.

default default default default hershey hershey hershey hershey 1 2 3 4 SimpRom CompRom DupRom CartRom /* prec 1, index 1 /* prec 1, index 2 /* prec 1, index 3 /* prec 1, index 4 */ */ */ */

Comment Font Name SL-GMS Font Index Font Precision Workstation Class Name

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 different Workstations; e.g., use "default" for screen and "PostScriptWs" for printer output.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-5

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. 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". specifies the platform-dependent name of the font. Refer to the subsections below that discuss characteristics of specific workstations.

Font Index

Font Name

/* Comment* / specifies comments which can be placed anywhere in the line; they conform to the C programming language style, where comment strings are enclosed in "/* " and " * /". Any number of comments are allowed in a single line, but a comment may not span more than one line. The following subsections give the detailed "fontdef.dat" specifications for platforms supported by SL-GMS.

X Window System

default default default default raster raster raster raster 11 12 13 13 9x15 -linotype-helvetica-medium-r-normal--0-0-0-0-p-iso8859-1 -adobe-helvetica-medium-r-normal--*-*-0-0-p-iso8859-1 adobe-times

Font Name SL-GMS Font Index Font Precision Workstation Class Name

Figure 9-5: Example "fontdef.dat" for the X Window System Many platforms supported by SL-GMS use the X Window System, which continues to evolve new font technologies with each release. For instance, the X Logical Font Description (XLFD) was introduced with Release 4 of X Version 11. Support for scalable fonts and international font sets were major additions to Release 5.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-6

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 set is being specified. This section discusses single-font environments; see XFontSet platforms on page 9-7 for details specific to font set specification. The XLFD standard, Version 1.4, defines a "well-formed XLFD pattern" as a string containing fourteen (14) hyphens, one of which is the first character 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 to the pattern and uses the XListFonts( ) facility to build the list of font names available 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 processed by XListFonts( ). Scalable fonts must be explicitly specified using zeros ("-0-") in the XLFD fields for PIXEL_SIZE, POINT_SIZE, and AVERAGE_WIDTH.

XFontSet platforms

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-*-*-0 XWs raster 15 -sun-minchou-medium-r-normal--*-*-75-75-c-*-*-0 XWs raster 16 -morisawa-gothic medium bbb-medium-r-normal-sans-0-0-0-0-m-0-*-0 XWs 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-*-0 XWs 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

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 the internationalization input/output technologies introduced with Release 5 of

Version 6.2a- 26 May 2006

SL-GMS Reference 9-7

Text

X Version 11. The XFontSet technology forms the basis of internationalized 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 each character set required to support the current locale. SL-GMS adds the requirement 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 chosen to match as closely as possible. A "fontdef.dat" entry for font sets consists of one or more comma-separated "well-formed XLFD patterns". Escaped newlines (a backslash "\" followed immediately by the end-of-line character) may be used if convenient. An asterisk (* ) wildcard as the first character in the XLFD field for CHARSET_REGISTRY may enable a single pattern to specify fontset 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 font for 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 Japanese locale requiring fonts for "jisx0201.1976-0" and "jisx0208.1983-0". Some variation in Xlib's rendering of ASCII text has been noted across platforms when multiple "ASCII-capable" character sets are active: in some cases the "iso8859-1" font is used; in others the local "ASCII-capable" font is used. The latter case may call for extensive "fontdef.dat" specification if ASCII text rendering is important. Earlier localized versions of SL-GMS used locale- and platform-specific proprietary technologies to support localized text output, and by default fonts 14 and 15 (Figure 9-6:) were used to display localized text while default fonts of index 1 to 13 were properly used for ASCII only. XFontSet platforms support display of localized text using any font index, and no defaults are provided for fonts 14 or 15. The sample "XWs raster 14" and "XWs raster 15" entries emulate the default behavior of SL-GMS under Sun's obsolete Japanese Language Environment. 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 17 and 18 are equivalent.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-8

Text

Windows NT

default default default default default default default default default default default default raster raster raster raster raster raster raster raster raster raster raster raster 1 Times New Roman 2 Times New Roman-Italic 3 Times New Roman-Bold 4 Times New Roman-Bold-Italic 5 Algerian 6 Algerian-Italic 7 Courier New 8 Courier New-Italic 9 Courier New-Bold 10 Courier New-Bold-Italic 11 Symbol 12 Symbol-Bold

Font Name SL-GMS Font Index Font Precision Workstation Class Name

Figure 9-7: Example "fontdef.dat" for a Windows NT system TrueType fonts are supplied with Windows NT. An SL-GMS NT Font Name is composed of the font family name and an optional list of one or more style modifiers separated by the "-" character. Figure 9-7: shows a sample "fontdef.dat" for a Windows NT system.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-9

Text

The table below lists the TrueType font family names appropriate for use the "fontdef.dat" file. 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 The following table lists the set of Font style modifiers. Font style modifier Bold Italic Strikeout Underscore

Version 6.2a- 26 May 2006

SL-GMS Reference 9-10

Text

The font style modifiers are not case-sensitive and may be applied in any order to a given font definition. Figure 9-8: provides an example of an SL-GMS Font Name appropriate to Windows NT.

Times New Roman-Bold-Italic-Strikeout-Underscore Family Name Style Modifiers

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 should list only TrueType fonts. Any non-TrueType font listed in "fontdef.dat" will be 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 the definition 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 disable rotation for precision 0 (TrueType) text. Refer to the SL-GMS® Function Reference. The "tprec0_rot_flag" message can also be sent to the StandardTopState to enable or disable rotation for precision 0 text. Refer to the SL-GMS® State Class Library Reference.

Using the fontdef program

The fontdef program is provided with SL-GMS (Windows NT only) in the work\fonts directory. The fontdef program enumerates all of the installed TrueType fonts on a given system. When the output is redirected to a file, it generates a font 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-11

Text

To run the program type: fontdef [index starting_index] ["fonts_to_be_ignored"..] > filename starting_index = optional number specifying the first index to start the list. If none is specified, then 14 is used as the default. "fonts_to_be_ignored" = optional list of font family names, separated with spaces, that will be excluded from the generated output file. A font name that contains spaces must be enclosed by double quotes (e.g., "Arial Black") For example, to generate a "fontdef.dat" file in the current directory that will start with index 14 and will not include any Arial 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 your application. One of the thirteen default fonts can be overridden by adding an entry for the desired font index to the "fontdef.dat" file.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-12

Text

PostScript Workstation

PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs PostScriptWs raster raster raster raster raster raster raster raster raster raster 1 Helvetica 2 Helvetica-Oblique 3 Helvetica-Bold 4 Courier 5 Courier-Bold 6 Courier-Oblique 7 Times-Roman 8 Times-Bold 9 Times-BoldItalic 10 Symbol

Font Name SL-GMS Font Index Font Precision Workstation Class Name

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 Precision field must be "raster". Note that the word "raster" specifies precision 0 (non-rotatable) text and does not accurately describe the implementation of precision 0 text. Precision 0 text is implemented using PostScript and not raster fonts.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-13

Text

PostScript output

PostScript output is provided for any of the three types of Text and is used exclusively on PostScript printers and display devices. SL-GMS translates Text in SL-GMS Model files into the PostScript font that is the nearest match to the fonts listed in Appendix A of the PostScript Language Reference Manual from Adobe Systems, Incorporated. Figure 9-10: and Figure 9-11: show the PostScript font mapping for all font index-precision pairs.

Coordinates and Modes

For PostScript itself: · · · The standard mode is portrait, with (x, y) = (0, 0) at the lower left corner. The standard page size is 8 1/2 x 11 inches. The standard coordinates are 72 points per inch, which yields a maximum of 612 x 792 points per page.

For SL-GMS: The coordinate ranges to be considered when specifying x and y displacement for Models that are to be output by a PostScript printer are: · · 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 uniform margin of half an inch around the PostScript printout. In the options described below in the PostScript Options table, the values of N are to be within those ranges. NOTE: In the PostScript file itself, the coordinate ranges actually used are in a default range of ten times those numbers with a default scale factor of 0.1 for both x and y. This permits taking advantage of the 300 dots per inch precision of a typical PostScript printer while using only integers.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-14

Text

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)

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

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

Version 6.2a- 26 May 2006

SL-GMS Reference 9-15

Text

Initiating PostScript from an SL-GMS application

To print a View (with its Models) from an application, the function gmsPsViewWrite( ) should be used (the SL-GMS Function Reference provides information about this function). The function gmsPsWsProcArgs( )3 is the 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 set 4 with gmsPsWsProcArgs( ). For example, the following code fragment could be used to print a PostScript file with the -a, -l, and -f8 options: idLinkRef views; int p_argc; char * p_argv[3]; views = refNewRef(gmsFindByName("v_main")); refAdd( views, gmsFindByName("v_sub")); p_argc = 3; p_argv[0] = "-pa"; p_argv[1] = "-pl"; p_argv[2] = "-pf8"; gmsPsWsProcArgs(p_argc, p_argv); gmsPsLViewWrite(gmsQEvWorkst(gmsQGismoEvent( )), views, "test") For non-C programming languages or situations where the argc-argv mechanism is inconvenient or simply unavailable, the function, gmsPsWsProcArgsStr(argstr), can be used instead of gmsPsWsProcArgs( ).

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.

Version 6.2a- 26 May 2006

SL-GMS Reference 9-16

Text

argstr is of type char* , where the character string contains space-separated arguments. Quotes attempting to combine words into one argument are not accounted for. For example, the following two calls result in the same print output to a PostScript file with -op, -c, and -s options: gmPsWsProcArgsStr("-pop -pctest_print -ps50") is the same as... gmsPsWsProcArgs(argc, argv) with: argc = 3 argv[0] = "-pop" argv[1] = "-pctest_print" argv[2] = "-ps50"

Polyline point limit

PostScript interpreters vary in terms of the maximum number of points they can process in one polyline. Some can handle only 200, most 1500 (the SL-GMS default if not overridden) and some more. The gmsPsPolyMaxPoints( ) function(refer to the SL-GMS® Function Reference for more information) is provided to inform SL-GMS of the limit for a particular PostScript interpreter. Polylines that are larger than the interpreter's limit are "broken" into smaller segments when printed. For example, the following code fragment could be used to inform SL-GMS that the printer's upper limit for the number of points in a polyline is 200. idLinkRef views; int p_argc; char * p_argv[3]; views = refNewRef(gmsFindByName("v_main")); refAdd( views, gmsFindByName("v_sub")); p_argc = 3; p_argv[0] = "-pa"; p_argv[1] = "-pl";

Version 6.2a- 26 May 2006

SL-GMS Reference 9-17

Text

p_argv[2] = "-pf8"; gmsPsWsProcArgs(p_argc, p_argv); gmsPsPolyMaxPoints(200); gmsPsLViewWrite(gmsQEvWorkst(gmsQGismoEvent( )), views, "test")

Version 6.2a- 26 May 2006

SL-GMS Reference 9-18

10

Introduction

Color

SL-GMS provides a consistent set of functions for the allocation and management of colors on a variety of platforms. Because color capabilities vary depending upon hardware and windowing systems, slightly different color-handling behavior can be expected across platforms. Every SL-GMS application requires, and allocates, 16 colors per Workstation. SL-GMS processes do not share the system colormap. Colors are standardized across all platforms. This means that if a "colordef.dat" file is not read by SL-GMS (for whatever reason), the SL-GMS indices 0 through 15 have the same red, green, and blue values, irrespective of the type of SL-GMS Workstation, whether it be X, Windows, or PostScript. SL-GMS handles all six of the X visual types (DirectColor, TrueColor, PseudoColor, StaticColor, GreyScale, and StaticGrey). SL-GMS determines the type of visual best suited to its needs, according to a set of internal 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.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-1

Color

Changing SL-GMSDraw's color palette

SL-GMSDraw's default color palette in the Color Attribute Control Panel contains 32 colors. The colors are defined in the file "colordef.dat". The color panel in the Default Graphic Properties window displays 32 colors at a time. If more colors are defined in the "colordef.dat" file, the user can scroll to select a color.

Color definition files

Color definitions can be specified in the "colordef.dat" file distributed in the lib directory. This file associates a color index with the color's red, green, and blue values and an optional bitplane writemask. The index1 must be an integer between 0 and 2 31, and the RGB values must be real numbers between 0 and 1 (which represent percentages of total saturation). The bitplane writemask is an integer in either binary or hexadecimal form. The rest 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

Example

0 1 2 3 4 5 6 7 8 9 10 1 1 1 0.9191 0 0 0 0.8714 0.2857 1 1 0 0.2879 0.4945 0.9067 0.593 0 0.6421 0.0541 0.9599 0.9185 0 0 0 0.7054 0.8031 0.7972 1 0.6374 0.3474 0.6648 1 0.6694 White Red2 SpringGreen3 Yellow SteelBlue3 Magenta3 Cyan2 Black LightCyan3 Tan1 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 2 15-1.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-2

Color

The fifth field can be either a bitplane mask or a comment. If it contains only 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 of hexadecimal digits, 0123456789abcdefABCDEFxX, it is taken to be a hexadecimal bitplane mask. Otherwise, it is treated as a comment ("White" in the example, above). If a bitplane mask is included in the fifth field, the G_WS_PLANE_MASKING bit needs to be set. The SL-GMS® Function Reference describes the workstation options. In addition, if the first non-blank character in a line is not a number, the entire line is treated as a comment. Comments in the style of C programming language (i.e., strings enclosed in "/*" and "*/") are allowed in the file "colordef.dat". Any number of comments are allowed in a single line, but a comment may not span more than one line. During its startup sequence, SL-GMS looks for a "colordef.dat" file in the current working directory. If no "colordef.dat" file is found, SL-GMS next looks in any directories added to the search path (using gmsAddLibPath( )). If no "colordef.dat" file is found, SL-GMS uses its own default "colordef.dat" file located in the lib directory. The color definitions in SL-GMSDraw cannot be modified from within SL-GMSDraw. To modify the color definitions, the editor must be exited and then restarted in a directory with the desired "colordef.dat" file.

Creating a "colordef.dat" file

An example program, called colordef in the demo directory, can be used to create a "colordef.dat" file. The "README" file in the colordef directory provides instructions for running the program. NOTE: The "colordef.dat" file is read only once, during initialization. This means that, in order to re-read a "colordef.dat" file that has been modified, the application must be restarted.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-3

Color

Using colors above index 31

The color panel in the Default Graphic Properties window displays 32 colors at a time. A scrollbar appears to the right of the color panel if more than 32 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 the lib directory and provides a straight mapping of screen colors to PostScript output. A screen color, defined by an index number, can be translated to a different color for PostScript output by editing the "pscolordef.dat" file with a standard text editor and changing the RGB entries for the desired screen color index.

Reverse video

Normally, SL-GMS applications, including SL-GMSDraw, use colors 0 and 7 for their background and foreground colors, respectively. Usually color 0 is white and color 7 is black. To reverse these two colors (or to choose different colors for foreground and background) the colors 0 and 7 must be redefined.

Example

0 7 0.0 1.0 0.0 1.0 0.0 1.0 // black // white

Grey-scale

Grey-scaling is accomplished using a special file, "colordef.grey", which is provided in the lib directory. In order to use "colordef.grey", the file must be copied to the current working directory and renamed to "colordef.dat".

Version 6.2a- 26 May 2006

SL-GMS Reference 10-4

Color

AutoCAD colors

The SL-GMS utility dxf2g 2 converts AutoCAD ".dxf" (Data Exchange Format) files to SL-GMS ".g" (ASCII) Model files. Several options can be added 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 Model made without -cf, the "colordef.dat" file for SL-GMSDraw must be a copy of "colordef.acad". 2. Specifying -cf is equivalent to saying, "Only the SL-GMS colors are available for display; use them in the best way." In this case, each AutoCAD color number is converted to an index between 0 and 31, so that the selected color is the "best fit" to one of the standard SL-GMSDraw colors. In this case, the regular SL-GMS 32-color "colordef.dat" file will work satisfactorily. The file "colordef.acad" distributed in the lib directory contains 168 RGB entries as follows:

Index 0-31 32 33-41 42-51 52-61 ...... 152-161

Contents Standard SL-GMS colors White AutoCAD colors 1-9 AutoCAD colors 10-19 and 20-29 AutoCAD colors 30-39 and 40-49 ............... AutoCAD colors 230-239 and 240-249

2. The section AutoCAD dxf2g ".dxf" file converter on page D-4 provides a complete description of the conversion of ".dxf" files.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-5

Color

Index 162-167

Contents AutoCAD colors 250-255

If the display hardware is capable of simultaneously displaying the necessary number of colors, "colordef.acad" may be set up as the "colordef.dat" file before using SL-GMSDraw to display Models created from ".dxf" files with 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. The SL-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 attempt is made to display a Model converted without the -cf option set, it is probable that no display will occur at all.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-6

Color

Common Desktop Environment (CDE) colors

A "colordef.cde" file, included in the lib directory, enables SL-GMS applications to share colors with the Common Desktop Environment(CDE). The RGB values defined in the "colordef.cde" file match the sixteen static colors used by the CDE. In order to share colors with the CDE, rename the "colordef.cde" file in the lib directory to "colordef.dat". In addition, the G_WS_LOOKUP_COLORS option must be enabled in an application in order to have SL-GMS share colors with the CDE. Add the following call to the application: gmsWsDefaultOpts(G_WS_LOOKUP_COLORS); Additional information about the gmsWsDefaultOpts( ) function, and the G_WS_LOOKUP_COLORS option is provided in the section Workstation/Window -- object in SL-GMS Function Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference 10-7

11

Introduction

Performance

The display and monitoring of application system activity often requires very critical timing constraints. To meet these constraints the developer must optimize all aspects of data collection, processing, and display. SL-GMS provides a number of services that assist the developer to achieve exceptionally high performance in loading, displaying, and updating graphical screen displays. Some of these services are described in this chapter, along with advice on additional user and developer strategies that can be implemented to optimize the application of SL-GMS. Optimization techniques are divided into those appropriate for users of SL-GMS tools and those appropriate for programmers who are extending the tools for custom applications. Performance issues important to users involve Model creation using SL-GMSDraw and file usage. Issues important to programmers involve the optimum definition of variables, optimizing dynamic Model elements, developer-defined functions, and, generally, reduction of unnecessary calculations and displays.

Optimization by users Model creation

Significant performance improvement can be achieved if SubModels are created with the exact size and orientation required in the top-level Model. Run-time execution is saved because the top-level Model avoids the application of scaling and rotation transformations on its SubModels. Thus, SubModel objects such as Rectangles, Circles, and Arcs that are the correct scale will display faster in the top-level Model. Similarly, each rotation of a SubModel adds overhead time because a rotation matrix must be applied to the SubModel for each distinct orientation. Since SubModels are incorporated (instanced) many times in various top-level Models, a very large return in performance is achieved by concentrating effort on optimizing performance of SubModels.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-1

Performance

It is recommended that the Apply Transform option of the Object Pull-Down Menu in SL-GMSDraw or the xtran command in SL-GML be used after building Models that are to be loaded as SubModels at run time. This combines transformations accumulated during editing and applies them to the Points defining graphical objects. The Apply Transform advantage is limited in its application, however, due to the way certain objects are defined. The Apply Transform has no effect 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 the Apply Transform operation can be used. For example, if a rectangle is to be rotated, create the rectangle as a closed polygon with four points.

File usage

SL-GMS screen Models are typically stored in a standard binary "<modelname>.m1" file by the M1 filer. In many cases the standard ASCII ("<modelname>.g") form is used for device-independent archival purposes and such uses as text-based editing. The faster ".m1" form is typically used at run time in customer applications. The binary "<modelname>.m1" file was designed for use with SL-GMS development tools such as the SL-GMSDraw Graphical Editor and SL-GML Command Language. In the ".m1" file each graphical element is stored as a separate entity; therefore, parsing and reconstruction must be done as the file is read into memory. To achieve maximum possible screen-load performance of a top-level Model at run time, the M2 or contiguous filer is provided. The M2 filer produces a "<modelname>.m2" file in which screen-Model information is stored as an exact memory image of its internal form. Using the M2 filer, the entire screen-Model input is accomplished in one quick read, rather than parsed and reconnected as it is with the normal ".m1" filer. A good practice is to free ".m2" Models when no longer needed to make best use of time and memory. The following table shows a comparison of load times between the M1 filer and the M2 filer for top-level Models with and without SubModels.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-2

Performance

M1 FILER vs. M2 FILER

PERFORMANCE COMPARISON: Model Loading Times for Sun Sparc 2 System FILES: Top-level Models with and without SubModels

Top-level Model Pathname I. Loading Models with no SubModels: $GMS_HOME/demo/zoompan/zpmap3 $GMS_HOME/demo/gmsdemo/netmanage II. Loading Models with SubModels: $GMS_HOME/demo/graphs/xcustom $GMS_HOME/demo/minidraw/topmenu $GMS_HOME/demo/draw2/topmenu

SubModel Count 0 0 2 22 51

M1 Filer M2 Filer (ms) (ms)

252.45 136.30 245.26 180.79 169.43 347.90

72.60 24.84 54.60 109.13 131.43 231.71

$GMS_HOME/demo/network/SUBMODS/usa_map 0

Invoking the M2 filer

The M2 filer provides a set of functions parallel to those provided for the M1 filer. The functions to load and save ".m2" Models are gmsM2Get( ) and gmsM2Save( ). They are documented in the SL-GMS® Function Reference. The corresponding SL-GML commands to load and save ".m2" Models are m2get and m2save. They are listed in the chapter SL-GML Reference 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 the internal memory representation when read in. This allows the internal structure of SL-GMS objects to change (for optimization, rework, and so on) with no effect on the external file representation. The ".m2" format, on the other hand, is basically a memory image of the Model object. Even a minor internal change to the object data structures makes 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 all Models must be maintained for upward compatibility.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-3

Performance

Once read in, there is almost no difference in the internal memory used by Models read from ".m1" or ".m2" files. The ".m2" form uses slightly less internal memory because "<modelname>.m2" is really one allocated chunk, rather than an aggregation of pieces, allocated with the malloc( ) C function. The Models are identical in every other way once read in from either type of file. NOTE: Currently, SL-GMSDraw operates only on ".m1" files. An ".m1" file must be converted to ".m2" format using the m1m2 shell script. The State Management System (SL-SMS) always tries to load an ".m2" file. By default, a Model search is performed on each directory specified by gmsAddLibPath( ), searching first for ".m2" files and then ".m1" files before moving to the next directory. The function gmsStM2Flag( ) may be used to change the Model search behavior for a given State.

Double buffering

There 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 provided to allow users to selectively double buffer only a portion of a Workstation/Window for performance reasons. This type of double buffering is done in SL-GMSDraw, when the objects are created, by selecting doublebuffer in the Object Flags window of SL-GMSDraw for the object to be double buffered. The Object Flags window is displayed by selecting the Flags option in the Properties submenu of the Object Pull-Down Menu. The speed of a double-buffered redraw is proportional to the number of pixels to be transferred to the screen within the rectangular double-buffered region. By double buffering only the objects that exhibit annoying flashing, the area to be double buffered is reduced and the Model can be animated smoothly and in the fastest manner.

Object substitution

In many cases additional performance can be achieved by substituting faster-displaying objects for slower. For example, on X workstations, wide Lines in a Model can be replaced with an equivalent long, thin, filled Rect-

Version 6.2a- 26 May 2006

SL-GMS Reference 11-4

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 variables

Programmers know that the choice of variables and how they are structured affect efficiency of memory usage and speed of execution. In choosing variable definition types, the following should be considered specifically in relation to SL-GMS.

Array variables

Performance can be improved by the use of array variables. Many of the standard SL-GMS GISMO Action Functions, such as gms_radio_array( ), gms_toggle_array( ), and gms_textload_array( ), operate on array variables to load a Group of Text objects very quickly, as an array of text strings. The SL-GMS GISMO Action Functions are examples of user-defined actions. More information is provided in the section Dynamics driven by array variables on page 3-52.

Scoping Variable

In general, try to limit the use of variables to the screen state in which they are used. The use of State variable definitions decreases the time to define and create variables because SL-GMS collects VarDefs into their own State variable definition table. 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 the design approach where each Model is freed when it is not being displayed. Rather than removing the VarDef links before freeing the Model, gmsStFreeAllVarDefs( ) can be called to simply throw away all the variables associated with that Model. Any remaining Models do not have to be re-linked to a variable list because they are linked to their own local variables.

Developer-maintained Variable Definition tables

Version 6.2a- 26 May 2006

SL-GMS Reference 11-5

Performance

The following functions allow variables to be defined and designated as changed without having to do look-ups in the hash 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 not performed until the gmsDynUpdate( ) and gmsUpdate( ) calls are made. The gmsVarDefineNoTable( ) function must be used in conjunction with gmsVarInitFctn( ). Since no look-up tables are created, the user can no longer search for a variable by its name or address. Therefore, the VarDef objects must be maintained by the user and gmsVarDefChanged( ) must be used to indicate when a variable has changed. These functions require a bit more programming to maintain the VarDef objects, but increase performance for dynamic initialization and dynamic update. In many cases, the simplest SL-GMS design (all the variables defined as global) performs quite well. Applications which have a large number of variables, or need to scope variables, can use the State variable-definition approach or a combination of globally- and State-defined variables. In cases where there are strict performance requirements, or where the application design facilitates the maintenance of the VarDef objects, gmsVarDefineNoTable( ) and/or gmsVarDefChanged( ) may be used.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-6

Performance

Developer-maintained Variable Definition tables attached to Models

Variable Definition Tables support limited forms of dynamics in non-replicated SubModels.1 Variable Definition Tables may also be used as an alternative to State Variable Definitions or Renamed Variables. Variable Definition Tables are generally used in these types of applications: · · · applications which must non-replicated SubModels use dynamic descriptions in

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

The function gmsModDynInitVarDefTable( ) must be used on a non-replicated SubModel if that SubModel contains dynamics descriptions. The function gmsDynInit( ) does not work correctly in this situation. Only limited forms of dynamics descriptions work correctly on a non-replicated SubModel, even when Variable Definition Tables are used. A description of these limitations is provided in the section Suppressing SubModel replication on page 11-15. Applications having a strong correlation between data-driving structures and Model Instances may use Variable Definition Tables as an alternative to State Variable Definitions (created through gmsStVarDefine( )). The Variable Definition names in a Variable Definition Table are local in scope to a single top-level Model or Model Instance. If an application uses a separate structure to contain the data driving the dynamics in each Model Instance in a top-level Model, Variable Definition Tables provide a convenient

1. The section Suppressing SubModel replication on page 11-15 provides further information about non-replicated SubModels and the dynamics associated with them.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-7

Performance

mechanism for binding the data in those structures to the Model Instances. Renamed Variables are not needed in the Model Instances because the names in each Variable Definition Table are local in scope to each Model Instance. A Variable Definition Table can also be used on a top-level Model without interfering with any Variable Definition Tables on Model Instances in that Model. Variable Definition Tables should not be used on Model Instances contained in SubModels. The function gmsModDynInitVarDefTable( ) initializes the dynamic descriptions of all parts in the given Model. It also creates and stores a Variable Definition Table in the Model. If the Model already contains a Variable Definition Table, that table will be destroyed. The Variable Definitions in the Variable Definition Table are referenced only by Variable References contained in the Model. Unlike Variable Definitions in global or State tables, Variable Definitions in a Variable Definition Table contained in a Model cannot be used by any other Model. The gmsModDynInitVarDefTable( ) function can be used to initialize dynamics descriptions on SubModels prior to their replication. If this is done, there is no need to perform the initialization on the replicates. When a SubModel is replicated, its Variable Definition Table is also replicated. Once gmsModDynInitVarDefTable( ) has been called on a top-level Model, any gmsDynInit( ) call on that Model has no effect. The presence of a Variable Definition Table in a top-level Model blocks the effect of gmsDynInit( ) on that Model. Once gmsModDynInitVarDefTable( ) has been called on a SubModel, any gmsDynInit( ) call on parents of that SubModel has no effect on the SubModel. The blocking effect is local; SubModels which do not contain a Variable Definition Table are processed normally by gmsDynInit( ) calls on parents of the SubModel.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-8

Performance

Optimized dynamics

Optimized dynamics allow an application to set internal global flags that improve the object-updating performance of DynProps. By this technique an application can significantly streamline the dynamic update and display process. However, if only a small percentage of the total number of objects is to be changed between updates, usage of optimized dynamics can be slower than using regular dynamics. Certain functions control SL-GMS internal flags that are used to implement optimized dynamic Model features. Some of these functions control the use of optimized dynamics, while others affect the way that the update and display processes occur. The syntax for the functions and more detail about the use of these functions is described in the Dynamics -- optimization section in the SL-GMS Function Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-9

Performance

The following table lists use of these functions. Function Calls Used with Optimized Dynamics Function Call gmsAutoUpdateMode(G_ON) Description cause gmsDynUpdate(nil) and gmsUpdate(nil) to be done after each Event is processed in gmsMainLoop( ) (default: G_ON) indicate that all variables have changed between each update 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) disable extent calculation on objects that are not detectable; this makes the update pass quicker, but disables clipping (default: G_ON) disable setting of internal display flags used by SL-GMS during update pass (default: G_OFF)

gmsAllVarsChanged( ) gmsUseShadowMode(G_OFF)

gmsExtentMode(G_OFF)

gmsNoFlagsMode(G_ON)

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)

Optimizing DynProps with developer-defined functions

The dynamic descriptions which are contained in a DynProp that is stored on an SL-GMS Graphical primitive are stored both externally in ".m1" or ".m2" files and internally in run-time memory. These descriptions are a set of objects which are interpreted at run time. The external dynamic string

Version 6.2a- 26 May 2006

SL-GMS Reference 11-10

Performance

form is used only when creating and editing the dynamic description in a SL-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 introduces very little overhead into a properly constructed screen. However, any functionality of a dynamic description that can be shifted to the time when the object is compiled, linked, or loaded, saves real-time execution and speeds up operation of the model. Thus, the performance of dynamic Models that involve many instances of expression handling, conditional dynamic descriptions, or actions can be improved significantly by creating special optimization functions. Such functions are invoked using the call action within the dynamic description. The resulting optimization provides the following performance advantages: · · · smaller ".m1" and ".m2" Model files faster retrieval of these files at run time faster interpretation of gmsDynUpdate( ) phase the dynamics during the

For example, a standard conditional dynamics specification might be: x = 0 tcolor 5 bcolor 4 ecolor 1 x = 1 tcolor 4 bcolor 3 ecolor 0 and can be simplified to: x = 0 call user_set_color(__self, 5, 4, 1) x = 1 call user_set_color(__self, 4, 3, 0)

Version 6.2a- 26 May 2006

SL-GMS Reference 11-11

Performance

where the user_set_color( ) function looks like: int user_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 providing a function to do everything, including the conditional comparison: * call user_set_hilite(__self, x) where the user_set_hilite( ) function looks like: int user_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;

Version 6.2a- 26 May 2006

SL-GMS Reference 11-12

Performance

} return 1; } The user_set_hilite( ) function checks x and makes the appropriate calls to highlight or unhighlight the object, _self. The example highlighting function above is invoked from an unconditional action list -- essential for achieving maximum possible performance. Less information is read from the file and the execution is done in a compiled function, rather than interpreted. User-defined functions are further described in the section User-defined functions on page 3-35. NOTE: These user-defined functions are needed only to achieve maximum performance. In most cases, the normal DynProp interpretation is sufficiently fast, especially when used in conjunction with Array Dynamics.

Structuring DynProps for optimization

DynProps for objects are created using a SL-GMS Drawing Editor. The values used to drive dynamic actions are calculated by the application program. Optimized dynamics are created only for DynProps that use direct actions without expressions or interpolations. Direct actions unconditionally occur every time SL-GMS performs an update. Expressions are an arithmetic or logical operation surrounded by parentheses that are permitted in ordinary dynamic descriptions. The following is an example of a direct dynamic description that can be converted to optimized dynamics: * rotate angle fcolor fcol_1 Conditional dynamics that cannot be converted: angle_2 = -30.:-90. rotate angle_2

Version 6.2a- 26 May 2006

SL-GMS Reference 11-13

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 of the SL-GMS Quick Reference. If the variable type, as defined by gmsVarDefine( ), does not match the type of variable for the action, the dynamic description silently fails to be converted into an optimized dynamic description.

Disabling use of Shadow objects

Each 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's pre-change position and is used to erase the object. The use of Shadows is transparent to the application. In applications where the entire View is cleared and redrawn with each update, for example, when double buffering is used, the creation of Shadow objects introduces unnecessary overhead. Calling the gmsUseShadowMode( ) function with G_OFF prevents the creation of Shadows throughout SL-GMS.

Disabling calculation of extents

Each time an object is transformed, a new extent for the object must be calculated. The extent is used to determine whether the entire object appears in the View, or if part of the object must be clipped. (Most graphics windowing systems clip objects that would otherwise be drawn outside of the window.) The extent is also used to determine which object is the target of Locator (mouse) input by the gmsFindObject( ) function. Calling the gmsExtentMode( ) function with G_OFF prevents the calculation of extents for non-detectable objects only. If moving objects in View are made non-detectable, moving these objects does not cause new

Version 6.2a- 26 May 2006

SL-GMS Reference 11-14

Performance

extents to be calculated when this function is called with G_ON. Eliminating calculation of extents results in quicker update and display passes, if many objects have extents that are changing.

Font pre-loading

To minimize raster text overhead during the first display of a Model, it is important that the correct raster fonts be pre-loaded into SL-GMS. In general, applications linked with packages other than X automatically have text fonts pre-loaded by SL-GMS. In SL-GMS applications linked with X, a font is not loaded until the first time it is used.

Suppressing SubModel replication

SubModels are replicated by Model Instances which reference them. If each Model Instance does not have a unique replicate of the template SubModel, modifications to the appearance of the SubModel by one Model Instance will affect the appearance of all other Model Instances referencing that SubModel. The functions gmsSubModReplicateMode( ) and gmsModNonReplicate( ) control the replication behavior of a SubModel. The function gmsModNonReplicate( ) sets or clears the non-replication flag on a SubModel. By default, this flag is not set on a SubModel when it is created. When the flag is not set on a SubModel, the SubModel's replication behavior is defined by the global flag set by the function gmsSubModReplicateMode( ). When the non-replication flag is set on a SubModel, the global flag is overridden and the SubModel is not replicated by a Model Instance. Usually, the non-replicated flag is set only on SubModels having no animation or dynamics. Since the SubModel is never modified, Model Instances referencing that SubModel do not conflict with one another. Non-replicated SubModels can be used with dynamics in limited circumstances. Further information about these limitations is provided in the section Dynamics in Non-Replicated SubModels on page 11-16.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-15

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 a non-replicated SubModel are initialized more quickly, since the Model Instances do not have to replicate the SubModel

Currently, the status of the non-replication flag on a SubModel cannot be saved in a ".m1" or ".g" file. This means the non-replication flag must be set at run time. In order to set the non-replication flag at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ). To gain full control over the replication behavior of SubModels, the application should first call: gmsSubModReplicateMode(G_REPLICATE_ALWAYS); Individual SubModels are pre-loaded: id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1");

Then SubModels are marked non-replicated: gmsModNonReplicate(submodel1, G_ON);

Dynamics in Non-Replicated SubModels

Model Instances referencing a non-replicated SubModel must share a single copy of this SubModel in memory. Because of this, certain types of animation do not function correctly in non-replicated SubModels. It is not possible for a part within a non-replicated SubModel to erase itself directly. However, it is possible for a part to be erased indirectly by using a background Rectangle 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

Version 6.2a- 26 May 2006

SL-GMS Reference 11-16

Performance

· · · fill style: fstyle on Polygons only, fill direction: fdir. The fdir action works correctly on Rectangles, which do not perform erasure. on Polygons only, fill percent: fpercent. The fpercent action works correctly on Rectangles, which do not perform erasure. 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 a non-replicated SubModel, the part should be marked noerase to prevent any possibility of erasure. Background Rectangles with redraw 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 a non-replicated SubModel, this is not possible. Because of this, any part in a non-replicated SubModel which is animated must be explicitly forced to be redrawn using a redraw action. For example, submodel1 contains a Text Rectangle with the following dynamics description: * fcolor fcolor_var stext stext_var "%d" If submodel1 were to be used as a non-replicated SubModel, this dynamics description would have to be modified to include a redraw action: * fcolor fcolor_var stext stext_var "%d" redraw

Version 6.2a- 26 May 2006

SL-GMS Reference 11-17

Performance

The following information should be noted for non-replicated SubModels: · · · animated objects in a non-replicated SubModel should not be detectable. input dynamics (those specified with the "#" symbol) cannot be used in non-replicated SubModels. GraphTrace objects cannot be used in non-replicated SubModels; if a single non-replicated GraphTrace is shared among several Model Instances, the Model Instances will conflict with one another as they attempt to store data in the GraphTrace through the plotdata action software double buffering does not work correctly on individual parts within a non-replicated SubModel; the dbflag should not be set on these objects. only unconditional dynamics actions can be used within a non-replicated SubModel. replicated SubModels evaluate their dynamics descriptions during the execution of gmsDynUpdate( ), non-replicated SubModels defer the evaluation of dynamics descriptions until gmsUpdate( ) is executed.

·

· ·

Freeing unused SubModels

The function gmsModPermanent( ) is used to set or clear the permanent flag on a Model. By default, this flag is not set on a Model when it is created. The permanent flag affects only the behavior of Models which are SubModels. When the permanent flag is not set, a SubModel is freed when the last Model Instance referencing that SubModel is freed. This is done to prevent accumulation of SubModels in memory. Setting the permanent flag on a SubModel may improve performance. When the last Model Instance referencing a given SubModel is freed, that SubModel is freed. If another Model Instance is loaded or created and it references the same SubModel (by name), the SubModel must be reloaded from disk. When the permanent flag is set, performance is improved by retaining the SubModel in memory, instead of reloading the SubModel from disk.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-18

Performance

The permanent flag is typically set on a SubModel which is instanced in several top-level Models. This can decrease the amount of time needed to load a top-level Model because the SubModel will already be in memory. If the permanent flag is set on a SubModel, the SubModel can be freed only by explicitly calling gmsObjFree( ). The SubModel is not automatically freed when the last Model Instance referencing that SubModel is freed. Currently, the status of the permanent flag on a SubModel cannot be saved in a ".m1" or ".g" file. This means that the permanent flag must be set at run time. In order to set the permanent flag at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ). Individual SubModels are pre-loaded: id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1"); Selected SubModels are then marked "permanent": gmsModPermanent(submodel1, G_ON);

SubModel cache

Using a SubModel cache can improve the performance of an application which repeatedly creates and frees several Model Instances which refer to the same SubModel. The overhead required to replicate the SubModel and free the replicates is reduced. However, the application may consume more memory, since the replicates are no longer automatically freed with the Model Instances. Neither the SubModel cache capacity nor count attributes is saved in a ".m1" or ".g" file. These attributes must be set at run time. To set these attributes at run time, the SubModel must be pre-loaded using gmsMXGet( ) or gmsM2XGet( ): id submodel1; submodel1 = gmsMXGet("submodel1", "submodel1"); A SubModel cache is automatically destroyed when the original SubModel (the template for the replicates) is freed. The function gmsModPermanent( ) must be used to prevent submodel1 from being

Version 6.2a- 26 May 2006

SL-GMS Reference 11-19

Performance

automatically freed when the last Model Instance referencing submodel1 is freed: gmsModPermanent(submodel1, G_ON); The function gmsModCacheCapacity( ) is then called to set the capacity of the SubModel cache to a number smaller than or equal to the maximum number of replicates predicted to exist in memory. This number can be determined by computing or estimating the number of Model Instances which will be referencing submodel1 at the same time. The closer the cache capacity is to the actual number of replicates which will exist in memory, the greater the optimization. In this example, it has been determined that no more than 100 Model Instances will reference submodel1 at the same time: gmsModCacheCapacity(submodel1, 100); SubModel replication can be either batched or incremental. To batch SubModel replication, gmsModCacheCount( ) is called immediately after the gmsModCacheCapacity( ) call. This call will create 100 replicates of submodel1 and store them in the cache: gmsModCacheCount(submodel1, 100); To perform incremental SubModel replication, the application omits the gmsModCacheCount( ) call. As Model Instances referencing submodel1 are created or loaded from disk, replicates of submodel1 are created. The count of the SubModel cache will increase, but will never exceed the capacity. If the number of replicates needed is less than the capacity, the count will remain smaller than the capacity.

Version 6.2a- 26 May 2006

SL-GMS Reference 11-20

12

Introduction

The Graphical Modeling Language

SL-GML permits quick access to all libgms functions. As a complement to SL-GMSDraw, it is equally flexible in creating screens from Graphical Primitives and is sometimes indispensable for refining graphical Models, using a simple graphical description language. SL-GML interprets commands read from a file or entered at a keyboard. 1

SL-GMS

<gms> gml ready> model get cogen <gms> gml ready> immu <gms> gml ready> _ Cycle

Cogeneration Monitoring System

Reserve Pump 724.7 lit/min Pressure kg/cm 63.7 Heat loss 966.7 MW Steam Elec Power 682.5 Generator 29.85 Heat Transfer Primary Secondary Exchanger Reserve Power Output Demand Change Temp 129.0 'F Temp 78.0 'F Capacities Power Transfer Reserve

11

Output Power 998.5

446.3 880.4 0.6 58.9 273.0 983.0 360.8

Return Reserve Cap 927.7 Reserve Flow 764.1 lit/mn Temp 143.9 'F Exchng Input 8.8 N/Hr Primary Energy Flow 200.0 900.2 N/Hr lit/mn Return Energy Flow 418.1 581.3 N/Hr lit/mn

81.7 85.5 28.9

% % %

Reading % R Values

1 73.5 546.9

2 10.0 731.6

3 52.9 519.0

4 28.6 946.4

5 42.6 493.8

6 70.2 550.0

I IV

II III

P1 P4

P2 P3

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.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-1

The Graphical Modeling Language

In general, SL-GMSDraw is used for editing Model files. However, there are occasions when it is easier to convert a Model file to an SL-GML command file and use an editor on the command file; for example, to change a text string that appears in many places in a Model, or to change the color red to the color green wherever it occurs. Those are instances when making global changes with an editor is easier than editing the Models using a SL-GMS drawing editor. Once the command files have been changed, they must be reconverted to Model files using SL-GML. When errors are encountered while reading the command file with SL-GML, the line number where the error occurred is displayed. It is usually advisable to give the command file the same name as that of the Model it contains. The name of the command file has no effect on the name of the Model that is saved, rather the name that precedes the model command in the command file determines the name of the Model.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-2

The Graphical Modeling Language

Example

1. 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 and the Model is named "testmod.m1". 3. Click the File Pull-Down Menu and select the GML Script option of the Export submenu.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-3

The Graphical Modeling Language

4. The ASCII file "testmod.g" 2 can then be edited with a standard text editor: mtran0 vis 1 detect 1 testmod: model fcolor 4 fstyle 1 finter 1 fdir 0 fpercent 100 ecolor 7 estyle 1 ewidth 1 fcir2 50 37.5 50 45.5 endm 5. The Model can be examined or changed using the SL-GML interface by starting SL-GML as described in the section SL-GML command-line options of the SL-GMS Quick Reference and typing the following command at the <gml_ready> prompt:3

<gml_ready> < testmod.g

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.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-4

The Graphical Modeling Language

6. The Model can then be displayed by entering

<gml_ready> update

Converting Model files

SL-GML provides the portability medium for SL-GMS Models. SL-GML saves Model files in ".g" format and can convert ".g" files back to ".m1" (binary) files. SL-GML command files (".g" files) can always be transported between different computers. Steps to Port a Model File Between Different Computers Using SL-GML Functional Description

Start-up SL-GML on the source computer Read in the binary version of the Model Write out the ASCII version of the Model to a file

Steps

1. Invoke SL-GML per the Installation Notes on the source computer 2. Enter model get modelname 3. Enter modelname gsave The "modelname.g" command file is created. 4. Enter quit

Exit SL-GML

Version 6.2a- 26 May 2006

SL-GMS Reference 12-5

The Graphical Modeling Language

Steps to Port a Model File Between Different Computers Using SL-GML

(continued)

Functional Description

Transfer the SL-GML command files from the source computer to the destination computer Start-up SL-GML on the destination computer Read in the ASCII version of the Model

Steps

5. Use the appropriate system command(s) to copy or move the ".g" files from the source to the destination computer 6. Invoke SL-GML per Installation Notes on the destination computer 7. Enter <modelname.g The "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. 8. Enter modelname save The "modelname.m1" file is created. 9. Enter quit

Write out the binary version of the Model to a file

Exit SL-GML

NOTE: Converting Graph Models to ".g" format causes comments in the Graph template (".g" file) to be lost when the conversion is made. The m1g and gm1 scripts distributed in the bin directory perform the binary-to-ASCII and ASCII-to-binary conversions described above for a single or multiple Models.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-6

The Graphical Modeling Language

Projects

A Project is a collection of Views and their Models. Before SL-SMS evolved, Projects were used when multiple Views and Models were to be displayed in the same Workstation/Window. Although Projects can still be used to build an application without programming, it is recommended that SL-SMS be used to handle multiple Views and Models. More information about multiple Views is provided in the section Views on page 8-5. Normally, a Project is created and saved in a SL-GML command file (with the suffix ".p1"). The Project can then be loaded by an application program at startup.

Version 6.2a- 26 May 2006

SL-GMS Reference 12-7

A

Introduction

· · · · · ·

SL-GMS GISMO Library Reference

This appendix describes the following features of the GISMOs in the SL-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 supplied SL-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 names which begin with "f_"; and the Motif look, which begin with "m_". For convenience, these are referred to as "f" and "m" styles, respectively. The "f" style appears flat and is rectangular. It has a two-dimensional appearance. The variables associated with the fill, edge and text color, the text font, and the edge width are available as RenamedVars for each Instance of an "f" style GISMO. The size of the GISMO Instance can be changed by scaling. The "m" style GISMOs are three-dimensional Motif look-alikes. Their highlighting is fixed by the Motif standard. In addition to rectangular shapes,

Version 6.2a- 26 May 2006

SL-GMS Reference A-1

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 be edited to change the color/font, but it is saved as a different Model. The size of the GISMO Instance can be changed by scaling.

SL-GMS GISMO Library Model names Model Name Restrictions

For compatibility with all supported platforms, supplied library GISMOs have: · · · · file names characters; (including extension) not exceeding fourteen

GISMO Model names which are ten characters or less (allowing for 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 chosen from alphabetic, numeric, or underscore {A-Z, a-z, 0-9, _ }.

Model Naming Convention

The first part of the GISMO Model name relates to its appearance, while the second part (separated by an underscore "_") relates to its function. The "f" and "m" library GISMOs are named as shown below: s_ffffffxx and sg_ffffffx (10 characters maximum) (10 characters maximum)

Version 6.2a- 26 May 2006

SL-GMS Reference A-2

Naming Convention of the SL-GMS GISMO Library symbol s g example m_call ma_call definition STYLE index: "f" for "Flat" and "m" for "Motif" 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 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.)

xx and x m_quit_0

GISMO construction

This section describes how each GISMO in the SL-GMS GISMO Library is constructed and the use of the RenamedVars and Program Interface for each 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, the RenamedVars are conveniently subdivided into appearance RenamedVars and functionality RenamedVars. Virtually the same set of appearance RenamedVars applies to all GISMOs with the same look, regardless of what the GISMO actually does. These are summarized in tables at the

Version 6.2a- 26 May 2006

SL-GMS Reference A-3

end of this appendix. The functionality RenamedVars focus on what the GISMO does and are common to either style of GISMO appearance. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) Style "f" (flat) "m" (Motif look-alike)

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( )

Version 6.2a- 26 May 2006

SL-GMS Reference A-4

Functional Description: When the CALL GISMO is selected, it calls gms_flash( ) to set the value of the internal variable __button_hilite.1 This variable is used to highlight the GISMO. The style of highlighting is specified in the part of the appearance DynProp which tests for __button_hilite set to one (refer to page A-118). In addition, the CALL GISMO invokes the user-defined callback function. The calling syntax of the gms_flash( ) function is described on page A-84. The calling syntax of the gms_call( ) function is described on page A-81. Variables: The CALL GISMO is distributed in both "f" style (flat look) and "m" styles (Motif look-alike versions). Appearance RenamedVars Variable Name see Table Af (page A-110) f_call CALL GISMO

see Table Am (page A-111) m_call ma_call md_call ms_call Functionality RenamedVars Variable Name button_state callback Description renamed to an integer variable; provides highlight control renamed to the user callback function

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.

Version 6.2a- 26 May 2006

SL-GMS Reference A-5

Example RenamedVars

Sample RenamedVars for the m_call GISMO user-defined function called my_function: button_label :: "myfunction" button_state callback :: my_function edge_width :: 2 text_align_x :: 2 text_height :: 1.5 to call a

PROGRAM INTERFACE

The callback function must expect as an argument a pointer to an integer: int my_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 that my_function can be written in either C, FORTRAN, or Ada.

Version 6.2a- 26 May 2006

SL-GMS Reference A-6

The callback function my_function must be declared to SL-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( )

Functional Description: The DATSCREEN GISMO calls gms_flash( ) to set the value of the internal variable _ _button_hilite. This variable is used to

Version 6.2a- 26 May 2006

SL-GMS Reference A-7

highlight the GISMO. The style of highlighting is specified in the part of the appearance DynProp which tests for _ _button_hilite set to one (refer to page A-118). The gms_datscreen_state_invoke( ) function 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) if the reset_flag argument is 1, pushes a new datscreen state with a new Model (model_name) on the state stack, and adds the Model to the named View (view_name). If the clear_flag is 1, the current View is erased before displaying model_name. Setting the clear_flag variable to 0 prevents the current View from being cleared, and model_name is drawn over the existing Model(s). The calling syntax of the gms_flash( ) function is described on page A-84. The calling syntax of the gms_datscreen_state_invoke( ) function is described on page A-83. Variables: The DATSCREEN GISMO is distributed in both "f" style (flat look) and "m" style (Motif look-alike) versions. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) DATSCREEN GISMO f_dscrn m_dscrn md_dscrn ms_dscrn

Version 6.2a- 26 May 2006

SL-GMS Reference A-8

Functionality RenamedVars Variable Name button_state clear_flag Description renamed to an integer variable; provides highlight control renamed to an integer constant or variable; 1 = clear the View before displaying Model, 0 = do not clear the View before displaying Model renamed to a string constant; the Model that is to become visible once this GISMO is selected 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) renamed to a string constant; the View in which to display the specified Model

model_name reset_flag

view_name

Example RenamedVars

Suppose the following is required in an application: Clicking on a "GO TO SCREEN #1" button causes the current View to clear and a Model named screen1 to be displayed and animated with the data description contained in the file "screen1.dat". The RenamedVars that are required for a m_dscrn GISMO Instance 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-9

text_align_x :: 2 text_height :: 1.5 view_name :: "" Upon each update pass, the contents of the "screen1.dat" file are read until a blank line is encountered. If "screen1.dat" is not successfully opened, the datscreen State behaves just as the screen 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( )

Functional Description: The POPUP GISMO calls gms_flash( ) to set the value of the internal variable _ _button_hilite. This variable is used to highlight the GISMO. The style of highlighting is specified in the

Version 6.2a- 26 May 2006

SL-GMS Reference A-10

part of the appearance DynProp which tests for _ _button_hilite set to one (refer to page A-118). The gms_popup_state_invoke( ) function deactivates the current State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked state, it resets to the Top State) if the reset_flag argument is 1, pushes a new popup state with a new Model (model_name) on the state stack, and adds the Model to the named View (view_name). A popup state makes active a specified Model on top of existing Models, saving the obscured image in raster format for quick re-display when the popup state is deactivated. The POPUP GISMO 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 on page A-84. The calling syntax of the gms_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. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) POPUP GISMO f_popup m_popup ma_popup

Functionality RenamedVars Variable Name button_state Description renamed to an integer variable; provides highlight control

Version 6.2a- 26 May 2006

SL-GMS Reference A-11

Functionality RenamedVars

(continued)

Variable Name model_name reset_flag

Description renamed to a string constant; the Model that is to become visible once this GISMO is selected 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) renamed to a string constant; the View in which to display the specified Model

view_name

Example RenamedVars

Suppose the following is required in an application: Clicking on a "POP UP MENU #1" button causes a Model named popup1 to display on the screen over the existing Models in the View "v_main". The RenamedVars that are required for a m_popup GISMO Instance 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"

Version 6.2a- 26 May 2006

SL-GMS Reference A-12

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( )

Functional Description: The QUIT GISMO calls gms_flash( ) to set the value of the internal variable _ _button_hilite. This variable is used to highlight the GISMO. The style of highlighting is specified in the part of the appearance DynProp which tests for _ _button_hilite set to one (refer to page A-118). The gms_quit( ) function kills all processes created by SL-SMS and exits SL-GMS gracefully. The calling syntax of the gms_flash( ) function is described on page A-84. The calling syntax of the gms_quit( ) function is described on page A-94. Variables:

Version 6.2a- 26 May 2006

SL-GMS Reference A-13

The QUIT GISMO is distributed in both "f" style (flat look) and "m" style (Motif look-alike) versions. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) f_quit m_quit QUIT GISMO

Functionality RenamedVars Variable Name button_state Description renamed to an integer variable; provides highlight control

Example RenamedVars

Sample 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-14

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( ) and gms_state_pop( )

Functional Description: The RETURN GISMO calls gms_flash( ) to set the value of the internal variable _ _button_hilite. This variable is used to highlight the GISMO. The style of highlighting is specified in the part of the appearance DynProp which tests for _ _button_hilite set 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 it deactivates the current State by popping it from the SL-SMS internal State stack and returns control to the Superstate of the popup State.

Version 6.2a- 26 May 2006

SL-GMS Reference A-15

The calling syntax of the gms_flash( ) function is described on page 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. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) RETURN GISMO f_return m_return

Functionality RenamedVars Variable Name button_state Description renamed to an integer variable; provides highlight control

Example RenamedVars

Sample 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-16

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_screen_state_invoke( ) gms_flash( ) and

Functional Description: The SCREEN GISMO calls gms_flash( ) to set the value of the internal variable _ _button_hilite. This variable is used to highlight the GISMO. The style of highlighting is specified in the part of the appearance DynProp which tests for _ _button_hilite set to one (refer to page A-118). The gms_screen_state_invoke( ) function deactivates the current State and all SuperStates up to the last State Instance marked with the gmsStMark( ) function (if there is no marked state, it resets to the Top State) if the reset_flag argument is set to 1; pushes a new screen state with a new Model (model_name) on the state stack; adds the Model to the named

Version 6.2a- 26 May 2006

SL-GMS Reference A-17

View (view_name); and sets the popflag off and the freeflag on. If the clear_flag is 1, the current View is erased before displaying model_name. Setting the clear_flag variable to 0 prevents the current View from being cleared, and model_name is drawn over existing Model(s). The calling syntax of the gms_flash( ) function is described on page A-84. The calling syntax of the gms_screen_state_invoke( ) function is described on page A-97. Variables: The SCREEN GISMO is distributed in both "f" style (flat look) and "m" style (Motif look-alike) versions. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) f_scrn m_scrn md_scrn ms_scrn SCREEN GISMO

Functionality RenamedVars Variable Name button_state clear_flag Description renamed to an integer variable; provides highlight control renamed to an integer constant or variable; 1 = clear the View before displaying Model, 0 = do not clear the View before displaying Model renamed to a string constant; the Model that is to become visible once this GISMO is selected

model_name

Version 6.2a- 26 May 2006

SL-GMS Reference A-18

Functionality RenamedVars

(continued)

Variable Name reset_flag

Description 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) renamed to a string constant; the View in which to display the specified Model

view_name

Example RenamedVars

Suppose the following is required in an application: Clicking on a "GO TO SCREEN #2" button causes the current View to clear and a Model named screen2 to be displayed. The RenamedVars that are required for a m_scrn GISMO Instance 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 :: ""

Version 6.2a- 26 May 2006

SL-GMS Reference A-19

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( ) Functional Description: The STATE GISMO calls the gms_stayon( ) function to set the value of the internal variable __ button_hilite. This variable is used to highlight the GISMO. The style of highlighting is specified 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 of the State class class_name and installs it in the State Management Hierarchy. The other arguments set the various State Instance attributes as described in the SL-GMS® State Class Library Reference. The reset_flag, if set to 1, deactivates the event State (that State in which an event occurred). States are then de-activated starting at the event State and in order up the State tree until a marked State is encountered and then the

Version 6.2a- 26 May 2006

SL-GMS Reference A-20

newly-created State Instance is installed as a SubState. If there is no marked state, it resets to the Top State. The calling syntax of the gms_stayon( ) function is described on page 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. Appearance RenamedVars Variable Name see Table Af (page A-110) see Table Am (page A-111) f_state m_state md_state ms_state STATE GISMO

Functionality RenamedVars Variable Name button_state class_name clear_flag Description renamed to an integer variable; provides highlight control renamed to a string constant or variable; the name of the State class to invoke 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 renamed to an integer constant or variable; 1 = open and read data from "model_name.dat" file, 0 = do not open a ".dat" file renamed to a string constant or variable; the Model to display

dat_flag

model_name

Version 6.2a- 26 May 2006

SL-GMS Reference A-21

Functionality RenamedVars

(continued)

Variable Name pop_flag reset_flag

Description renamed to an integer constant or variable; the State popflag value 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) renamed to a string constant; the View in which to display the specified Model

view_name

Example RenamedVars

Sample RenamedVars for an Instance of the m_state GISMO to create a button with the label "MYSTATE" that invokes a State of the mystate State class with the "mystate" Model displayed on top 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 INTERFACE

This is an example of an initialize function -- a function that defines a customized State. In this case a new State class called mystate is created with the gmsStateClass( ) function. The function gmsClassAddMethod( ) is called to designate the methods defined for the mystate class. After the State class methods are defined, gmsStClassInstall( ) is called to install the new State class. The State class can be defined only once. The SL-GMS® State Class Library Reference provides additional

Version 6.2a- 26 May 2006

SL-GMS Reference A-22

information about initialization functions and activate, deactivate, and update functions. An initialization function must be written for each of the different customized States invoked by the renaming of the class_name variable. /* STATE INITIALIZE FUNCTION */ int mystate_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; }

Version 6.2a- 26 May 2006

SL-GMS Reference A-23

BUTTON GROUP

A GISMO BUTTON GROUP is a group of toggle buttons or other objects cooperating with each other in a prescribed manner. Toggle buttons come in 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 one time

Any set of objects can be grouped together to create a toggle group with either radio or check button behavior. Several "m" style GISMO models are 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" and grouping them together to produce RADIO and CHECK GISMOs.

Version 6.2a- 26 May 2006

SL-GMS Reference A-24

RADIO GISMOs

3 "GISMO helpers" grouped together

1 2 3

A B C

radio3 (with "A" selected)

Description: manipulate a variable from 0 to 1 to produce "radio" highlighting (only one GISMO element highlighted at a time) 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: #

Version 6.2a- 26 May 2006

SL-GMS Reference A-25

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: # call gms_radio_var(callback,&indexvar, 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: # call gms_radio_var(callback,&indexvar, 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)

Version 6.2a- 26 May 2006

SL-GMS Reference A-26

The index-controlled RADIO GISMO Model DynProp with "flip" highlighting style is: # call gms_radio_var(callback,&indexvar, 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( )

Functional Description: The RADIO GISMO can be controlled by either an array variable in which at maximum only one element at a time is set to 1, or by an index variable which indexes the GISMO part currently selected. A RADIO GISMO controlled by an array variable, when selected, calls gms_radio_array( ) to set the elements of the variable arrayvar to 1 ("selected") and 0 ("unselected") appropriately and to optionally invoke a user function. A RADIO GISMO controlled by an index variable, when selected, calls gms_radio_var( ) to set the variable indexvar to the index of the selected part (indexvar will be set to -1 if none of the radio buttons are selected) and to optionally invoke a user function. A special parameter called always_on set to 1, indicates that at least one radio button must remain on. In addition, radio buttons are selected (or unselected) either by a loc_release Event (pressing and releasing the mouse button) or a loc_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 at the same time, one does not have to remain on.

Version 6.2a- 26 May 2006

SL-GMS Reference A-27

If the callback variable is renamed, the user-defined function is invoked and passed the index of the selected object, along with the value set for the variable. Highlighting is accomplished via the gms_hilite_*( ) functions. Each highlighting style has two gms_hilite_*( ) functions: one function expects an array variable with elements set to 1 (highlight) or 0 (unhighlight) and one function expects an index variable set to non-0 (highlight) or 0 (unhighlight). For example, the "edge" style highlighting functions available are: 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 page A-94. The calling syntax of the gms_radio_var( ) function is described on page A-95. The calling syntax of the gms_hilite_color( ) function is described on page A-85. The calling syntax of the gms_hilite_color_var( ) function is described on page A-86. The calling syntax of the gms_hilite_edge( ) function is described on page A-87. The calling syntax of the gms_hilite_edge_var( ) function is described on page A-88. The calling 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 on page A-92. The calling syntax of the gms_hilite_flip( ) function is described 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. for the radio3 GISMO are: Variables

Version 6.2a- 26 May 2006

SL-GMS Reference A-28

Variables radio3 Variable Name always_on Description 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 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 renamed to the user callback function (without quotation marks); renaming is optional renamed to an integer constant or variable; the highlight color renamed to an double constant or variable; the highlight edge width renamed to an integer constant or variable; the unhighlight color renamed to an double constant or variable; the unhighlight edge width

arrayvar

callback hc hw uc uw

Example RenamedVars

Sample RenamedVars for an instance of the radio3 GISMO driven by the array variable my_array and calling the user-defined callback function my_function; one of the elements of the GISMO is always highlighted; the GISMO uses an "edge"

Version 6.2a- 26 May 2006

SL-GMS Reference A-29

highlighting style with an edge color of 5 and edge width of 3 for highlighted and an edge color of 7 and an edge width of 1 for unhighlighted: always_on :: 1 arrayvar :: my_array callback :: my_function hc :: 5 hw :: 3. uc :: 7 uw :: 1. arrayvar must be renamed. When arrayvar is renamed, the value of arrayvar's elements are changed directly in memory in response to the input event. If both arrayvar and callback are renamed, the value of arrayvar's elements is changed directly in memory and the callback function is then invoked. The callback function might perform some error checking, change the value of arrayvar's elements further, or perform a function based upon the radio button selected (or unselected). Sample RenamedVars for a RADIO GISMO driven by the index variable my_variable and calling the user-defined callback function my_function; one of the elements of the GISMO is always highlighted; the GISMO uses an "edge" highlighting style with an edge color of 5 and edge width of 3 for highlighted and an edge color of 7 and an edge width of 1 for unhighlighted: always_on :: 1 callback :: my_function hc :: 5 hw :: 3. indexvar :: my_variable uc :: 7 uw :: 1. indexvar must be renamed. When indexvar is renamed, the value of indexvar is changed directly in memory in response to the input event. If both indexvar and callback are renamed, the value of indexvar is changed directly in memory and the

Version 6.2a- 26 May 2006 SL-GMS Reference A-30

callback function is then invoked. The callback function might perform some error checking, change the value indexvar further, or perform a function based upon the radio button selected (or unselected).

PROGRAM INTERFACE

The callback function must expect as arguments two pointers to an integer. int my_function (partindex, value) int *partindex;/* index of GISMO part picked or -1(when always_on is 1, the loc_motion method is used for button selection, and the mouse cursor is not on one of the objects in 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 driven by an index variable*/ { /* this is a dummy statement; actual function code belongs here... */ printf("*partindex = %d; *value = %d\n", *partindex, *value); return 1; } NOTE: partindex and value are pointers (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call:

Version 6.2a- 26 May 2006

SL-GMS Reference A-31

. . 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) and optionally call an application callback

DynProps for functionality and appearance: Sample GISMO Model DynProps with varied highlighting styles are shown below. The call to gms_toggle_array( ) provides the functionality. The second call in each of the DynProps: gms_hilite_color( ), gms_hilite_edge( ), . . . controls the highlighting appearance of the GISMO.

Version 6.2a- 26 May 2006

SL-GMS Reference A-32

The CHECK GISMO Model DynProp with "fill" highlighting style is: # call gms_toggle_array(callback, &arrayvar) * call gms_hilite_color(&arrayvar, hicolor, uncolor) The CHECK GISMO Model DynProp with "edge" highlighting style is: # call gms_toggle_array(callback, &arrayvar) * call gms_hilite_edge(&arrayvar, hicolor,uncolor, hiwidth, unwidth The CHECK GISMO Model DynProp with "vis" highlighting style is: # call gms_toggle_array(callback, &arrayvar) * call gms_hilite_vis(&arrayvar) The CHECK GISMO Model DynProp with "flip" highlighting style is: # call gms_toggle_array(callback, &arrayvar) * call gms_hilite_flip(&arrayvar) GISMO action functions: gms_toggle_array( ), gms_hilite_color( ), gms_hilite_vis( ), gms_hilite_flip( ), and gms_hilite_edge( )

Version 6.2a- 26 May 2006

SL-GMS Reference A-33

Functional Description: The CHECK GISMO is controlled by an array variable in which appropriate elements are set to 1 for "selected" and 0 for "not selected." A CHECK GISMO, when selected, calls gms_toggle_array( ) to set the elements of an array variable, arrayvar, to 1 and 0 appropriately and to invoke a user function if the 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 variable with elements set to 1 (highlight) or 0 (unhighlight) are used in the DynProps for the CHECK GISMO. The calling syntax of the gms_toggle_array( ) function is described on page A-106. The calling syntax of the gms_hilite_edge( ) function is described on page A-87. The calling syntax of the gms_hilite_color( ) function is described on page A-85. The calling syntax of the gms_hilite_flip( ) function is described on page A-88. The calling syntax of the gms_hilite_vis( ) function is described on page A-91.

Variables: Variables for the toggle3 GISMO are: Variables toggle3 Variable Name arrayvar Description 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-34

Variables toggle3

(continued)

Variable Name callback

Description renamed to the user callback function (without quotation marks); renaming is optional renamed to an integer constant or variable; the highlight color renamed to an double constant or variable; the highlight edge width renamed to an integer constant or variable; the unhighlight color renamed to an double constant or variable; the unhighlight edge width

hc hw uc uw

Example RenamedVars

(the CHECK GISMO in this example uses "flip" highlighting) Sample RenamedVars for the CHECK GISMO are: arrayvar :: my_array callback :: my_function arrayvar must be renamed. When arrayvar is renamed, the value of arrayvar's elements is changed directly in memory in response to the input event. If both arrayvar and callback are renamed, the value of arrayvar's elements is changed directly in memory and the callback function is then invoked. The callback function might perform some error checking, change the value of arrayvar's elements further, or perform a function based upon the check button(s) selected (or unselected).

Version 6.2a- 26 May 2006

SL-GMS Reference A-35

PROGRAM INTERFACE

The callback function must expect as arguments two pointers to integer: int my_function (partindex, value) int *partindex;/* index of GISMO part picked */ int *value; /* value of arrayvar[partindex]; either 0 ("unselected") or 1 ("selected")*/ { /* this is a dummy statement; actual function code belongs here... */ printf("*partindex = %d; *value = %d\n", *partindex, *value); return 1; } NOTE: partindex and value are pointers (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call: . . int my_arg2p[] = {G_POINTER, G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 2, my_arg2p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-36

SPECIAL PURPOSE CYCLE GISMOs

Description: manipulates a variable cycled through a set of values from 0 to "n-1" where "n" is equivalent to the number of objects contained in the Model or Group to which the DynProp shown 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( ) Functional Description: The CYCLE GISMO, when selected, calls the function gms_cycle_var( ) to cycle the value of variable based upon the number of parts in the selected object. The gms_cycle_var( ) function cycles the value of variable from 0 to "n-1" where "n" is equivalent to the number of objects contained in the Model or Group to which the DynProp containing this function is attached. In addition, if the callback variable has been renamed, the user-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 using visibility. The object whose part index is the same as the value of variable is made visible. Other objects in the part (which could be a Group) are made invisible. If variable is -1, all objects in the part or Group are made invisible.

Version 6.2a- 26 May 2006

SL-GMS Reference A-37

The calling syntax of the gms_cycle_var( ) function is described on 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: Variables cycle1 and cycle2 Variable Name callback Description renamed to the user callback function (without quotation marks); renaming is optional 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

variable

Example RenamedVars

callback (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, the value of the renamed variable (my_variable in the first example above) is changed directly in memory in response to the input event. If both variable and callback are renamed, as in the second example, the value of the renamed variable my_variable is changed directly in memory, and the my_function callback function is then invoked. The callback function might perform

Version 6.2a- 26 May 2006

SL-GMS Reference A-38

some error checking, change the value of my_variable further, or perform a function based upon the value of my_variable.

PROGRAM INTERFACE

The callback function must expect as arguments two pointers to integer. int my_function (value, on) int *value; /* value of the index of GISMO part picked (zero relative) */ int *on; /* always = 1; meaning that this part of the GISMO is on */ { /* this is a dummy statement; actual function 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 that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call: . . int my_arg2p[] = {G_POINTER, G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 2, my_arg2p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-39

FILL-PERCENT GISMOs

Description: manipulates a variable through a range of values between a maximum and a minimum and optionally calls an application 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 of the Model) used to control appearance in the f_fill GISMO. They are: * fcolor background_color * ecolor fill_color fcolor fill_color The m_fill GISMO has the following DynProp for appearance:

Version 6.2a- 26 May 2006

SL-GMS Reference A-40

fill_color = * fcolor fill_color ecolor fill_color GISMO action functions: gms_hilite_fpercent1( ) gms_fpercent_var1( ) and

Functional Description: When selected, the FILL PERCENT GISMO calls gms_fpercent_var1( ) to set the value of var between min and max. If the callback variable is renamed, the user-defined function is invoked and passed the value of the percentage index. The value of the percentage index is equal to min when the Filled Rectangle is empty, the value of max when 100 percent full, or some value in between min and max when filled to some other percentage. The fill-percent of a Rectangle is changed to reflect the percentage of the value of the variable var in relation to min and max by calling the gms_hilite_fpercent1( ) function. The DynProp shown above is attached to a Model or Group containing two or more objects. The first part is the background object, which is redrawn whenever the fill-percent object is clicked. The second part is the object itself, whose fill-percent is changed to represent the value of the variable var as a percentage between the minimum (the variable min) and maximum (the variable max). The calling syntax of the gms_fpercent_var1( ) function is described on page A-85. The calling syntax of the gms_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_fill and the m_fill GISMO are:

Version 6.2a- 26 May 2006

SL-GMS Reference A-41

Variables f_fill and m_fill Variable Name background_color callback Description (f_fill only) renamed to an integer constant or variable renamed to the user callback function (without quotation marks); renaming is optional renamed to an integer constant or variable; the fill color renamed to a double constant or variable; the maximum value in the range of valid values for var renamed to a double constant or variable; the minimum value in the range of valid values for var renamed to the variable which drives the GISMO

fill_color max

min

var

EXAMPLE RenamedVars

Sample RenamedVars for an m_fill GISMO to fill between the values of 0.0 and 1000.0, based upon the value of the variable my_variable, using color 14 as a fill color, and to call the my_function callback: callback :: my_function fill_color :: 14 max :: 1000.0 min :: 0.0 var :: my_variable var must be renamed. When var is renamed, the value of the renamed variable (my_variable in the example above) is changed directly in memory in response to the input event. If

Version 6.2a- 26 May 2006

SL-GMS Reference A-42

the callback variable is renamed, the callback function (my_function in the example above) is then invoked. The callback function might perform some error checking, change the value of my_variable further, or perform a function based upon the value of my_variable.

PROGRAM INTERFACE

The callback function must expect as an argument a pointer to a double. int my_function (value) double *value;/* value of relative position of rectangle fill in range of minvalue to maxvalue */ { /* this is a dummy statement; actual function code belongs here... */ printf("*value = %g\n", *value); return 1; }

NOTE: value is a pointer (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call: . . int my_arg1p[] = {G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 1, my_arg1p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-43

SCROLLBOX GISMOs

Description: scroll lines of text; m_sboxs allows selection of a single line of text and m_sboxm allows selection of multiple lines; optionally call user function(s) upon scrolling and/or selection DynProps: Functionality: The m_sboxs and m_sboxm GISMOs are built as several Local SubModels within a Model. Each of the different Local SubModels (m_slider, m_uparrow, m_downarrow and m_textscroll) has a DynProp attached to it that determines its functionality. The Local SubModels are listed below with their associated DynProps. The only difference in the DynProps for the single (m_sboxs) and multiple (m_sboxm) selection scrollboxes appears in the m_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)

Version 6.2a- 26 May 2006

SL-GMS Reference A-44

* 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)

Version 6.2a- 26 May 2006

SL-GMS Reference A-45

# call gms_togglescroll_array(callback_select, &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) 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( )

Functional Description: The gms_text_array_slider_var( ) function responds to a locator press on the slider and sets the variable cursor_index to the index in the string array of the first line in the scrollbox. If the callback_slider variable is renamed, the user-defined callback function is invoked and passed the address of cursor_index. The gms_text_array_slider_hilite( ) function moves the 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 percentage of the string array which is displayed in the scrollbox window. The gms_textscroll_lines( ) function is used to scroll through an array of strings displayed in a Group of Text Rectangle objects either 1 or -1 lines at a time. The gms_radioscroll_var( ) sets the value of hilite_index in response to a locator Event. hilite_index, can be thought of as

Version 6.2a- 26 May 2006

SL-GMS Reference A-46

an index (offset) into the array of strings. It is the index of the string in an array of strings that is highlighted when it is displayed in a scrollbox. The gms_hilitescroll_var( ) function highlights one member of a Group of Text Rectangles. The index of member highlighted is determined, as follows: part-index = hilite_index ­ cursor_index All other members of the Group are unhighlighted. The gms_togglescroll_array( ) function sets array element values in hilite_array based upon which Text Rectangle was clicked with the mouse. hilite_array is an array of integers that specifies which lines of the array are highlighted. An array element with a value of 1 indicates a highlighted line of text. The gms_hilitescroll_array( ) function is used to highlight selected lines of text. The gms_textscroll_array( ) function is used to load a Group of Text Rectangle objects with strings from an array. The calling syntax of the gms_flash( ) function is described on page A-84. The calling syntax of the gms_textscroll_lines( ) function is described on page A-105. The calling syntax of the gms_text_array_slider_var( ) function is described on page A-101. The calling syntax of the gms_radioscroll_var( ) function is described on page A-96. The calling syntax of the gms_hilitescroll_var( ) function is described on page A-93. The calling syntax of the gms_togglescroll_array( ) function is described on page A-106. The calling syntax of the gms_text_array_slider_hilite( ) function is described on page A-101. The calling syntax of the gms_hilitescroll_array( ) function is described on page A-92. The calling syntax of the gms_textscroll_array( ) function is described on page A-104.

Version 6.2a- 26 May 2006

SL-GMS Reference A-47

Variables: Functionality RenamedVars for m_sboxs and m_sboxm Variable Name callback_select Description renamed to the user callback function (without quotation marks) for gms_radioscroll_var( )(m_sboxs only) and gms_togglescroll_array( ) (m_sboxm only) renamed to the user callback function (without quotation marks) for gms_text_array_slider_var( ) renamed to an integer variable; the offset into string_array renamed to an integer constant or variable; the highlight color for the currently-selected line (m_sboxs) or lines (m_sboxm) in the scrollbox renamed to an integer variable; index of the first element in string_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 (m_sboxs only) renamed to an integer variable; offset into string_array of highlighted object renamed to an integer variable; index of the last element in string_array renamed to an integer constant or variable; maximum characters per line renamed to an integer constant or variable; the number of Text Rectangles in the Group that makes up the scrollbox

callback_slider

cursor_index hc

first_index hilite_array

hilite_index last_index scrollbox_chars scrollbox_lines

Version 6.2a- 26 May 2006

SL-GMS Reference A-48

Functionality RenamedVars for m_sboxs and m_sboxm

(continued)

Variable Name string_array string_array_loade d uc

Description renamed to an array of strings; the data displayed in the scrollbox renamed to an integer variable; causes the Text Rectangles in the scrollbox to be loaded from string_array when set to 1 renamed to an integer constant or variable; the normal color for lines in 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-49

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 INTERFACE

The callback_select callback function, for both the gms_radioscroll_var( ) and gms_togglescroll_array( ) functions, must expect as arguments two pointers to an integer and one pointer to an id. The value parameter passed from the gms_radioscroll_var( ) (m_sboxs GISMO) and the gms_togglescroll_array( ) (m_sboxm GISMO) functions is different. The other parameters are identical. int my_function_select (part_index, value, picked_part) int *part_index; /* which of the Filled Text Rectangles in the Group was clicked on; valid values are 0 to (scrollbox_lines - 1) */ int *value; /* for m_sboxs: line number within string_array that is currently highlighted; valid values are first_index to last_index; for m_sboxm: 1 = highlighted, 0 = unhighlighted */ id *picked_part; /* id of Filled Text Rectangle that was clicked on */ { /* this is a dummy statement; actual function code belongs here... */

Version 6.2a- 26 May 2006

SL-GMS Reference A-50

printf("*part_index = %d; *value = %d\n", *part_index, *arrayindex); return 1; } The callback_slider function must expect as an argument a pointer to integer: int my_function_slider (cursorindex) int *cursorindex;/* index in string_array of first line displayed in scrollbox */ { /* this is a dummy statement; actual function 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 and my_function_slider can be written in either C, FORTRAN, or Ada. The callback functions my_function_slider and my_function_select must be declared to SL-GMS with the gmsAddUserFctn( ) 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);

Version 6.2a- 26 May 2006

SL-GMS Reference A-51

gmsAddUserFctn("my_function_select", my_function_select,G_INTEGER, 3, my_arg3p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-52

Scrolling functions

The SL-GMS GISMO Action Functions which provide scrolling are designed to be used for scrolling menus containing lines of text. Examples of the use of the scrolling functions (and scrollbox GISMOs) can be found in the gismos subdirectory of the demo directory. The function in the library that actually does the scrolling is gms_textscroll_array( ). The other functions that affect the scrollbox work by changing the value of the cursor_index variable. The cursor_index variable represents an offset into the string_array -- in other words, string_array[cursor_index] is the first line of text displayed in the scrollbox window. For instance, the gms_textscroll_lines( ) function increments cursor_index by numlines, and then calls gmsVarChanged( ) on cursor_index. When SL-GMS is notified that cursor_index has changed, the gms_textscroll_array( ) function is activated and scrolls the text in the scrollbox. Two functions for manipulating the scrollbox with a slider GISMO also exist: 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 described above, these functions work by changing the value of cursor_index. The functions also change the size of the slider rectangle to reflect the percentage of the file that is being viewed in the scrollbox. In addition to the scrolling behavior, the scrollbox itself can respond to mouse clicks in two different ways: radio behavior and check behavior. The gms_radioscroll_var( ) and gms_hilitescroll_var( ) functions are used in conjunction to provide radio-highlighting behavior. When a line of text is clicked, it is highlighted. If it is clicked again it is unhighlighted. If another line of text is clicked, the first line is unhighlighted and the new line is highlighted. The gms_togglescroll_array( ) and gms_hilitescroll_array( ) functions are used to highlight one or more lines of text in a scrollbox. The hilite_array variable is an array of integers that contains the information that determines which lines of the array are highlighted. The gms_togglescroll_array( ) function sets array element values to 1 if the line is highlighted and 0 if it is not. The gms_hilitescroll_array( ) function

Version 6.2a- 26 May 2006

SL-GMS Reference A-53

reads the values in the hilite_array and highlights the correct lines of text in the scrollbox.

Example

The three dynamic action functions in the DynProp below are used to load a Group of Text Rectangles from an array of strings (gms_textscroll_array( )), and to provide scrolling, highlighting, and toggling behavior for each line of text. The Text Rectangles are created with empty strings; they are loaded later when the gms_textscroll_array( ) function is called. // Part of a scrollbox with check behavior textlines: 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 described on page A-106. The calling syntax for the gms_hilitescroll_array( ) function is described on page A-92. The calling syntax of the gms_textscroll_array( ) function is described on page A-104. SCROLLBOX GISMOs are described in greater detail starting on page A-44.

Version 6.2a- 26 May 2006

SL-GMS Reference A-54

SLIDER GISMOs

Description: manipulate a variable through a range of values between a minimum and a maximum and optionally call an application callback

DynProps for functionality: The SLIDER GISMO Model DynProp which performs a move operation (move part of the GISMO within a minimum and a maximum) 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 replace points operation (move a part of the GISMO within a minimum and a maximum and the capability to change the size of the moving part) and calls a user function is: # call gms_slider_var1(callback, &var, min, max) * call gms_hilite_percent2(&var1, &var2, min, max)

Version 6.2a- 26 May 2006

SL-GMS Reference A-55

GISMO action function: gms_slider_var1( gms_hilite_percent1( ), and gms_hilite_percent2( )

),

Functional Description: When selected, the SLIDER GISMO calls gms_slider_var1( ) to set the value of a variable between a minimum and maximum. A part of the GISMO object may be moved between two other scale-defining objects. The position of the moving element represents 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 with the location of the slider. A DynProp describing slider behavior is applied to a Model or Group containing four or more objects. The first is the background object, which is redrawn whenever the slider is clicked. The second object is the slider itself, which may be positioned to represent the value of a single variable, or may have its Points transformed to represent the value of two variables. The scale is implied between Reference Points located by the third and fourth objects. The calling syntax of the gms_slider_var1( ) function is described on page A-98. The calling syntax of the gms_hilite_percent1( ) function is described on page A-90. The calling syntax of the gms_hilite_percent2( ) function is described on page A-91.

Variables: The SLIDER GISMO is distributed in both "flat" (f_slide) and Motif look-alike versions (m_slideh, and m_slidev). The variables for the f_slide, m_slideh (horizontal) and m_slidev (vertical) GISMOs are:

Version 6.2a- 26 May 2006

SL-GMS Reference A-56

Variables f_slide m_slideh m_slidev Variable Name callback max Description renamed to the user callback function (without quotation marks); renaming is optional renamed to double constant or variable; the maximum value in the range of valid values for var renamed to double constant or variable; the minimum value in the range of valid values for var renamed to the variable which drives the GISMO

min

var

The f_slide, m_slideh, and m_slidev GISMOs are all implementations of a Model DynProp that performs a move operation. They call the gms_slider_var1( ) and gms_hilite_percent1( ) functions. For this type of Model DynProp, renaming the callback variable is optional. If a SLIDER GISMO is created using the Model DynProp which performs a replace points operation (using the gms_slider_var1( ) and the gms_hilite_percent2( ) functions), the callback variable must be renamed and it must set the value of var1 and var2 so that 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: callback :: my_function max :: 1000.0

Version 6.2a- 26 May 2006

SL-GMS Reference A-57

min :: 0.0 var :: my_variable

PROGRAM INTERFACE

The callback function must expect as an argument a pointer to a double: int my_function (value) double *value;/* value of variable; relative position of GISMO part picked in range of min to max */ { /* this is a dummy statement; actual function code belongs here... */ printf("*value = %g\n", *value); /* update dynamics and display */ gmsDynUpdate(nil); gmsUpdate(nil); return 1; }

NOTE: value is a pointer (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call: . . int my_arg1p[] = {G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 1, my_arg1p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-58

TEXTENTRY ARRAY GISMOs

Description: call an application callback function with individual fields 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)

Version 6.2a- 26 May 2006

SL-GMS Reference A-59

GISMO action functions: gms_textentry_array( ), gms_textload_array( ), gms_hilite_edge_selobj( ), and gms_hilite_color_selobj( )

Functional Description: The TEXTENTRY ARRAY GISMO can be a Model or Group of Text or Text Rectangle objects whose contents are controlled by an array variable, arrayvar, and whose highlighting is controlled by the _ _selected_object variable. Upon a string event, gms_textentry_array( ) copies the text string from the index part within the Model or Group into the indexed element in the array. The _ _selected_object variable is used by the SL-GMS event handler to determine which object is 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 the echoing object and places it into the variable provided as an argument. The __selected_object variable is also used by the gms_hilite_edge_selobj( ) and gms_hilite_color_selobj( ) functions to hilite the selected GISMO. The calling syntax of the gms_textentry_array( ) function is described on page A-102. The calling syntax of the gms_textload_array( ) function is described on page A-104. The calling syntax of the gms_hilite_edge_selobj( ) function is described on page A-88. The calling syntax of the gms_hilite_color_selobj( ) function is described on page A-86.

Variables: Variables for a TEXTENTRY ARRAY GISMO are:

Version 6.2a- 26 May 2006

SL-GMS Reference A-60

Variables TextEntry Array GISMO Variable Name array_type Description 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) renamed to the array variable which the text represents renamed to the user callback function (without quotation marks); renaming is optional renamed to an integer constant or variable; the highlight color renamed to an double constant or variable; the highlight edge width renamed to an integer constant or variable; the maximum number of characters allowed for input 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) renamed to an integer constant or variable; the unhighlight color renamed to an double constant or variable; the unhighlight edge width

arrayvar callback hc hw maxchars type

uc uw

Basic SL-GMS Data Types (defined in the file "gmscodes.h" distributed in the lib subdirectory) valid for the TEXTENTRY ARRAY GISMO are:

Version 6.2a- 26 May 2006

SL-GMS Reference A-61

Basic SL-GMS Data Types Valid for the TEXTENTRY ARRAY GISMO Decimal Value 2 8 256

Data Type G_INTEGER G_DOUBLE G_STRING

Description integer double

Hex Value 0x2 0x8

pointer to pointer to a 0x100 null-terminated string

Basic SL-GMS Array Types Valid for the TEXTENTRY ARRAY GISMO Decimal Value 2 8 16

Array Types G_INTEGER G_DOUBLE G_CHAR

Description integer double

Hex Value 0x2 0x8

pointer to pointer to a 0x10 null-terminated string

Example RenamedVars

Sample RenamedVars for a TEXTENTRY ARRAY GISMO to allow input of an integer (maximum of 10 characters); call the my_function callback and set the variable my_variable:

(integer) array_type :: 2 arrayvar :: my_variable callback :: my_function hc ::7 hw :: 3. maxchars :: 10

Version 6.2a- 26 May 2006

SL-GMS Reference A-62

type :: 2 uc ::15 uw ::1.

(integer)

Sample RenamedVars for a TEXTENTRY ARRAY GISMO to allow input of a double (maximum of 10 characters); call the my_function callback and set the variable my_variable: array_type :: 8 (double) arrayvar :: my_variable callback :: my_function hc ::7 hw :: 3. maxchars :: 10 (double) type :: 8 uc ::15 uw ::1. Sample RenamedVars for a TEXTENTRY ARRAY GISMO to allow input of a string (maximum of 10 characters); call the my_function callback and set the variable my_variable:

(string) array_type :: 16 arrayvar :: my_variable callback :: my_function hc ::7 hw :: 3. maxchars :: 10 (string) type :: 256 uc ::15 uw ::1.

PROGRAM INTERFACE

If type is 2 (integer) the callback function must expect as an argument a pointer to a pointer to the object selected and a pointer to an integer: int

Version 6.2a- 26 May 2006

SL-GMS Reference A-63

my_function (obj, i) id *obj; int *i; { /* this is a dummy statement; actual function code belongs here... */ printf("*obj = %x, *i = %d\n",*obj, *i); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,""); /* include this statement to deactivate/unhighlight upon end of string 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 an argument a pointer to a pointer to the object selected and a pointer to a double: int my_function (obj, d) id *obj; double *d; { /* this is a dummy statement; actual function code belongs here... */ printf("*obj = %x, *d = %g\n",*obj, *d); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,""); /* pointer to a pointer to GISMO part picked */ /* double value entered */ /* pointer to pointer to GISMO part picked */ /* integer value entered */

Version 6.2a- 26 May 2006

SL-GMS Reference A-64

/* include this statement to deactivate/unhighlight upon end of string entry, i.e., with the <RETURN> key */ gmsStTextEditObj(gmsQStEvState( ), nil,0,"","", 0); return 1; } If type is 256 (string) the callback function must expect as an argument a pointer to a pointer to the object selected and a pointer to a pointer to char: int my_function (obj, s) id *obj; char **s; { /* this is a dummy statement; actual function code belongs here... */ printf("*obj = %x, *s = %s\n",*obj, *s); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,""); /* include this statement to deactivate/unhighlight upon end of string entry, i.e., with the <RETURN> key */ gmsStTextEditObj(gmsQStEvState( ), nil,0,"","", 0); return 1; } NOTE: obj, i, d, and s are pointers (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. /* pointer to pointer to GISMO part picked */ /* string entered */

Version 6.2a- 26 May 2006

SL-GMS Reference A-65

By default, the TEXTENTRY ARRAY GISMO is selected (activated and highlighted) by clicking on it with the mouse and unselected when another TEXTENTRY ARRAY GISMO is selected. To have the TEXTENTRY ARRAY GISMO deactivate and unhighlight upon termination of string entry, that is, via the <RETURN> key, the gmsStTextEditObj( ) function call is included in the user callback function. Regardless of type the callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call as follows: . . int my_arg2p[] = {G_POINTER, G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 2, my_arg2p); In the code fragment above, my_arg2p[ ] is exactly the same for each type because the arguments to my_function are always pointers.

Version 6.2a- 26 May 2006

SL-GMS Reference A-66

TEXTENTRY VAR GISMOs

Description: call an application callback function with individual fields 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)

Version 6.2a- 26 May 2006

SL-GMS Reference A-67

GISMO action functions: gms_textentry_var( ), gms_hilite_edge_selobj( ), and gms_hilite_color_selobj( ) Functional Description: The TEXTENTRY VAR GISMO uses the gms_textentry_var( ) function which does two things in response to either a locator selection of the object, or the string event which is generated upon completion of the string by typing a <NEWLINE>: · When the TEXTENTRY VAR GISMO is selected via a Locator, the Text or Text Rectangle object is made into the current string-echo object by calling SL-GMS function gmsStTextEditObj( ). The internal SL-GMS variables, _ _selected_object and _ _self are set to the address of the object at the same time. The _ _selected_object variable is used by the SL-GMS event handler to determine which object is 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 the echoing object and places it into the variable provided as an argument. The __selected_object variable is also used by the gms_hilite_edge_selobj( ) and gms_hilite_color_selobj( ) functions to hilite the selected GISMO.

·

The calling syntax of the gms_textentry_var( ) function is described on page A-103. The calling syntax of the gms_hilite_edge_selobj( ) function is described on page A-88. The calling syntax of the gms_hilite_color_selobj( ) function is described 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:

Version 6.2a- 26 May 2006

SL-GMS Reference A-68

Variables f_textv Variable Name callback Description renamed to the user callback function (without quotation marks); renaming is optional if variable is renamed renamed to an integer constant or variable; the highlight color renamed to a double constant or variable; the highlight edge width renamed to an integer constant or variable; the maximum number of characters allowed for input 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) renamed to a string variable which the text represents; renaming is optional if callback is renamed renamed to an integer constant or variable; the unhighlight color renamed to an double constant or variable; the unhighlight edge width

hc hw maxchars type

variable

uc uw

Version 6.2a- 26 May 2006

SL-GMS Reference A-69

Variables for the textentry GISMO are: Variables textentry Variable Name callback Description renamed to the user callback function (without quotation marks); renaming is optional if variable is renamed renamed to an integer constant or variable; the maximum number of characters allowed for input 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) renamed to a string variable which the text represents; renaming is optional if callback is renamed

maxchars type

variable

Variables for the m_textv GISMO are: Variables m_textv Variable Name see Table Am (page A-111)1 callback renamed to the user callback function (without quotation marks); renaming is optional if variable is renamed renamed to an integer constant or variable; the maximum number of characters allowed for input Description

maxchars

Version 6.2a- 26 May 2006

SL-GMS Reference A-70

Variables m_textv

(continued)

Variable Name type

Description 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) renamed to a string variable which the text represents; renaming is optional if callback is renamed

variable

1. button_label is not a variable in the m_textv GISMO.

The basic SL-GMS Data Types (defined in the file "gmscodes.h" distributed in the lib subdirectory), valid for the TEXTENTRY VAR GISMO, are: Basic SL-GMS Data Types Valid for the TEXTENTRY VAR GISMO Decimal Value 2 8 256

Data Type G_INTEGER G_DOUBLE G_STRING

Description integer double pointer-to-pointer to a null-terminated string

Hex Value 0x2 0x8 0x100

Example RenamedVars

Sample RenamedVars for the m_textv GISMO to allow input of an integer (maximum of 10 characters); call the my_function callback and set the variable my_variable: callback :: my_function

Version 6.2a- 26 May 2006

SL-GMS Reference A-71

edge_width :: 3 maxchars :: 10 text_align_x :: 2 text_height :: 1.5 (integer) type :: 2 variable :: my_variable Sample RenamedVars for the m_textv GISMO to allow input of a double (maximum of 10 characters); call the my_function callback and set the variable my_variable: callback :: my_function edge_width :: 3 maxchars :: 10 text_align_x :: 2 text_height :: 1.5 (double) type :: 8 variable :: my_variable Sample RenamedVars for the m_textv GISMO to allow input of a string (maximum of 10 characters); call the my_function callback and set the variable my_variable: callback :: my_function edge_width :: 3 maxchars :: 10 text_align_x :: 2 text_height :: 1.5 (string) type :: 256 variable :: my_variable

PROGRAM INTERFACE

If type is 2 (integer) the callback function must expect as an argument a pointer to a pointer to the object selected and a pointer to an integer: int

Version 6.2a- 26 May 2006

SL-GMS Reference A-72

my_function (obj, i) id *obj; /* pointer to pointer to GISMO part picked */ int *i; /* integer value entered */ { /* this is a dummy statement; actual function code belongs here... */ printf("*obj = %x, *i = %d\n",*obj, *i); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,""); /* include this statement to deactivate/unhighlight upon end of string 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 an argument a pointer to a pointer to the object selected and a pointer to a double: int my_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); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,"");

Version 6.2a- 26 May 2006

SL-GMS Reference A-73

/*include this statement to deactivate/unhighlight upon 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 an argument a pointer to a pointer to the object selected and a pointer to a pointer to char: int my_function (obj, s) id *obj;/*pointer to pointer to GISMO part picked*/ char **s; /* string entered */ { /* this is a dummy statement; actual function code belongs here... */ printf("*obj = %x, *s = %s\n",*obj, *s); /* include this statement if wish to clear string just entered */ gmsTRepl(*obj,""); /* include this statement to deactivate/unhighlight upon end of string entry, i.e., with the <RETURN> key */ gmsStTextEditObj (gmsQStEvState( ), nil,0,"","", 0); return 1; } NOTE: obj, i, d, and s are pointers (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada.

Version 6.2a- 26 May 2006

SL-GMS Reference A-74

By default, the TEXTENTRY VAR GISMO is selected (activated and highlighted) by clicking on it with the mouse and unselected when another TEXTENTRY VAR GISMO is selected. To have the TEXTENTRY VAR GISMO deactivate and unhighlight upon termination of string entry, that is, via the <RETURN> key, the gmsStTextEditObj( ) function call is included in the user callback function. Regardless of type the callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call as follows: . . int my_arg2p[] = {G_POINTER, G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 2, my_arg2p); In the code fragment above, my_arg2p[ ] is the same for each type because the arguments to my_function are always pointers.

Version 6.2a- 26 May 2006

SL-GMS Reference A-75

NON STANDARD COLORCELLS GISMOs

Description: manipulates a color index variable equal to the color index of the object picked and optionally calls an application callback function

DynProps: Functionality # call gms_color_select(callback, &colorvar) Appearance (colarr4 only): cube_start_index = * ecolor fcolor cube_start_index = * ecolor fcolor . . . cube_start_index = *

(cube_start_index - 4) (cube_start_index + 0)

(cube_start_index - 4) (cube_start_index + 1)

Version 6.2a- 26 May 2006

SL-GMS Reference A-76

ecolor (cube_start_index - 4) fcolor (cube_start_index + 63) The appearance of objects in the colorcells GISMO is determined by the attributes associated with each object. DynProps are not utilized for control of appearance.

GISMO action functions: gms_color_select( )

Functional Description: When selected, the COLORCELLS GISMO calls gms_color_select( ) to set the value of the colorvar renamed variable to the color index of the object selected. The callback function is invoked (if the callback variable is renamed) and passed the value of the fill color index of the selected part. Valid color indices are taken from the "colordef.dat" file defined in either the SL-GMS lib directory, the current directory, or any directory defined to SL-GMS with the gmsAddLibPath( ) function. The calling syntax of the gms_color_select( ) function is described on page A-82.

Variables: Variables for the colorcells GISMO are: Variables colorcells Variable Name callback Description renamed to the user callback function (without quotation marks); renaming is optional if colorvar is renamed

Version 6.2a- 26 May 2006

SL-GMS Reference A-77

Variables colorcells

(continued)

Variable Name colorvar

Description generally renamed to the integer variable that drives the GISMO; renaming is optional if callback is renamed

Variables for the colarr4 GISMO are: Variables colarr4 Variable Name callback Description renamed to the user callback function (without quotation marks); renaming is optional if colorvar is renamed generally renamed to the integer variable that drives the GISMO; renaming is optional if callback is renamed 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)

colorvar

cube_start_index

Example RenamedVars

callback (callback NOT renamed) colorvar :: my_colorvar(variable renamed) OR callback :: my_function(callback renamed) colorvar (variable NOT renamed) OR

Version 6.2a- 26 May 2006

SL-GMS Reference A-78

callback :: my_function(callback renamed) colorvar :: my_colorvar(variable renamed) Either colorvar, callback, or both must be renamed. If only colorvar is renamed, the value of the renamed variable (my_colorvar in the first example above) is changed directly in memory in response to the input event. If only the callback variable is renamed, the callback function (my_function in the second example) is invoked. If both colorvar and callback are renamed, as in the third example, the value of the renamed variable my_colorvar is changed directly in memory, and the my_function callback function is then invoked. The callback function might perform some error checking or change the value of my_colorvar further.

PROGRAM INTERFACE

The callback function must expect as an argument a pointer to an integer: int my_function (value) int *value; /* value of color index of object picked*/ { /* this is a dummy statement; actual function code belongs here... */ printf("*value = %d\n", *value); return 1; }

NOTE: value is a pointer (i.e., called by reference) so that my_function can be written in either C, FORTRAN, or Ada. The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call:

Version 6.2a- 26 May 2006

SL-GMS Reference A-79

. . int my_arg1p[] = {G_POINTER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 1, my_arg1p);

Version 6.2a- 26 May 2006

SL-GMS Reference A-80

SL-GMS GISMO Action Functions

(In alphabetical order by function name)

gms_call( )

Syntax

int gms_call (callback) int (*callback)( );/* user-defined callback function */

Description

This function calls a user-defined function in response to a locator release.

Callback

Page A-6 provides a description of the callback function.

gms_call1( )

Syntax

int gms_call1 (callback, arg1) int (*callback)( );/* user-defined callback function */ long arg1; /* argument to user-defined callback function */

Description

This function calls a user-defined function with one argument in response to a locator release.

Callback

The callback function must expect as arguments a pointer to an integer and a long: int

Version 6.2a- 26 May 2006

SL-GMS Reference A-81

my_function (partindex, arg) int *partindex;/* index of GISMO part picked */ long arg; /* argument to callback function */ { /* this is a dummy statement; actual 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 that my_function can be written in either C, FORTRAN, or Ada.

The callback function my_function must be declared to SL-GMS with the gmsAddUserFctn( ) call: . . int my_arg1p1i[] = {G_POINTER, G_INTEGER}; . . gmsAddUserFctn("my_function", my_function, G_INTEGER, 2, my_arg1p1i);

gms_color_select( )

Syntax

int gms_color_select (callback, colorindex) int (*callback)( );/* user-defined callback function */ int *colorindex;/* color index variable */

Version 6.2a- 26 May 2006

SL-GMS Reference A-82

Description

This function sets a color index variable to the fill color index of the selected part and optionally calls a user callback function, passing the fill color index of the selected part.

Callback

Page A-79 provides a description of the callback function.

gms_cycle_var( )

Syntax

int gms_cycle_var (callback, variable) int (*callback)( );/* user-defined callback function */ int *variable;/* index variable */

Description

This function cycles a variable based upon the number of parts in the selected 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 or Group to which the DynProp containing this function is attached, and invokes an optional user-defined function.

Callback

Page A-39 provides a description of the callback function.

gms_datscreen_state_invoke( )

Syntax

int gms_datscreen_state_invoke (viewname, modelname, resetflag, clearflag) char *viewname;/* name of View in which to display Models */ char *modelname;/* name of Model to display */

Version 6.2a- 26 May 2006

SL-GMS Reference A-83

int resetflag;/* ON = reset State stack */ int clearflag;/* ON = clear View before displaying Model */

Description

This function creates and activates an Instance of the datscreen State class. It also sets the View name, adds a Model to the State Instance's Model 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 to 1.

gms_flash( )

Syntax

int gms_flash ( )

Description

The gms_flash( ) function highlights the selected object using "flash" behavior. The _ _button_hilite variable is set in response to a locator press, and reset in response to a locator release.

gms_flash_call( )

Syntax

int gms_flash_call (callback) int (*callback)( );/* user-defined callback function */

Description

This function calls a user-defined function with "flash" highlighting behavior on the selected object. The _ _button_hilite variable is set in response to a locator press, and reset in response to a locator release. If a callback function is specified, it is invoked after _ _button_hilite is reset.

Version 6.2a- 26 May 2006

SL-GMS Reference A-84

Callback

Page A-6 provides a description of the callback function.

gms_fpercent_var1( )

Syntax

int gms_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 */

Description

This function sets a variable in a range in response to a locator press on a FILL PERCENT GISMO.

Callback

Page A-43 for a description of the callback function.

gms_hilite_color( )

Syntax

int gms_hilite_color (arrayvar, hc, uc) int *arrayvar;/* array variable */ int hc; /* highlighted color */ int uc; /* unhighlighted color */

Description

This 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 variable. If arrayvar[part-index] is 1, the part's fill color is set to the highlighted color. If the arrayvar[part-index] is 0, the part's fill color is set to the

Version 6.2a- 26 May 2006

SL-GMS Reference A-85

unhighlighted color. unhilighted color.

Other objects in the Group are changed to the

gms_hilite_color_selobj( )

Syntax

int gms_hilite_color_selobj (hc, uc) int hc; /* highlighted color */ int uc; /* unhighlighted color */

Description

This function highlights only one object in a Group -- that which is the current TextEdit object. An object is made the current TextEdit object through execution of one of the following functions: gmsStTextEditobj( ) gms_textentry_array( ) gms_textentry_var( )

gms_hilite_color_var( )

Syntax

int gms_hilite_color_var (indexvar, hc, uc) int *indexvar;/* part index of object to highlight */ int hc; /* highlighted color */ int uc; /* unhighlighted color */

Description

This function highlights an object in a Group or part using fill color (objects are assumed to be filled). The object whose part index is the same as the value of indexvar is set to the highlighted color. Other objects in the part (which could be a Group) are changed to the unhighlighted color.

Version 6.2a- 26 May 2006

SL-GMS Reference A-86

gms_hilite_cycle( )

Syntax

int gms_hilite_cycle (indexvar) int *indexvar;/* part index of object to highlight */

Description

This function highlights an object in a Group or part using visibility. The object whose part index is the same as the value of indexvar is made visible. 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 invisible.

gms_hilite_edge( )

Syntax

int gms_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 */

Description

This function highlights each object of a Group or part using edge color and width. If arrayvar[part-index] is 1, the part is highlighted. Otherwise, the part is unhilighted.

Version 6.2a- 26 May 2006

SL-GMS Reference A-87

gms_hilite_edge_selobj( )

Syntax

int gms_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 */

Description

This function highlights using edge color and width, according to whether the object, or one of the parts within the object, is equal to the currently-selected TextEdit object _ _selected_object.

gms_hilite_edge_var( )

Syntax

int gms_hilite_edge_var (indexvar, hc, uc, hw, uw) int *indexvar;/* part index of object to highlight */ int hc; /* highlighted edge color */ int uc; /* unhighlighted edge color */ double hw; /* highlighted edge width */ double uw; /* unhighlighted edge width */

Description

This function highlights objects in a Group or part using edge color and width. The object whose part index is the same as the value of indexvar is highlighted. Other objects in the part (which could be a Group) are unhighlighted. A value of -1 means that nothing is highlighted.

gms_hilite_flip( )

Version 6.2a- 26 May 2006

SL-GMS Reference A-88

Syntax

int gms_hilite_flip (arrayvar) int *arrayvar;/* array of highlight flags */

Description

This function highlights each object of a Group, associating each object in order with each element of the given array variable. Each object of the Group must itself be an object containing at least two parts. The function highlights by changing the visibility 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 the second part is invisible) if the associated variable is 0. The second part is visible if the variable is 1.

gms_hilite_flip_var( )

Syntax

int gms_hilite_flip_var (indexvar) int *indexvar;/* highlight variable */

Description

This function highlights only one object in a Group. The object highlighted is the one whose part-index is equal to the value of indexvar. The object must contain at least two parts. The function highlights by changing the visibility 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 (and the second part is invisible) if the value of indexvar is 0. The second part is visible if indexvar is 1.

Version 6.2a- 26 May 2006

SL-GMS Reference A-89

gms_hilite_fpercent1( )

Syntax

int gms_hilite_fpercent1 (variable, minval, maxval) double *variable;/* fill value */ double minval;/* minimum value of range */ double maxval;/* maximum value of range */

Description

This function performs a fpercent action given a range on the second object in a FILL PERCENT GISMO. The first object is assumed to be a background object. variable is set to the relative fill position in the minval to maxval range.

gms_hilite_percent1( )

Syntax

int gms_hilite_percent1 (variable, minval, maxval) double *variable;/* position value */ double minval;/* minimum value of range */ double maxval;/* maximum value of range */

Description

This function performs a move action given a range on the second object in a SLIDER GISMO. This function moves the object so that the Reference Point of the object is positioned at a place interpolated between the Reference Points on the third and fourth object elements. The first object element is a background object and is always redrawn. variable is set to the relative position in the minval to maxval range.

Version 6.2a- 26 May 2006

SL-GMS Reference A-90

gms_hilite_percent2( )

Syntax

int gms_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 */

Description

This function performs a replace points action given a range on the second object in a SLIDER GISMO, setting the start and end to represent the first and second variables given as arguments. The result is that the second object in the SLIDER GISMO is sized to var1 and var2 to represent a percentage of the range defined by minval and maxval.

gms_hilite_vis( )

Syntax

int gms_hilite_vis (arrayvar) int *arrayvar;/* array of highlight values */

Description

This function highlights the members of a Group using visibility. Each Group member must itself be an object containing at least two parts. If arrayvar[part-index] is 0, the first part of the Group member is visible and the second part is invisible. Otherwise, the second part of the Group member is visible.

Version 6.2a- 26 May 2006

SL-GMS Reference A-91

gms_hilite_vis_var( )

Syntax

int gms_hilite_vis_var (indexvar) int *indexvar;/* index variable for part to highlight*/

Description

This function highlights the members of a Group using visibility. Each Group member must itself be an object containing at least two parts. The second part of the Group member whose part-index is equal to the value of indexvar is made visible. For all other Group members, the first part is visible.

gms_hilitescroll_array( )

Syntax

int gms_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 */

Description

The gms_hilitescroll_array( ) function is used to highlight selected lines of text. The first argument, cursorindex, is an index (offset) into hilitearray. The second argument, hilitearray, is an array of integers that specifies which lines of the array are highlighted. The value of the element hilitearray[cursorindex] is the highlight flag for the first line of text. An array element with a value of 1 indicates a highlighted line of text. The third and fourth arguments are the colors with which to highlight and unhighlight the lines of text.

Version 6.2a- 26 May 2006

SL-GMS Reference A-92

gms_hilitescroll_var( )

Syntax

int gms_hilitescroll_var (cursorindex, hiliteindex, hc, uc) int *cursorindex;/* array index of the string displayed in the first object of a Group of Text Rectangles */ int *hiliteindex;/* array index of the currently highlighted string */ int hc; /* highlight color */ int uc; /* unhighlight color */

Description

The gms_hilitescroll_var( ) function highlights one member of a Group of Text Rectangles. The member highlighted is the one whose part-index is equal to (*hiliteindex - *cursorindex). All other members of the Group are unhighlighted. The third and fourth arguments are the highlight and unhighlight colors, respectively.

gms_popup_state_invoke( )

Syntax

int gms_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 */

Version 6.2a- 26 May 2006

SL-GMS Reference A-93

Description

This function creates and activates an Instance of a generic State class. It also sets the View name, adds the specified Model to the State Instance's Models List, sets the State Instance's popflag on, the freeflag on, the clearflag off, and sets the State Instance's resetflag attribute. The resetflag set to 1 causes the function gmsStResetToMark( ) to be called on the current State. This deactivates States starting at the current State and up the State tree until a marked State is encountered.

gms_quit( )

Syntax

int gms_quit( )

Description

This function exits from SL-GMS by calling gmsExit( ).

gms_radio_array( )

Syntax

int gms_radio_array (callback, arrayvar, always_on) int (*callback)( );/* user-defined callback function */ int *arrayvar;/* array of values */ int always_on;/* if set to 1, one element in "arrayvar" is always on */

Description

This function associates an array variable with a set of radio buttons. Each element of the array variable, arrayvar, corresponds to the part numbers of the object (zero relative). It sets the value of no more than one element of arrayvar to 1 and sets all the remaining elements to 0 and passes the callback function the index of the selected object, and the value which is set for that member of the array variable.

Version 6.2a- 26 May 2006

SL-GMS Reference A-94

If the always_on flag is set to 1, at least one element of arrayvar is always set to 1. In addition, radio buttons are selected (or unselected) either by a loc_release Event (pressing and releasing the mouse button) or a loc_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 at the same time, one does not have to remain on.

Callback

Page A-31 provides a description of the callback function.

gms_radio_var( )

Syntax

int gms_radio_var (callback, indexvar, always_on) int (*callback)( );/* user-defined callback function */ int *indexvar;/* index of selected object */ int always_on;/* if set to 1, part index is always passed to callback function */

Description

This function associates an index variable, indexvar, with a set of radio buttons. The function sets indexvar to the part-index of the selected object and passes it to the callback function as the first argument. The variable indexvar is set to -1 whenever none of the radio buttons are selected. There are two ways for this to occur: 1. the mouse cursor is not on one of the radio buttons when the always_on flag is set to 1 and the loc_motion method is being used for button selection; 2. a "selected" radio button is "unselected" when always_on is set to 0. If the always_on flag is set to 1, then at least one radio button is always on. In addition, radio buttons are selected (or unselected) either by a

Version 6.2a- 26 May 2006

SL-GMS Reference A-95

loc_release Event (pressing and releasing the mouse button) or a loc_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 at the same time, one does not have to remain on.

Callback

Page A-31 provides a description of the callback function.

gms_radioscroll_var( )

Syntax

int gms_radioscroll_var (callback, cursorindex, hiliteindex, always_on, always_call) int (*callback)( );/* user-defined callback function */ int *cursorindex;/* array index of the string displayed in the first object of a Group of Text Rectangles */ int *hiliteindex;/* array index that corresponds to the selected object in a Group of Text Rectangles */ int always_on;/* not used */ int always_call;/* always call callback function */

Description

The gms_radioscroll_var( ) sets the value of hiliteindex in response to a locator Event. The first argument, callback, is an optional pointer to a user-defined callback function. The second argument, cursorindex, is an index (offset) into an array of strings. If the array is 100 lines long, and the scrolling window is display-

Version 6.2a- 26 May 2006

SL-GMS Reference A-96

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) into the array of strings. It is the index of the string in an array of strings that is highlighted 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 when the 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), the callback function is called only when the mouse button is released (i.e., when gmsQEvCode(event) == G_LOC_RELEASE).

Callback

Page A-50 provides a description of the callback function.

gms_screen_state_invoke( )

Syntax

int gms_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 */

Description

This function creates and activates an Instance of a generic State Class. It sets the View name, adds the specified Model to the State Instance's Model Name list, sets the State Instance's popflag off, the clearflag to the specified value, and the freeflag on. Setting the resetflag to 1 causes the function gmsStResetToMark( ) to be called on the current State, meaning that States are deactivated starting at the current State and up the State tree until a marked State is encountered.

Version 6.2a- 26 May 2006

SL-GMS Reference A-97

This function returns 0 if it fails to activate because it could not find the named View or Model.

gms_slider_var1( )

Syntax

int gms_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 */

Description

This function sets a real variable to the value interpolated between the given maximum and minimum, depending upon the position of the locator Event in relation to the third and fourth GISMO elements, described in the section SLIDER GISMOs on page A-55.

Callback

Page A-58 provides a description of the callback function.

gms_state_invoke( )

Syntax

int gms_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 */

Version 6.2a- 26 May 2006

SL-GMS Reference A-98

int clearflag;/* ON = clear View before displaying Model */ int popflag; /* value for State "popflag" */ int datflag; /* value for State "datflag" */

Description

The gms_state_invoke( ) function creates a new Instance of the State class classname and installs it in the State Management Hierarchy. The other arguments set the various State Instance attributes as described in the 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 tree until a State instance marked with the gmsStMark function is encountered. The newly-created State Instance is installed there. If the event State does not exist, the deactivation process starts at the current State. If there is no marked State Instance, it resets to the Top State and installs the newly-created State Instance there. NOTE: The gms_state_invoke( ) function can not be used to invoke any of the Enhanced States described in the SL-GMS® State Class Library Reference.

gms_state_pop( )

Syntax

int gms_state_pop ( ) This function deactivates the event State (i.e., that State in which an event occurred) if it exists, otherwise it deactivates the current State.

gms_state_return( )

Syntax

int gms_state_return ( )

Version 6.2a- 26 May 2006

SL-GMS Reference A-99

Description

This function deactivates the event State (i.e., that State in which an event occurred) if it exists, otherwise it deactivates the current State.

gms_stayon( )

Syntax

int gms_stayon ( )

Description

The gms_stayon( ) function causes the _ _button_hilite variable to be set, and gmsDynUpdate( ) to be called on the object currently processed. After all DynProp actions for the selected object are performed, the _ _button_hilite variable is reset.

gms_stayon_call( )

Syntax

int gms_stayon_call (callback) int (*callback)( );/* user-defined callback function */

Description

This function calls a user-defined function with "stayon" highlighting behavior on the selected object. The gms_stayon_call( ) function causes the _ _button_hilite variable to be set, and gmsDynUpdate( ) to be called on the object currently processed. If a callback function is specified, it is invoked. After the callback function returns, the _ _button_hilite variable is reset. If no callback function is specified, the _ _button_hilite variable is not reset until all DynProp actions for the selected object are performed.

Callback

Page A-6 provides a description of the callback function.

Version 6.2a- 26 May 2006

SL-GMS Reference A-100

gms_text_array_slider_hilite( )

Syntax

int gms_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 */

Description

The gms_text_array_slider_hilite( ) function moves the 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 percentage 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 Rectangles in a Group) in the scrollbox. The third and fourth arguments are the indices of the first and last elements in the string array (zero relative).

gms_text_array_slider_var( )

Syntax

int gms_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 */

Version 6.2a- 26 May 2006

SL-GMS Reference A-101

int last_index;/* index of last string array element */

Description

The gms_text_array_slider_var( ) function responds to a locator press on the slider and sets the variable cursorindex to the index in the string array of the first line in the scrollbox. The first argument, callback, is an optional pointer to a user-defined callback function. The second argument, cursorindex, is an index (offset) into the string array. 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 elements in the string array.

Callback

Page A-51 provides a description of the callback function.

gms_textentry_array( )

Syntax

int gms_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*/

Description

This function handles a Group of textentry objects that is associated with an array variable. On a locator Event, the selected object within the Group is made the current echo object, and all subsequent key events are

Version 6.2a- 26 May 2006

SL-GMS Reference A-102

absorbed except for non-printable ASCII keys. On a carriage-return, the variable is updated with the entered value and the specified callback is called, if it exists, passing it the current textedit object id and the address of the variable. Finally, the next object in the Group is made the current textedit object.

Callback

Pages A-63 through A-65 provide a description of the callback function.

gms_textentry_var( )

Syntax

int gms_textentry_var (callback, variable, maxchars, type) int (*callback)( );/* user_defined callback function */ 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*/

Description

This function accepts input for a single Text Rectangle object.

Callback

Pages A-72 through A-74 provide a description of the callback function.

Version 6.2a- 26 May 2006

SL-GMS Reference A-103

gms_textload_array( )

Syntax

int gms_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*/

Description

This function sets the text content for of each member of a Group of Text Rectangle objects with the content of the given array variable. Valid values for type are described on page A-62.

gms_textscroll_array ( )

Syntax

int gms_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 */

Description

The gms_textscroll_array( ) function is used to load a Group of Text Rectangle 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 as an offset into the array. The Group of Text Rectangles is loaded from arrayvar beginning with arrayvar[indexvar].

Version 6.2a- 26 May 2006

SL-GMS Reference A-104

The third argument, maxchars, is the maximum number of characters per line. The fourth argument, maxlines, should be set to the maximum number of text lines that can be displayed in the GISMO, that is, the number of Text Rectangle objects in the Group.

gms_textscroll_lines ( )

Syntax

int gms_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 Text Rectangles */ int maxlines; /* maximum number of lines in Group */ int numlines; /* number of lines to scroll */

Description

The gms_textscroll_lines( ) function is used to scroll through an array of strings 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 as an offset into the array. In response to a locator press, the value of numlines is added to indexvar. The third argument, maxlines, should be set to the maximum number of text 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. numlines can 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 is renamed to the value 1.

Version 6.2a- 26 May 2006

SL-GMS Reference A-105

gms_toggle_array( )

Syntax

int gms_toggle_array (callback, arrayvar) int (*callback)( );/* user_defined callback function */ int *arrayvar;/* array of ints*/

Description

This function toggles each element in an array variable between the values 0 and 1.

Callback

Page A-36 provides a description of the callback function.

gms_togglescroll_array( )

Syntax

int gms_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 */

Description

The gms_togglescroll_array( ) function sets array element values in hilitearray based upon which Text Rectangle was clicked with the mouse. The first argument, callback, is an optional pointer to a user-defined callback function. The second argument, cursorindex, is an index (offset) into the array.

Version 6.2a- 26 May 2006

SL-GMS Reference A-106

The third argument, hilitearray, is an array of integers that specifies which lines of the array are highlighted. An array element with a value of 1 indicates a highlighted line of text. The fourth argument, always_on, is currently not used.

Callback

Page A-50 provides a description of the callback function.

Version 6.2a- 26 May 2006

SL-GMS Reference A-107

Reserved variable names for GISMO DynProps

The reserved variable names set or used by SL-GMS functions and SL-GMS GISMO Action Functions are provided in the following table. Reserved Variable Names for GISMO DynProps Variable _ _button_hilite Type int Description 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-108

Reserved Variable Names for GISMO DynProps

(continued)

Variable _ _selected_object id

Type

Description 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_state SL-SMS automatically sets this variable to: 0 when state is not active 1 when state is currently active If the button_state variable is renamed to any other name, SL-SMS ignores it. set to system time as hh:mm:ss upon gmsDynInit( ) and updated once a second

timeofday

string

Any variable name preceded by two underscores does not appear in SL-GMSDraw's Object Renamed Variables window.

Version 6.2a- 26 May 2006

SL-GMS Reference A-109

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) Variable Name button_label edge_hicolor edge_uncolor edge_width fill_hicolor fill_uncolor text_font Description renamed to a string constant or variable renamed to an integer constant or variable; the edge highlight color renamed to an integer constant or variable; the edge unhighlight color renamed to an integer constant or variable; the edge width renamed to an integer constant or variable; the fill highlight color renamed to an integer constant or variable; the fill unhighlight color renamed to an integer constant or variable; the font index used to display button_label renamed to a numeric constant or variable renamed to an integer constant or variable; the text highlight color renamed to an integer constant or variable; the font type used to display button_label renamed to an integer constant or variable; the text unhighlight color

text_height text_hicolor text_prec text_uncolor

Version 6.2a- 26 May 2006

SL-GMS Reference A-110

m Table Appearance Variables for m_* GISMOs (Motif look-alike) Variable Name button_label direction Description renamed to a string constant or variable (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 renamed to an integer constant or variable; the width of highlight shadows renamed to an integer constant or variable; for left (1), center (2), or right (3) horizontal alignment of text renamed to a numeric constant or variable

edge_width text_align_x

text_height

Version 6.2a- 26 May 2006

SL-GMS Reference A-111

Appearance of BUTTON Type GISMOs Dimensions

The "m" and "f" series of GISMOs have fixed dimensions. These can be changed by scaling. SubModels can be scaled by setting the Scale parameters in the SubModel Control Panel or by scaling the Instance.

f_call

Figure A-2The "state_1" object

Scaling can be either equal or unequal in the x and y dimensions. Text height will be scaled also, therefore, some adjustment of this appearance variable may be necessary to produce the desired results.

Appearance "f" Style

The appearance of the "f" style BUTTON type GISMO is created with two Filled Text Rectangles objects called state_1 and state_0. The state_1 object controls the appearance of the button when it is selected. The state_0 object controls the appearance of the button when it is unselected. The state_1 object, shown in Figure A-2, is a Filled Text Rectangle created with the following SL-GML code. The f_call GISMO will be used for this example. state_1: ftrect 0 0 10 4 "f_call"

Version 6.2a- 26 May 2006

SL-GMS Reference A-112

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 SL-GMSDraw Syntax button_label =* stext button_label "%s" Description 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 when the variable text_hicolor is initialized or changed, the Text color (tcolor) is the value assigned to text_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

text_hicolor =* tcolor text_hicolor fill_hicolor =* fcolor fill_hicolor

Version 6.2a- 26 May 2006

SL-GMS Reference A-113

DynProp for the "state_1" ("selected") object

(continued)

SL-GMSDraw Syntax edge_hicolor =* ecolor edge_hicolor

Description when the variable edge_hicolor is initialized or changed, then the edge color (ecolor) is the value assigned to edge_hicolor 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

__button_hilite || button_state =1 vis 1 redraw =0 vis 0

1. __button_hilite is set to 1 (true) by the gms_flash( ) function when the GISMO is selected, on a locator press, and then reset back to 0 (false) on a locator release.

The state_0 object, shown in Figure A-3, is a Filled Text Rectangle 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, as shown in Figure A-4 (DynProps for state_1 and state_0 not shown). The order of the grouped objects is important; the state_1 object should be selected first, then the state_0 object. group state_1: ftrect 0 0 10 4 "f_call" state_0: ftrect 0 0 10 4 "f_call" endg

f_call

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

Version 6.2a- 26 May 2006

SL-GMS Reference A-114

The DynProp shown below is attached to it. DynProp for the "state_0" ("unselected") object SL-GMSDraw Syntax __button_hilite || button_state =0 vis 1 redraw =1 vis 0 button_label =* stext button_label "%s" text_uncolor =* tcolor text_uncolor fill_uncolor =* fcolor fill_uncolor edge_uncolor =* ecolor edge_uncolor Description 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 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 when the variable text_uncolor is initialized or changed, the text color (tcolor) is the value assigned to text_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 when the variable edge_uncolor is initialized or changed, the edge color (ecolor) is the value assigned to edge_uncolor

1. __button_hilite is set to 1 (true) by the gms_flash( ) function when the GISMO is selected, on a locator press, and then reset back to 0 (false) on a locator release.

The DynProp shown below is attached to the Group. The DynProp is attached to the Group because these variables are common to both the selected and the unselected state.

Version 6.2a- 26 May 2006

SL-GMS Reference A-115

DynProp for the Group SL-GMSDraw Syntax __button_hilite || button_state =* batcherase text_height =* theight text_height Description 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. 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 when the variable text_font is initialized or changed, the Text font (tfont) is equal to the value assigned to the variable text_font 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 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

text_font =* tfont text_font text_prec =* tprec text_prec edge_width =* ewidth edge_width

"m" Style

The appearance of the "m" style BUTTON type GISMO is also created with two objects called state_1 and state_0. Each of these objects is a Group that contains a Filled Text Rectangle object and two Polyline objects. The state_1 object controls the appearance of the button when it is selected. The state_0 object controls the appearance of the button when it is unselected.

Version 6.2a- 26 May 2006

SL-GMS Reference A-116

The state_1 object is a Group that consists of a Filled Text Rectangle object, named plate_1, and two Polyline objects, named upper_1 and lower_1, created with the SL-GML code shown 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 variables differentiate the appearance of the different objects. state_1: group fcolor 14 ecolor 0 estyle 0 plate_1: ftrect 0 0 10 4 "m_call" fcolor 0 ecolor 15 estyle 1 upper_1: line 0 0 0 4 10 4 ecolor 12 lower_1: line 0 0 10 0 10 4 endg

m_call

upper_1

lower_1

plate_1

m_call

state_1

Figure A-5Parts of the "state_1" Group

Version 6.2a- 26 May 2006

SL-GMS Reference A-117

The plate_1 object has a DynProp attached to it as shown below. DynProp for the "plate_1" object SL-GMSDraw Syntax button_label =* stext button_label "%s" Description 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 when the variable text_align_x is initialized or changed, the text alignment (talign) is the value assigned to text_align_x 3

text_align_x =* talign text_align_x 3

The state_1 Group also has a DynProp attached to it. DynProp for the "state_1" Group ("selected") SL-GMSDraw Syntax __button_hilite || button_state =0 vis 0 =1 vis 1 redraw Description 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

The state_0 object is a Group that consists of a Filled Text Rectangle object, named plate_0, and two Polyline objects, named lower_0 and upper_0, created with the following SL-GML code. Only the fill color (fcolor), edge color (ecolor), and edge

Version 6.2a- 26 May 2006

SL-GMS Reference A-118

style (estyle) variables will be shown, since these variables differentiate the appearance of the different objects. state_0: group fcolor 13 ecolor 0 estyle 0 plate_0: ftrect 0 0 10 4 "m_call" fcolor 0 ecolor 15 estyle 1 lower_0: line 0 0 10 0 10 4 ecolor 12 upper_0: line 0 0 0 4 10 4 endg

m_call

upper_0

lower_0

m_call

plate_0

state_0

Figure A-6Parts of the "state_0" Group

Version 6.2a- 26 May 2006

SL-GMS Reference A-119

The plate_0 object has a DynProp attached to it as shown below. DynProp for the "plate_0" object SL-GMSDraw Syntax button_label =* stext button_label "%s" Description 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 when the variable text_align_x is initialized or changed, the text alignment (talign) is the value assigned to text_align_x 3

text_align_x =* talign text_align_x 3

The state_0 Group also has a DynProp attached to it. DynProp for the "state_0" object ("unselected") SL-GMSDraw Syntax __button_hilite || button_state =0 vis 1 redraw =1 vis 0 Description 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

The state_1 and state_0 objects are then grouped together, as shown in Figure A-7 (DynProps for state_1, plate_1, state_0, and plate_0, and other variables are not shown). group state_1: group plate_1: ftrect 0 0 10 4 "m_call" upper_1: line 0 0 0 4 10 4

Version 6.2a- 26 May 2006

SL-GMS Reference A-120

lower_1: line 0 endg state_0: group plate_0: ftrect lower_0: line 0 upper_0: line 0 endg

0 10 0 10 4

0 0 10 4 "m_call" 0 10 0 10 4 0 0 4 10 4

endg The DynProp, shown at the bottom of the page, is attached to the Group. The DynProp is attached to the Group because these variables are common to both the selected and the unselected state.

m_call

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

DynProp for the Group SL-GMSDraw Syntax __button_hilite || button_state =* batcherase Description 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-121

DynProp for the Group

(continued)

SL-GMSDraw Syntax text_height =* theight text_height edge_width =* ewidth edge_width

Description 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 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

Version 6.2a- 26 May 2006

SL-GMS Reference A-122

B

actions attributes

Glossary

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. 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. 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. Relating to symbolic relationships implied by the logical operators AND, OR, and NOT. 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. A Control Panel is a collection of buttons in a graphical display. The SL-GMSDraw interface uses Control Panels. A Datasource is a set of variable definition objects and methods used to connect graphical objects with external sources of data or internal variables.

Bitmap

Boolean button

Control Panel

Datasource

Version 6.2a- 26 May 2006

SL-GMS Reference B-1

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 describe behaviors an object performs to reflect the value of application variables. See also input dynamics, dynamics. 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 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. A collection of dynamic descriptions attached to an object is referred to as an object's DynProp (short for Dynamic Property). 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. 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. 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.

display dynamics

dynamic description

dynamics

DynProp

Event

GISMO

Group

Version 6.2a- 26 May 2006

SL-GMS Reference B-2

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. 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. In object-oriented programming, a message is a request for an object to execute one of its methods. 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. 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. 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.

Instance

message method

Model

NDC

Version 6.2a- 26 May 2006

SL-GMS Reference B-3

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 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. See Reference Point.

object-oriented

Object Reference Point:

Operation Reference Point: See Reference Point. output dynamics owner See display dynamics. Upward links in a Model for a Graphical Primitive object. For example,

Group or Model

object

parts

The term parts is used when referring to the objects collected as a Model. The parts of a Model are its objects. 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

Pull-Down Menu

Version 6.2a- 26 May 2006

SL-GMS Reference B-4

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.

Version 6.2a- 26 May 2006

SL-GMS Reference B-5

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. 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. 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. A TextEdit object is a Text or Filled Text Rectangle object used to echo characters entered from the keyboard. A Transformation object is a two-dimensional 2x3 matrix used to perform translation, scaling, and rotation of objects. 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. 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. A VarDef is a Variable Definition object created by the functions, gmsVarDefine( ), gmsStVarDefine( ), and gmsVarDefineNoTable( ).

State Instance

SubModel

TextEdit object

Transformation object

UserData

UserWord

VarDef

Version 6.2a- 26 May 2006

SL-GMS Reference B-6

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. 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. 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. See 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. 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.).

WC-entent

window

Workstation Workstation/Window

World Coordinates

Version 6.2a- 26 May 2006

SL-GMS Reference B-7

C

Introduction

· ·

SL-GMS Interface with the X Toolkit and X Windows

The SL-GMS interface to the X Toolkit (Xt) and X Windows (X) has two components: The creation or use of an X window or Xt-based widget in which to draw dynamic graphics The X event gathering -- either SL-GMS gathers X events or an application 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 in two separate interface libraries, the gwsxt and gwsx libraries, respectively. When using SL-GMS to draw dynamic graphics in an Xt-based widget (a Motif or OLIT widget, for example), the GWS-XT interface should be used. When drawing SL-GMS dynamic graphics in an X window, the GWS-X interface 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 application X event-loop gathering function external to SL-GMS. Both the GWS-XT and GWS-X interfaces and the process of X event gathering are described below.

The SL-GMS / Xt Interface

SL-GMS can either create or use an existing X window for dynamic graphics; however, SL-GMS cannot create an Xt-based widget in which to draw dynamic graphics. If SL-GMS dynamic graphics are to be used in an Xt-based widget (a Motif or an OLIT widget, for example), the widget must be created outside of SL-GMS. SL-GMS is informed of the Xt "id" of the Xt-based widget in which to draw dynamic graphics in the gmsWorkst( ) function call, which creates the SL-GMS Workst object. The Xt "id" of the Xt-based widget (which is an unsigned long integer) is passed in as a string argument to gmsWorkst( ). The wind argument to gmsWorkst( ) is a

Version 6.2a- 26 May 2006

SL-GMS Reference C-1

pointer to a character string that contains the Xt "id" of the widget. Simply use the sprintf( ) function to write the Xt "id" to a character string in memory and pass a pointer to the string as the wind argument to gmsWorkst( ). Please note that the conn argument (used for specifying the X Display connection name) does not need to be specified when using GWS-XT, since SL-GMS is not opening a Display connection but will use the one associated with the specified widget. SL-GMS may be used with an application Xt event-loop function external to SL-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 gathers the X events. The X events are then dispatched from the application's Xt event-loop function directly to SL-GMS. For example, this is the situation when using the XtAppMainLoop( ) Xt event gathering function or a similar Xt event gathering function which dispatches all X events to clients. If the application's Xt event-loop function does not dispatch all X events to clients, the use of an additional function, gmsProcessLowEvent( ), is necessary to pass the X events from the application's Xt event-loop function to SL-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 any client that has indicated an interest in the relevant X event type. In this case, a customized Xt event-loop function will be used in the application in place of XtAppMainLoop( ). Alternatively, the SL-GMS Xt event-loop function, gmsMainLoop( ), may be used to gather and dispatch all X events, much the same as XtAppMainLoop( ) does. The only difference between using gmsMainLoop( ) and XtAppMainLoop( ) is in what controls the X event gathering and dispatching. If gmsMainLoop( ) is used, SL-GMS controls the X event gathering and dispatching. If an application Xt event-loop function external to SL-GMS such as XtAppMainLoop( ) is used, the control of the X event gathering and dispatching is under the application code. For example, many Motif Graphical User Interface (GUI) builder tools generate a main( ) function for the application which calls XtAppMainLoop( ) or a similar function for X event-loop gathering and dispatching. The use of SL-GMS with an application Xt event-loop function external to SL-GMS allows for easy integration of a Motif interface generated by a Motif GUI builder tool with SL-GMS.

Version 6.2a- 26 May 2006

SL-GMS Reference C-2

The SL-GMS / X Interface

As mentioned above, SL-GMS can either create or use an existing X window for dynamic graphics. If the gmsWorkst( ) function is called with a null wind argument, SL-GMS will create an X window for drawing dynamic graphics. The conn argument will be used as the name of an X Display connection to open if it is specified. If the conn argument is null, the DISPLAY environment variable will be used to determine the name of the X display connection to open. If SL-GMS dynamic graphics are being used in an existing X window, both the conn and wind arguments must be specified. The "id" of the X window and the "id" of the associated X Display connection (both being unsigned long integers) are passed in as the wind and conn arguments, respectively, to gmsWorkst( ). Both of these arguments to gmsWorkst( ) are pointers to character strings that contain the appropriate "id". The sprintf( ) function is used to write each "id" to different character strings in memory and pass a pointer to the appropriate character string as the conn or wind argument to gmsWorkst( ). As mentioned above for the Xt case, SL-GMS may be used with an X event-loop external to SL-GMS through the use of gmsExternalEventLoopFlag( ), which allows the user to specify that SL-GMS is not to gather X events. Instead, an application X event-loop function external to SL-GMS gathers the X events; however, there is a significant difference when using X as opposed to Xt. Under X (Xlib) as opposed to Xt, the application's X event-loop function will not dispatch X events to clients. As a result, a call to gmsProcessLowEvent( ) must be added to the application's X event-loop function to pass X events to SL-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 be passed to SL-GMS. The return value of gmsProcessLowEvent( ) will indicate whether or not SL-GMS was interested in the X event. This way, the user does not need to try to determine in the application's X event-loop function whether or not SL-GMS has an interest in an X event. Alternatively, the SL-GMS X event-loop function, gmsMainLoop( ), may be used to gather X events. Some GUI builder tools generate Xlib code instead of Motif and Xt code. In this case, the generated code will probably contain an X event-loop function that the application expects to use to

Version 6.2a- 26 May 2006

SL-GMS Reference C-3

interact with the various parts of the GUI. This is an example of the situation where the use of an application X event-loop function external to SL-GMS is mandatory. The application's X event-loop should be modified to include a call to gmsProcessLowEvent( ) so that SL-GMS can receive and process X events gathered by the X event-loop function.

Version 6.2a- 26 May 2006

SL-GMS Reference C-4

D

Introduction

Model Utilities

SL-GMS provides the utilities for converting Model files from one format to another, and for generating localization files from Models. The Model conversion utilities are: gm1 (gm<one>), gm2, m1g, m1m2, and dxf2g. The genlocfile utility generates localization files from Models. These utilities are found in the SL-GMS bin directory, along with the SL-GML and SL-GMSDraw executables. Note that when processing files with these conversion utilities, errors are not reported.

Utility Command Line gm1 [-loc lang_name] <filename>.g gm2 [-loc lang_name] <filename>. g m1g <filename>.m1 m1m2 <filename>.m1

Description convert .g to .m1 convert .g to .m2 convert .m1 to .g convert .m1 to .m2

dxf2g ... <infile[ .dxf]> convert AutoCad .dxf files [modelname] to SL-GMS .g files (See page D-4 for a full description of arguments) genlocfile -loc lang_name [-p prefix] [-wc] [modelname] (See page D-15 for a full description of arguments) generate localization file commands for "internationalized" objects in Models

Version 6.2a- 26 May 2006

SL-GMS Reference D-1

Basic Model Conversion Utilities

SL-GMS provides a set of SL-GMS scripts that are used to convert SL-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 the original ".g" file. This is to be expected and is a result of any source-to-binary to source translation. When a Model has an external SubModel in its SubModels List, a reference to that SubModel remains in the ".m1" file, even if the Model has no Instances of the SubModel. However, if the Model is saved as a ".g" file and converted to an ".m1" using the gm1 conversion utility, the reference to the external 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 in Chapter 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 converted back to the ".g" or ".m1" form. The current release of SL-GMS does not yet provide scripts to convert backwards because the ".m2" files are most appropriately used for performance optimization during run time screen loading. It is important that ".m2" files be updated, using the m1m2 script for example, 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" file exists for an older version of the ".m1" file.

Version 6.2a- 26 May 2006

SL-GMS Reference D-2

Localization

A -loc option of the gm1 and gm2 conversion scripts allow them to apply localization files to Models as they are converted from ".g" to ".m1" or ".m2" format. Each ".g" file can optionally have a corresponding localization file. If the corresponding localization file exists for the ".g" Model, it will be used to localize the ".g" Model during the conversion. The gm1 and gm2 conversion scripts generate a localization file name for each ".g" file by concatenating 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 all corresponding localization files with "lang_name" of "ja": gm1 -loc ja *.g Further information about localization files is provided in the Internationalization -- localization filessection of the SL-GMS Function Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference D-3

AutoCAD dxf2g ".dxf" file converter

The SL-GMS utility dxf2g converts AutoCAD ".dxf" (Data Exchange Format) 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" file for 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 of each.

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 -a -f -cap -cf<file> -d<value> -e Description AutoCAD coordinates to be used without change1 Fit AutoCAD display to SL-GMSDraw default window (72 x 54) Approximate AutoCAD colors 1 ­ 255 with SL-GMS colors 0 ­ 31 Approximate AutoCAD colors with the color defs in <file>2 Divide all x and y values by the <value> given. Default is 1.0. Use $EXTMIN and $EXTMAX from dxf HEADER to set scaling3

Version 6.2a- 26 May 2006

SL-GMS Reference D-4

Flag -L

Description 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 Multiply nominal text height by this value. Default is 1.0 Change black text to white

-t<value> -tw

-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

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 by using 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 set a different extent such as the default display window of SL-DRAW2 which was (0., 0.) to (100., 75.).

Option -a alone

The option -a makes no changes in the numerical values found in the ".dxf" file before outputting them to the SL-GMS ".g" files. If -a is not used, there is no problem because dxf2g automatically scales the coordinates to fit the SL-GMSDraw default display window.

Option -d<value> alone

All 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 be taken. The extent of the DXF file can (usually) be obtained by looking at the values given by "EXTMAX x,y" and

Version 6.2a- 26 May 2006

SL-GMS Reference D-5

"EXTMIN x, y" near the beginning of the DXF file. If -a is set and any of those x,y values exceeds a magnitude of 32,767 or the difference between the x's or y's exceeds that magnitude, the -d<value> option must be used.

Option -L alone

The -L option must be applied when the x,y coordinates are given in latitude and longitude. Each x coordinate is multiplied by the cosine of the mid-latitude of the covered region. Failure to use this option in the case of lat/lon will cause the display to be elongated in the east-west direction.

Option -t<value> alone

The height of each text character or string is multiplied by <value>. This option is of value when the text is too small when displayed at the desired zoom factor or factors.

Combinations of -a, -d, -L

Any combination of these options is permitted. Two examples: -a and -d<val>. If -a is set and any x or y coordinate in the DXF file exceeds a magnitude of 32,767 or the difference between the MIN and MAX x or y exceeds that magnitude, the -d<val> option must also be applied in order to reduce such values to less than 32,767. A common use for this combination is when the DXF file represents a map, especially when the map may have to adjoin another map. The recommended value for <val> is a power of ten. -a, -d<val>, and -L. When the coordinates are in lat/lon, the -L option must be added. A few DXF files convert to a "very small display," which, when zoomed in, becomes a correct and satisfactory display. The solution for dxf2g could be the "zoom in" AutoCAD solution, where most initial displays are small. The alternative is the -e option, that is, to execute "dxf2g -e <file>.dxf." That causes dxf2g to use the extent given by $EXTMIN and $EXTMAX from the DXF header, which is then normalized to the SL-GMSDraw standard extent. (Our experience is that those values in the DXF header are not always correct.)

Version 6.2a- 26 May 2006

SL-GMS Reference D-6

Option -t<val> is sometimes helpful, while -tw may be needed when the display background colors are very dark grey or black. -t2 will double the dxf text heights, that is, those specified in the dxf file; -t0.5 will halve the dxf heights; -tw will make all text white. The -w option is self-explanatory, as are -cap and "-cf <cfile>". The option -e causes dxf2g to use the $EXTMIN and $EXTMAX values found in the header of the ".dxf" file. This option is normally not necessary to obtain a satisfactory fit of the display into 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.

dxf2g

Follow the USAGE statement.

colordef.acad

There are two things to consider: 1. The color numbers that appear in the ".g" files output by dxf2g 2. The colors to be available when using SL-GMSDraw. A. The "colordef.acad" file contains the color numbers and definitions used by AutoCAD. By default, dxf2g outputs ".g" files using the same color numbers. See the USAGE statement on how to use the -cap and -cf options to produce ".g" files with a different set of color numbers. B. The standard "colordef.dat" file for SL-GMSDraw does not accommodate all AutoCAD colors. Before using SL-GMSDraw to display the default dxf2g output files, that "colordef.dat" file should be sequestered, for example: cd $GMS_HOME/lib mv colordef.dat colordef.hold

Version 6.2a- 26 May 2006

SL-GMS Reference D-7

Then execute cp colordef.acad colordef.dat If there is a "colordef.dat" file in the directory in which SL-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 for SL-GMSDraw. Experience with the test files used with dxf2g indicate that it is a good idea to change the first color of this file from 0 0 0 to .9 .9 .9, or even to .85 .85 .85, to display a background sufficiently gray so that very pale colors, especially pale yellow, can be seen without difficulty.

Color

The file "colordef.acad" contains 168 RGB entries, as follows:

Index 0 - 31 32 33 - 41 42 - 51 52 - 61 ..... 152 - 161 162 - 167

Contents Standard SL-GMS colors White AutoCAD colors 1 - 9 AutoCAD colors 10 - 19 and 21 - 29 (colors are paired) AutoCAD colors 30 - 39 and 40 - 49 ........ AutoCAD colors 230 - 239 and 240 - 249 AutoCAD colors 250 - 255

If the display hardware is capable of simultaneously displaying the necessary number of colors, "colordef.acad" should be set up as the "colordef.dat" file, as described above.

Version 6.2a- 26 May 2006

SL-GMS Reference D-8

If the regular 32-color SL-GMS "colordef.dat" file is retained and an attempt is made to display a Model converted without the -cap option set, it is probable that no color displays will occur. Colors are processed in one of three ways: 1. When neither -cap nor -cf is 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 Model made in such a case, the "colordef.dat" file for SL-GMSDraw must be a copy of "colordef.acad". 2. Specifying -cap is equivalent to saying, "Only the 32 SL-GMS colors are available for display -- use them in the best way." In this case, each AutoCAD color number is converted to an index 0 through 31 so that that index corresponds to the "best fit" (least squares fit) to one of the standard SL-GMS colors. (In this case, the SL-GMS 32-color "colordef.dat" file will work satisfactorily during display.) 3. Specifying "-cf <file>" is equivalent to saying, "Only the N colors defined in <file> are available for display; use them in the best way." In this case, each AutoCAD color number is converted to an 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 work satisfactorily as the "colordef.dat" file during display. NOTE: Since all color numbers, converted or not, in the files created by dxf2g are one of the "colordef.acad" numbers and each displayed color 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. If you wish to use a variant of the supplied color file, put it into the directory in which SL-GMSDraw is being executed and restart SL-GMSDraw.

Supplementary Utilities

There are four support utilities especially designed to improve efficiency when using dxf2g. These support utilities are distributed in the bin directory. They are described below.

Version 6.2a- 26 May 2006

SL-GMS Reference D-9

Since these utilities may not be provided on all platforms, alternative procedures are described for each utility as appropriate. ____ g myr This program converts to ".m1" format all "<file>_*.g" files associated with the most recent "_subs.g" file and moves the saved SubModels to the SUBMODS 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 a case, 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 its functions as delineated in steps 2, 3, and 4 of the following sequence: 1. Execute dxf2g "<file>" in accordance with the USAGE statement. 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 from conversion of the "<file>_subs.g" are often numerous and interfere with working conveniently with the layer files, usually the only ones of significant interest. The above sequence, which is functionally identical to what gmyr does, assures that all external SubModels will be in the SUBMODS subdirectory, where they are available to SL-GMSDraw.

Version 6.2a- 26 May 2006

SL-GMS Reference D-10

_____ mvaa When the "_subs" file is converted to ".m1" format using gm1 directly, all the Models listed therein are saved with the result that their ".m1" files end up in the current directory. The utility mvaa moves all such ".m1" files to the SUBMODS subdirectory (creating it, if necessary) where they are available to SL-GMSDraw. USAGE mvaa<RETURN> ALTERNATIVE Move the SubModel files to SUBMODS.

Comparing AutoCAD and SL-GMSDraw displays

When doing this, it is usually better to bring up SL-GMSDraw first, since AutoCAD does not complain about unavailable colors. It occasionally happens with AutoCAD that there are "dependent" layers, that is, layers in the list that are "on" but that do not display when requested; however such a layer may display when another layer is turned on. The dxf2g solution to such a situation is not always predictable -- two possibilities seem to occur: 1. the dependent layer is displayed as a separate layer; 2. it is displayed 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 Menu and 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 Deficiencies

1. Xref files are not handled. 2. The VIEWPORT facility has not been adequately tested; it should not be used.

Version 6.2a- 26 May 2006

SL-GMS Reference D-11

Problems, Anomalies, and Limitations

NOTE: The displays created by AutoCAD from ".dxf" files are considered to be correct and have been used as the basis of comparison. 1. If the initial character of a BLOCK name is * or $ or -, it is replaced by "aa_" or "ad_" or "am_", respectively. An interior character of * or $ or - is replaced by the "_" character. 2. If the initial character of a BLOCK name is a digit, it is prefixed by "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, execution stops with an appropriate message; the name of the file must be changed. 5. The initially displayed line widths, that is, when the zoom factor is 1.0, are usually correct. Each line width in DRAW is constant and does not change thickness when zoomed, whereas lines in AutoCAD are actually filled rectangles or other shapes and do change thickness when zoomed. The SL method has been adopted primarily to achieve fast zoom and pan speeds, which many of 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 supported by dxf2g, except for the sequence %%% for %, which is respected. In general, all other %% sequences are removed before the ".g" file is created, except for the cases described here. Both of the constructs, %%u and %%o, which enclose strings, are removed, but any other %% sequences in that particular string are not removed. Of the other %% sequences, only the first one appearing in any given string is removed. Note: The

Version 6.2a- 26 May 2006

SL-GMS Reference D-12

sequence %%nnn is removed only if there are exactly three digits. 8. Partial Ellipses are not handled correctly. 9. POINT, as specified by $PDMODE and $PDSIZE. Only the POINT is output. 10. If an x or y "extrusion" associated with an entity is non-zero, the entity is ignored. All z "extrusions" are assumed to be zero. SL-GMSDraw is a two-dimensional system.

Very Small Radius

There 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 output or displayed. That is due to a basic feature of the SL-GMS program that converts ".g" files to ".m1" format, which thereby avoids spending its time trying to create an arc or circle smaller than a single dot or pixel. This "very small radius" problem" may arise with a "very small display" and then go away when the -e option is used.

Version 6.2a- 26 May 2006

SL-GMS Reference D-13

The genlocfile utility

For each Model contained in a given ".m1" or ".m2" file, the genlocfile utility traverses all parts and all local SubModels. For each object which "needs to be internationalized," genlocfile outputs a localization file command 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 for the internationalization prefix is "i_". If a given Model does not contain any objects which fulfill all these conditions, a localization file is not generated for that Model. The genlocfile utility synthesizes a name for the generated localization file by concatenating four elements: the name of the ".m1" or ".m2" file (without the ".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 -wc option is specified. The -wc option is recognized in Windows NT only. This option causes genlocfile to generate a wide-character (Unicode) localization file. The genlocfile utility cannot process ".g" files.

Version 6.2a- 26 May 2006

SL-GMS Reference D-14

Usage

To 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 "menu.m1" on Windows NT: localization file "menu_fr.lc" from

genlocfile -loc fr -wc menu.m1 To generate the localization file "menu_ja.lc" from "menu.m1", processing only 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 Internationalization -- localization filessection of the SL-GMS Function Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference D-15

E

Introduction

The State Management System

The SL-GMS State Management System (SL-SMS) facilitates navigation over and control of a collection of dynamic graphical screens and the processing states of those screens. SL-SMS coordinates the mapping (making visible) and unmapping (making invisible) of dynamic screens, provides a simple method of handling Events, and automatically activates Datasources. The design intent is to reduce to a minimum the user application programming required to control these elements. For example, GISMOs in a Model can provide pickable objects which, when selected, bring up other screens or popup menus. SL-SMS in a sense provides macros for calls to libgms functions. SL-SMS users still have access to the full library of functions provided by SL-GMS. Access to the library functions enables users to extend the functionality of SL-SMS as their requirements evolve. The use of States is not restricted to screen switching. The complex definition of custom State methods can be used to encapsulate responses to input Events without necessarily causing a screen switch. For example, an application might attach to the "right mouse button press" Event a meaning that corresponds to the mode in which it was executed: while in a "drawing" mode, continue current line while 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, the Event processing loop controlled by the SL-GMS Main Functions, and the State Manager.

The GISMO Manager

SL-GMS GISMOs (Graphical Interactive State Management Objects) provide a means of directly manipulating application

Version 6.2a- 26 May 2006

SL-GMS Reference E-1

data, displaying data, and defining other aspects of interactive button behavior. The GISMO Manager initializes required GISMO functions and coordinates the dispatching of Events received from GISMOs. The SL-GMS GISMO Library provides an extensive library of ready-to-use GISMOs which can be used, unaltered, simply by selecting the desired GISMO from a palette of SubModels. Because GISMOs are defined using standard SL-GMS objects, the SL-GMS GISMO Library can be expanded by copying a GISMO which most closely matches the desired behavior and editing its DynProp. The GISMO Manager is independent of the usual SL-GMS Event processing loop started with gmsMainLoop( ); it is initialized with a call to gmsInitGismos( ). More information about GISMOs is provided in Appendix A and Chapter 5 -- GISMOs.

The State Manager

SL-SMS manages a hierarchy of screen States. The State Manager handles, for example, automatic loading of Models, visibility of Models and Views, and determination of which Event callback functions should be available at any given time. This chapter explains the State Manager portion of SL-SMS in detail.

The SL-GMS Main Functions

The gmsMainInit( )1 and gmsMainLoop( ) functions are used in application programs to set up SL-GMS, create a Workstation/Window, handle Event processing including Window expose or resize Events, and call user-defined functions in response to certain input Events. Additional SL-SMS functions, used along with these functions, provide portable integration to various platform-windowing systems such as X or SunView. The SL-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( ). The argument argstr is of type "char*." It contains space-separated arguments.

Version 6.2a- 26 May 2006

SL-GMS Reference E-2

State-changing GISMOs Predefined

Three predefined State-changing GISMOs are provided with SL-GMS: SCREEN, DATSCREEN, and POPUP.

SCREEN

When a SCREEN GISMO is selected at run time, its Views and Models specified in its Renamed Variables are made visible upon activation.

DATSCREEN

The DATSCREEN GISMO, when selected, makes its Views and Models visible upon activation and, in addition, has its datflag renamed to ON, causing a ".dat" file to be read when the State Instance is activated.

POPUP

The POPUP GISMO, when selected, makes its Views and Models visible upon activation and, in addition, has its clearflag renamed to OFF, giving its Model the appearance and behavior of a popup menu.

Defined at Run time

STATE

A STATE GISMO is also provided with SL-GMS. When a STATE GISMO is selected at run time, it creates an Instance of a customized State class and makes its Views and Models visible upon activation.

Version 6.2a- 26 May 2006

SL-GMS Reference E-3

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 and query these flags are found in the State -- attributes section of the SL-GMS Function Reference. These flags are provided as a convenience; they control functionality which has been found useful in a wide variety of applications. The use of the attribute flags is not required; they can all be set to OFF, if desired. In addition, new flags can be added to the State Class structure. State Attributes Provided by the Generic State Class

State Attributes Description

autodeactflag

clearflag d1flag datflag

freeflag

gismoflag

if ON, upon G_LOC_PRESS of right mouse button, deactivate State Instance and reactivate its SuperState ("pop" the stack). Default value: ON if ON, clear View upon activate, before making the State Instance's Models visible. Default value: ON if ON, read ".d1" file upon activate. Default value: OFF (not implemented) 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 if ON, free State Instance when the State Instance is deactivated. Normally set to ON for dialog boxes. Default value: OFF 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

Version 6.2a- 26 May 2006

SL-GMS Reference E-4

State Attributes Provided by the Generic State Class

(continued)

State Attributes

Description

popflag

st30flag

updflag

visflag

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 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 if ON, enable updates on State Instance. May be set in the suspend and reactivate methods. Default value: ON if ON, keep State Instance SuperState's Models visible when State Instance is activated. Default value: OFF

Building Custom State Class Objects

The generic State class object is distributed with SL-SMS. The generic State object serves as a prototype State object that couples together handling of an event that affects data, Datasources, and the graphical representation of the data on the workstation screen. It includes components proven to be useful in designing multi-screen applications. The generic State class data structure, distributed in the file "gms_sms.h", provides sufficient functionality that it can serve as the foundation for building user-customized State class objects. The generic State class object is copied and the new State object is customized by the application developers by deleting, modifying, and adding to the components provided in the generic structure.

Generic State class features

An Instance of the generic State class in SL-SMS includes:

Version 6.2a- 26 May 2006

SL-GMS Reference E-5

1. a Workstation/Window, a View, and a set of Models that are visible when a State Instance is active. Since there can be many concurrently active State Instances, there can be many concurrently visible Workstation/Windows, Views, and Models 2. a pointer to the generic State class which contains a set of State methods. Among the State methods are Event-handlers to 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 by the interaction of the Event attributes (e.g., the screen coordinates in the case of a Locator Event) and the active Workstation/Window and View. Also included in the State methods are functions which affect the State tree such as activate, deactivate, and suspend. 3. a set of Datasources that becomes active when a given State Instance is activated. In SL-SMS, Datasource objects automatically perform the necessary memory allocation for program variables and invoke gmsVarDefine( ) and gmsVarChanged( ) functions at appropriate times. When a State Instance is deactivated, Datasource objects automatically free memory. 4. a set of attributes that controls optional State Instance behavior. The attributes are flags which modify the manner in which the other three State Instance characteristics are implemented. A complete list of these flags appears in the section Attributes provided by the generic State Class on page -4. Although the above four represent the core components of a generic State Instance, a number of additional characteristics constitute the generic State Instance description: · a State variable by the name of "<Instance-name>_button_state" which can be used by an application, and a TextEdit object -- a Text Rectangle or Text object (one per Workstation/Window) that is used to echo characters typed at the keyboard. If no TextEdit object is defined for a Workstation/Window, no Keyboard or String Events reach any Event-handlers. Selection of a TEXTENTRY GISMO replaces the State Instance's TextEdit object with the GISMO selected.

·

Version 6.2a- 26 May 2006

SL-GMS Reference E-6

Upon initialization, SL-SMS internally performs the necessary functions to make three Instances of the generic State class structure, setting appropriate attribute flags to produce the three predefined State Instances, screen, datscreen, and popup. These three Instances are made available to users of SL-GMS via the SCREEN, DATSCREEN, and POPUP GISMOs 1 respectively. The three predefined State Instances have the following behaviors:

screen State

mouse button 3 deactivates (pops) the State opens ".dat" file closes ".dat" file reads ".dat" file until a blank line is encountered mouse button 3 deactivates (pops) the State mouse button 3 deactivates (pops) the State

datscreen State

popup State

The three Predefined State Instances are made available to users of SL-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 functions

The GISMO State-changing functions are called from GISMO dynamic descriptions; in other words, as arguments to call actions in an object's input (#) dynamics. The functions are:

1. Also through the gms_screen_state_invoke( ), gms_datscreen_state_invoke( ), and gms_popup_state_invoke( ) functions

Version 6.2a- 26 May 2006

SL-GMS Reference E-7

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 predefined States like datscreen, popup, and the generic screen State. The gms_state_invoke( ) function creates an Instance of a customized State class. The gms_state_return( ) function provides a simple method of "popping" a State Instance (i.e., deactivating it). The gms_quit( ) function is used to cause program termination. A complete description of the functions and their calling syntax can be found in the section SL-GMS GISMO Action Functions on page -81.

State class methods

Method Name definevars

Typical Behavior called in between the Model Get operation and the DynInit operations during the gmsActivate( ) function · perform special variable-handling operations, before the gmsDynInit( ) function is called · useful when using State Variables ( gmsStVarDefine( ) ) sent to State when State is activated (i.e., added to the State tree) · application-specific behavior, such as establishing links with data sources sent during the cloning process to permit the new class to copy from another State's fields 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

activate

copyfrom customfree

Version 6.2a- 26 May 2006

SL-GMS Reference E-8

Method Name deactivate

Typical Behavior sent to State when State is deactivated1 · undo any special actions performed in activate, such as freeing objects or removing links to data sources. sent to State when a SubState is activated · suspend updating · disable data bindings sent to State when a SubState is deactivated · resume updating · re-enable data bindings sent to each active State when a Timer Event is received · determine new application variable values · perform gmsVarChanged( ) on variables whose values have changed

suspend

reactivate

update

1. The deactivate method never is invoked for the top State; if an application exits, the top State notification occurs in the win_destroy method rather than the deactivate method.

State class methods, if used, must be declared in the State class source code file with the exact method names used in the preceding table. Provided as a guide, the table shows some typical steps performed in the various State methods. The user is not restricted to this list of steps.

State tree inheritance

Six types of State class methods may be defined in customized State modules:

Version 6.2a- 26 May 2006

SL-GMS Reference E-9

State Class Method Inheritance Inherited by SubStates yes

Method Type Input Event-handler methods (Event-handler callbacks executed in response to a Locator, Keyboard, or String Event) Window Event-handler methods (Event-handler callbacks executed in response to a Window Event) update method (the method which typically modifies variables driving screen objects and calls gmsVarChanged( )) 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) Notrecognized methods (executed when the State receives a message that it does not recognize) 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)

no

no

no

no yes

State tree inheritance is the capability for a SubState to use a method provided in a SuperState. As seen in the table above, two method types can inherit methods from their SuperState: Input Event-handler and User-defined methods. It follows that redefining such methods within a SubState that exists in its SuperState has the effect of defining a different response 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.

Version 6.2a- 26 May 2006

SL-GMS Reference E-10

Notrecognized methods

A State can now provide notrecognized methods that are executed when the State receives a message that it does not recognize. Three notrecognized methods are provided: notrecognized, notrecognized1, and notrecognized2, taking zero, one and two arguments, respectively. Examples of these methods are shown below: static int notrecognized (state, messagename) idCLASS state; char *messagename; { return gmsStStrMsg(state->client, messagename); } static int notrecognized1 (state, messagename, arg1) idCLASS state; char *messagename; int arg1; { return gmsStStrMsg1(state->client, messagename,arg1); } static int notrecognized2 (state, messagename, arg1, arg2) idCLASS state; char *messagename; int arg1; int arg2; { return gmsStStrMsg2(state->client, messagename, arg1, arg2); }

Version 6.2a- 26 May 2006

SL-GMS Reference E-11

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 handling

SL-SMS allows a State method to be defined for each type of Event generated at the Workstation level, as described in Chapter 7 -- Event Handling. NOTE: When using SL-SMS only the event codes listed in the table below can be used. State class Event-handler methods must be declared in the State class source code file with the exact names used below. The State methods are shown with their corresponding Event codes: Valid Event-handler Methods Method Name loc_press loc_release loc_motion key_press key_release key_filter str_done win_expose win_resize win_focus_in win_focus_out win_enter Event code G_LOC_PRESS G_LOC_RELEASE G_LOC_MOTION G_KEY_PRESS G_KEY_RELEASE G_KEY_FILTER G_STR_DONE G_WIN_EXPOSE G_WIN_RESIZE G_WIN_FOCUS_IN G_WIN_FOCUS_OUT G_WIN_ENTER

Version 6.2a- 26 May 2006

SL-GMS Reference E-12

Valid Event-handler Methods

(continued)

Method Name win_leave win_map win_unmap win_destroy win_destroy_override

1

Event code G_WIN_LEAVE G_WIN_MAP G_WIN_UNMAP G_WIN_DESTROY

1. A "win_destroy_override" method can be defined for a State but there is no corresponding event code.

Example

static int loc_motion (state, event) id state; id event; { unsigned int mod; /* only print data for loc_motion Event 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; }

Version 6.2a- 26 May 2006

SL-GMS Reference E-13

The first argument of every State Instance's Event-handler callback is a pointer to the State Instance itself, which permits callback functions to query 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 of object 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 upon the Workstation/Window and View in which they occur. In addition, SL-SMS checks within the State Instance's Model to determine whether the selected object is a GISMO. If the object is a GISMO, its dynamics are executed and no further processing is done for that Event. Keyboard Events are dispatched to a particular State Instance based upon the Workstation/Window in which they occur and the State Instance's location in the State tree. The Event is given to the most recently activated State Instance which has a TextEdit object. Function Key events are treated as Keyboard Events and can be used to trigger GISMO Actions by using the function gmsFKeyProcess( ). A String Event is dispatched following a series of Keyboard Events ending in a Keyboard Event with an Event code of XK_Linefeed. (A complete list of XK_ key symbol codes is provided in the "keysymdef.h" file in the lib directory.) NOTE: If no TextEdit object is defined using the gmsTextEditObj( ) or gmsTextEditObjName( ) functions for a Workstation/Window, neither Keyboard Events nor String Events are sent to any State Instances. For Window Events, State methods are invoked when a WinEvent object is received for a State Instance's Workstation/Window. In this way, SL-SMS automatically manages the many Events received by a multi-Win-

Version 6.2a- 26 May 2006

SL-GMS Reference E-14

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 perform cleanup tasks before exiting. A return value of -1 indicates that the State in question has not only deactivated itself but also a SuperState(s). As a result, the processing of the custom win_destroy( ) Event handler method is aborted because some of the SL-SMS States still to be processed may no longer exist. This situation is not common but may occur under certain conditions. For example, an SL-SMS State controlling an SL-GMS Model may handle the win_destroy( ) method by deactivating both itself and its SuperStates that control the relevant SL-GMS Workstation and View. In this case, since the SuperStates were deactivated from a SubState, the processing of the win_destroy( ) Event handler method must be aborted, since the SuperStates no longer exist to receive the win_destroy( ) method. In some cases, it may be necessary to inhibit the window destroy. For example, a State may require additional user input before exiting. To allow this, a new method, win_destroy_override( ), is now supported. Before a window is destroyed, the win_destroy_override( ) method is executed in all States that use the window and in all SubStates of those States. SubStates receive the win_destroy_override( ) callback even if they use a different window from the window being destroyed. If the win_destroy_override( ) method for any State or SubState returns a non-zero value, the window is not destroyed. In this way, each affected State or SubState has the opportunity to "cancel" the pending window destroy. If all win_destroy_override( ) methods return 0 (zero), all affected States are deactivated and the window is destroyed. If a State Instance's Class does not implement a Locator, Keyboard, or String Event method, the State Instance inherits the method from its SuperState. All other Event methods are not inherited. More information about Events in SL-SMS is provided in Chapter 7 -- Event Handling.

Version 6.2a- 26 May 2006

SL-GMS Reference E-15

Implementation of Exemplar cloning for State Classes

The process of creating SL-GMS State Instances includes the ability to use a State Class "Exemplar." The Exemplar does not have to be defined; it is optional. The Exemplar is never activated, either; it is simply used as a template for storing default attributes. The Exemplar is a single pre-defined State Instance which is associated with the generic State Class. Creation of State Instances of that Class is done by "cloning" the State Class Exemplar. This provides a mechanism whereby default attributes may be established for a State Class and assigned automatically whenever an Instance of that class is created. The Exemplar State Instance is usually defined during the initialize( ) function for a particular State Class. This is done by simply calling the gmsStateInst( ) function and assigning the Instance name to be the same as the class name. Each time a subsequent gmsStateInst( ) function call is made to create an Instance of the State Class, it first looks to see if the Exemplar can be found. If so, the new State Instance is created by cloning the Exemplar; if not, a simple Instance is created with the standard default attributes. The process of cloning the Exemplar to create a new State Instance involves creating a simple Instance and then copying all the standard State attributes, such as "freeflag", "clearflag", and so on. The names of Models and Views are copied; pointers are not. Only the attributes of the standard State structure are copied; all "custom" State fields are set to 0. The State Class can be defined so that additional State fields are copied to the new Instance by providing a copyfrom method. The method is invoked during the cloning process to permit the class to copy other State fields. This method is defined as follows: static int copyfrom (state1, state2) idCLASS state1, state2; { state1->customfield = state2->customfield; return 1; }

Version 6.2a- 26 May 2006

SL-GMS Reference E-16

Any necessary information may be copied from the Exemplar in this manner in a custom copyfrom method. As noted above, the Exemplar is usually created in the initialize( ) method of 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>

Version 6.2a- 26 May 2006

SL-GMS Reference E-17

. return 1; }

Side effects of implementing the Exemplar

The Exemplar is an optional State which is never to be updated. Thus, the user may or may not create the Exemplar, and, if it is created, may or may not reset its attributes. If an Exemplar exists, all State Instances of that State Class (created after the Exemplar) will copy its attributes. However, if the user has an application, created before the existence of the Exemplar, and if that application was implemented using a State Instance with the same name as the State class, that State Instance will become the Exemplar, and any State Instances created after it will copy its attributes. The difference between the old and the new applications will be that the State Instances created in the new application may not receive default SL-SMS attributes, but attributes from the Exemplar instead. If the Exemplar 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 subsequently-created State Instances. The old application will have State Instances with default SMS attributes and the new application will have State Instances with the Exemplar attributes. The difference in these attributes could lead to divergent behavior. A simple fix for this divergent behavior problem is for users to rename any State Instances which currently have the same name as the State Class. This renaming would have to occur not only in the gmsStateInst( ) call, but also anywhere the State Instance's name was used, including calls to gmsStFindByName( ), Renamed Vars in Models, and so on.

Version 6.2a- 26 May 2006

SL-GMS Reference E-18

Using the State Message Debug flag

To facilitate the development of custom State Class objects, the function gmsStDebugFlag( ) is provided for inclusion in the developer's code. This function provides the means to control tracing of messages between State 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 cases, however, using the SL-SMS approach is more straightforward and is therefore recommended. In SL-GMS, a single function, gmsWSEventFctn( ), is used to establish a callback function for an Event on a particular Workstation/Window: int gmsWsEventFctn (workst, eventcode, fctn) id workst; /* Workstation which is to receive Event */ 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 basis by passing the object pointer for the desired Workstation/Window (workst). In SL-SMS, the gmsInitState( ) function calls gmsWsEventFctn( ) once for every Event type listed in the table, Valid Event-handler Methods on page -12, in order to set up the Event-handlers that dispatch Events to GISMO action functions or State class methods. NOTE: The function gmsWsEventFctn( ) must not be called in applications that use gmsInitStates( ), as GISMOs will not function properly.

Version 6.2a- 26 May 2006

SL-GMS Reference E-19

All Event handlers may be established by using this function except for one: the Event handler for String Events. To define an Event handler for String Events gmsWsTestEditObj( ) should be used: int gmsWsTextEditObj(workst, textobj, maxchars, promptstring, initstring, dispatch_mode, fctn) id workst; /* Workstation which is to receive Event */ id textobj; /* id of Text/TextRect object */ int maxchars; /* max chars to display */ char *promptstring; /* prompt string */ char *initstring; /* initial string to display with prompt */ int dispatch_mode;/* dispatch_mode = G_MULTI_EVENT/G_ONE_SHOT/G_ONE_SHO T_CLEAR */ int (*fctn) ( ); /* callback function to be invoked upon Event */ Each Workstation/Window created manages a single window-manager window. At present, multiple window-manager windows are handled by creating multiple Workstation-Window objects. Creating multiple Workstation-Window objects does not produce any practical limitations.

Version 6.2a- 26 May 2006

SL-GMS Reference E-20

F

Introduction

Datasource Management

The SL Datasource Management System (SL-DMS) is a service provided by SL-GMS to simplify the interconnection of application data and SL-GMS screen objects. The design intent of SL-DMS is ultimately to eliminate programming required to connect with external data sources or internal variables. This elimination of programming facilitates the use of graphics screens driven by 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, memory allocation, and variable modification. A table is set up in memory which connects an application's data directly to SL-GMS screen-control objects. This table approach updates screen elements only when their underlying data changes. Each Datasource may be conceived as a collection of variables and a set of methods to operate on them. Many Datasources may exist in a given application, and can be activated and deactivated according to the needs of the program. SL is working closely with application developers to determine the best possible interface for SL-DMS. At present, Datasources are created and accessed by using the functions described in the Datasource sections of the SL-GMS® Function Reference.

Version 6.2a- 26 May 2006

SL-GMS Reference F-1

Datasource classes and Instances

The Datasource class serves as a template for creation of Datasource Instances. The Datasource class also defines a set of methods to manipulate 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 structure; each maintains a linked List of Variable Definition objects called VarDefs. In addition, Datasource classes and Instances have a name field which 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, such as step and random, which modify those variables. Typically, ".dat" files are used to generate test data when prototyping. The ".dat" file is also used as a Datasource description file for Simulation Datasources. More information about the syntax of ".dat" files is provided in the section Previewing dynamics of the SL-GMS Quick Reference. Information about using ".dat" files is provided in the section Previewing the Dynamic 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 simulation Datasource. Additional Datasources will be supplied in a future release of SL-GMS. If necessary, however, customized Datasources may be created 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 invoking an Instance of the simulation Datasource.

Version 6.2a- 26 May 2006

SL-GMS Reference F-2

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. This data file should use the same syntax described in the section Previewing the Dynamic Behavior of Objects on page 3-61. If SL-DMS encounters an error in a ".dat" file, an error message is generated as shown in the following example: ERROR: file "xradial.dat", line 1: syntax error in data spec command Currently, Datasource activation routines are placed directly in the State class activate method. Additional information about using Datasources with SL-SMS is provided in Appendix E.

On-line examples "gms_dms.h" file

The header file "gms_dms.h" distributed in the lib subdirectory provides two structures which define the Datasource class and minimal Datasource objects. The class Definition is used by SL-DMS for managing Instances of Datasource objects and should not be modified directly by Datasources or applications. In addition, the Datasource object's "required fields" (defined as "G_DATASOURCE_FIELDS") should only be modified by SL-DMS. However, each Variable Definition (VarDef) in the idLinkRef vardefs field provides an id ds_pointer field which is available for Datasource use.

Version 6.2a- 26 May 2006

SL-GMS Reference F-3

"simpleds.c" file

The "simpleds.c" file distributed in the dmstest subdirectory of the demo directory sets out the definition of an elemental "hello world" Datasource object: 1. The simpleDs structure contains only G_DATASOURCE_FIELDS which are required by SL-DMS. the

2. Only two methods are defined (activate and update), each of which perform something basic, but demonstrable, to all attached 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. Nested objects (VarDefs, in this case) are output according to their own class tables. 4. The global initialization function simpleDsClassInit( ) creates the simpleDs Datasource class using gmsDsClass( ); it advertises its interfaces and class tables with the gmsClassAddMethod( ), gmsClassAddDumpTable( ), and gmsClassAddM1Table( ) functions and finally calls gmsDsClassInstall( ).

"simpletest.c" module

The program "simpletest.c" distributed in the dmstest subdirectory of the demo directory presents a simple test for simpleDs. A simple Model referencing two variables (ival and dval) is loaded into SL-GMS and a single Instance of simpleDs is created, given two VarDefs, and activated. A Locator Event-handler is registered to trigger updates, and gmsMainLoop( ) is called.

"filetest.c" modules

The code provided in "fileds.h", "fileds.c", "filedsvar.c", and "filetest.c" presents a more complex example Datasource, which expands on the required G_DATASOURCE_FIELDS and attaches an additional object, fileDsVar, to each VarDef.

Version 6.2a- 26 May 2006

SL-GMS Reference F-4

"filetest.c" file

The test program "filetest.c" exercises not only fileDs but the gmsDsList*( ) interfaces.

"fileds.h" file

The header file "fileds.h" provides the structure definitions for fileDs and fileDsVar. The fileDs structure adds filename, format, and fp fields to G_DATASOURCE_FIELDS for Instance-level reference. Per-variable information is kept in the fileDsVar object.

"fileds.c" and "filedsvar.c" files

The function provided within "fileds.c" creates a Datasource class with six methods, and ends its global initialization function by invoking the function provided within "filedsvar.c".

Version 6.2a- 26 May 2006

SL-GMS Reference F-5

G

Introduction

Linking SL-GMS applications

This appendix describes the SL-GMS Run-time Function libraries and how an executable SL-GMS application is created.

Components of the SL-GMS Run-time Function Libraries

User Application Program or SL-GMSRUN libgms smsmap SL-GWS workstationspecific interface

Models

SL-GMSDraw or SL-GML

user-callable function library

user-callable Mapping application function library

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 two layers: 1. libgms is the central library which consists of all the C functions 1 needed to construct complex graphical Models, manipu1. Complete Ada, FORTRAN, and Pascal interfaces are also provided for libgms.

Version 6.2a- 26 May 2006

SL-GMS Reference G-1

late their size and position, modify screen States, or maintain external data sources. Models are read into application programs by functions from libgms that are linked with program code. At link time, the functions required by Models, as well as functions required to interface the program code, are extracted from libgms and become 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 of graphical objects and the comprehensive handling of hierarchical Models built-up from the objects (on-line as: libgms) SL-GMD -- Graphical Modeling Dynamics cluster of functions that support the coherent binding between application variables and screen object(s) or screen-object elements (online as: libgmd) SL-DMS -- Datasource Management System cluster of functions required to simplify the set up and maintenance of specifications for external data sources, such as conventional files, live data feeds, or other programs and/or applications code; libdms also includes transparent functions required to support specific proprietary products such as BASEstar from DEC, Nexpert Object from Neuron Data, for example, 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-world environments where the management of many screens and/or application states is required; libsms, libsmsnew, libsmsnt, and libsmsxm make possible, for example, · initialization

Version 6.2a- 26 May 2006

SL-GMS Reference G-2

·

the codeless switching and management of screen states to achieve nesting, sequencing, and branching within sets of screens data source manipulation, dialog handling zoom,pan,layering control

· · ·

libsms, libsmsnew, libsmsnt, and libsmsxm also support true multiple-concurrent states running under a single process, or under multiple processes (online as: libsms, libsmsnew, libsmsnt, and libsmsxm) SL-OOE -- SL Object Oriented Environment kernel which provides object-oriented resources that manage and control the outer architecture, as well as independent messaging, encapsulation, dynamic binding, and inheritance. 2. SL-SMSMAP is the Mapping application library of functions that provides the developer with the capability of creating interactive, animated graphics that satisfy the needs of map and network based applications. The graphics integrate into both X-based and Microsoft Windows (NT & 95) systems. 3. SL-GWS is the Graphics Workstation System, supported by its own set of functions in libgws. This outer layer contains independent clusters of low-level protocols and functions that may be seen as virtual workstations. Each cluster provides specific support for an increasing variety of platforms, graphics boards, devices, graphics standards, windowing conventions, raster (bitmap) capabilities, and operating system idiosyncrasies. Confining such functions to this layer greatly simplifies transportability without disturbing the higher-level structures of SL-GMS. As illustrations, there are virtual workstations for X Window, DECwindows, and others.

Version 6.2a- 26 May 2006

SL-GMS Reference G-3

PC-Intel

An executable SL-GMS application program is created by compiling the application source code modules and then linking the resulting binary files with the SL-GMS Run-time Function Libraries and the Windows NT Libraries.

Application Source Code Modules

SL-GMS Run-time Function Libraries

Windows NT Libraries

compile Application Binary Code Modules link

Executable SL-GMS Application Program

The SL-GMS Run-time Function $GMS_HOME\lib and are listed below.

Libraries

are

distributed

in

SL-GMS Run-time Function Libraries (Alphabetical Order)

Library Name "libdms.lib" "libgmd.lib" "libgms.lib" "libgws.lib" "libgwsnt.lib" "libsms.lib"

Description Data Management System Library Graphical Modeling Dynamics Library Graphical Modeling Functions Library Graphics Workstation Library NT Graphics Workstation Library Screen Management System Library

Version 6.2a- 26 May 2006

SL-GMS Reference G-4

SL-GMS Run-time Function Libraries (Alphabetical Order)

(continued)

Library Name libsmsmap.lib libsmsnew.lib libsmsnt.lib

Description Mapping Application Library Enhanced Screen Management System Library NT Screen Management System Library

An executable SL-GMS application program is created on PC-Intel systems using the nmake command. (This executable program reads the rules contained in a file called "makefile" to compile and link an application program.) Each SL-GMS on-line example program in the demo directory is distributed with a "makefile" file. Executing nmake in an on-line example subdirectory creates the executable program. Any "makefile" file in the demo subdirectories containing C programs2 can be copied and modified to create a new "makefile" file for compiling and linking an SL-GMS application written in C. Each "makefile" file distributed with the on-line examples is composed of two parts. The first part specifies · · the module order required for linking the SL-GMS Run-time Function Libraries and the Windows NT Libraries, and the system-specific options for compiling and linking application programs.

The second part specifies · the module order required for linking the application binary code modules,

2. The <non-C language> Interface Reference manuals provide complete information about compiling and linking applications in languages other than C.

Version 6.2a- 26 May 2006

SL-GMS Reference G-5

·

the SL-GMS Run-time Function Libraries and the system libraries used for linking (by using variables defined in the first part), and the application-specific options for compiling and linking (such as special compiler flags).

·

The partial link32 command line that results from the rules specified in "makefile" 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.lib libsmsnew.lib libsms.lib libgmd.lib libdms.lib libgms.lib libgws.lib libgwsnt.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.

Version 6.2a- 26 May 2006

SL-GMS Reference G-6

Sun systems

An executable SL-GMS application program is created by compiling the application source code modules and then linking the resulting binary files with the SL-GMS Run-time Function Libraries and the X Libraries.

Application Source Code Modules

SL-GMS Run-time Function Libraries

X Libraries

compile Application Binary Code Modules link

Executable SL-GMS Application Program

The SL-GMS Run-time Function $GMS_HOME/lib and are listed below.

Libraries

are

distributed

in

SL-GMS Run-time Function Libraries (Alphabetical Order)

Library Name "libdms.a" "libgmd.a" "libgms.a" "libgws.a" "libgwsx.a" "libgwsxt.a"

Description Datasource Management System Library Graphical Modeling Dynamics Library Graphical Modeling Functions Library Graphics Workstation Library X Graphics Workstation Library Xt Graphics Workstation Library

Version 6.2a- 26 May 2006

SL-GMS Reference G-7

SL-GMS Run-time Function Libraries (Alphabetical Order)

(continued)

Library Name "libsms.a" libsmsmap.a libsmsnew.a libsmsxm.a

Description State Management System Library Mapping Application Library Enhanced Screen Management System Library X and Motif Enhanced State Management System Library

An executable SL-GMS application program is created on Sun systems using the SunOS make utility. (This utility reads the rules contained in a file called "Makefile" to compile and link an application program.) Each SL-GMS on-line example program in the demo directory is distributed with a "Makefile" file. Executing make -n in an on-line example subdirectory displays the link line required to create the executable program. Any "Makefile" file in the demo subdirectories containing C programs 3 can be copied and modified to create a new "Makefile" file for compiling and linking an SL-GMS application written in C. (Developers of Motif applications should use the "Makefile" file in the demo/gms_motif directory. 4) Each "Makefile" file distributed with the on-line examples is composed of two parts. The first part specifies · the module order required for linking the SL-GMS Run-time Function Libraries and the X Libraries, and

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.

Version 6.2a- 26 May 2006

SL-GMS Reference G-8

·

the system-specific options for compiling and linking application programs (for example, whether or not to use shared libraries 5).

The second part specifies · · the module order required for linking the application binary code modules, the SL-GMS Run-time Function Libraries and the system libraries used for linking (by using variables defined in the first part), and the application-specific options for compiling and linking (such as special compiler flags).

·

The partial cc linker command line that results from the rules specified in "Makefile" 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 the rules 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 that result are not shown in the command lines above. The smsmap library is only required if the application utilizes the SL-GMS Mapping Application Library.

5. All executables distributed with SL-GMS are linked with stand-alone X libraries using the -Bstatic option.

Version 6.2a- 26 May 2006

SL-GMS Reference G-9

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-11 creating 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-2 definition .............................2-11, F-2 fontdef.dat.................................... 9-5 .def files definition .................................... 2-13 .dxf files............................. 2-5, 10-6, D-4 definition .................................... 2-11 .g files conversion to .m1 ...................... 12-5 definition ...........................2-12, 2-13 editing ........................................ 12-2 .i files definition .................................... 2-12 .m1 files changes not saved...................... D-2 conversion to .g ......................... 12-5 definition .................................... 2-13 .m2 files ................................... 11-2, D-2 definition .................................... 2-13 format......................................... 11-3 loading........................................11-3 saving.........................................11-3 .p1 files definition.....................................2-13 .ps files definition.....................................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

Numerics

0 (unselected), gms_toggle_array( ) 5-25 1 (selected), gms_toggle_array( ) ....5-25

A

-a option, AutoCAD ........................... D-4 action range ..........................................3-43 range scaling..............................3-43 Action Functions GISMO ............................... 5-5, A-53 action keyword, definition of...............3-7 action, dynamic conditional ....................................3-8 definition of...................................3-2 implicit ..........................................3-8 unconditional ................................3-8 activate method........................E-8, E-10 Ada programming language applying to C on-line examples ....1-1 animation double buffering .........................3-48 dynamic description ...................4-39 graph ..........................................4-14 Model .........................................4-10 smooth .......................................3-48 application building...........................12-7 application data ................................. F-1

Version 6.2a- 26 May 2006

SL-GMS Reference i

Index

application Xt event-loop function external to SL-GMS .................... C-2 Apply Xform ..................................... 11-2 array variables ................................. 11-5 in dynamic descriptions ............. 3-52 ASCII data files ................................ 2-11 ASCII save of Models m1g conversion script.................. 2-5 ASCII screen-description files.......... 2-12 ASCII to binary conversion .............. 12-6 aspect ratio ........................................ 8-7 AutoCAD -a option...................................... D-4 -c option ...................................... D-4 -cf option ..................................... D-4 color ........................................... 10-5 -d option...................................... D-4 -e option...................................... D-4 -f option....................................... D-4 files, conversion of ............... 2-5, D-4 -t option....................................... D-5 autodeactflag, in generic State ..........E-4 autoscale Graphs............................... 4-6 axis labeling ....................................... 4-4 in DynProp .............................. A-109

C

C language programs................G-5, G-8 -c option, AutoCAD ........................... D-4 C++ programming language applying to C on-line examples ....1-1 caching SubModels........................11-19 CALL GISMOs .................................. A-4 callback Keyboard Event......................... E-14 Locator Event ............................ E-14 String Event............................... E-14 Window Event ........................... E-14 Cartographic Roman font underscore character ...................9-4 cc linker .............................................G-9 -cf option, AutoCAD .......................... D-4 Chart dynamic......................................3-21 CHECK button........................ 5-15, A-24 Clear Redraw Mode .........................3-50 clearflag, in generic State.................. E-4 click (mouse), definition of..................1-1 colarr4 GISMO ................................ A-78 color AutoCAD ....................................10-5 change in Model.........................12-2 Common Desktop Environment .10-7 definition files .............................10-2 modification ..........................10-3 index...........................................10-2 management ..............................10-1 palette changing...............................10-2 per Workstation ..........................10-1 PostScript...................................10-4 colorcells GISMO ............................ A-77 COLORCELLS GISMOs ................. A-76 colordef.acad file ..............................10-5

B

background grid Graphs ................................4-3, 4-18 Bar Graph .......................................... 4-3 batcherase dynamic action .............. 3-46 behaviors, State Instance ..................E-7 binary to ASCII conversion .............. 12-6 bitplane mask................................... 10-3 bracket character in Simple Roman font .................. 9-4 Bstatic link option.............................. G-9 button causing event.......................... 7-4 BUTTON GISMO ...............................A-3 BUTTON GROUP GISMOs .............A-24 button_state .......................................E-6

Version 6.2a- 26 May 2006

SL-GMS Reference

ii

Index

colordef.cde file................................ 10-7 colordef.dat files............................... 10-2 format of..................................... 10-2 colordef.grey files............................. 10-4 command file error ........................................... 12-2 naming ....................................... 12-2 command files see .g files command interpretation ................... 12-1 compiling application source code .............. G-4 compiling, application source code... G-7 Composite Graph............................... 4-4 conditional dynamic action definition of .................................. 3-8 Conditional dynamics..................... 11-13 Contiguous binary-executable screen-description files .............. 2-13 conversion ASCII to binary........................... 12-6 binary to ASCII........................... 12-6 of Model files...................... 12-5, D-1 conversion routines for date and time values ............ 4-23 converting Model files ...................... 12-5 coordinate systems conversion example ..................... 8-2 World Coordinate System ............ 8-4 coordinates in ".g" file .................................... 2-12 Internal Coordinate System ......... 8-2 coordlimits........................................ 4-26 GraphTrace................................ 4-30 copyfrom method..................................E-8 customfree method................................E-8 customized State function definition .......................A-22 customized State class creation ........................................E-8 CYCLE GISMOs ............................. A-37 cycle1 GISMO ................................. A-38 cycle2 GISMO ................................. A-38

D

-d option, AutoCAD ........................... D-4 d1flag, in generic State ..................... E-4 data application ................................... F-1 as collection of variables ............. F-1 file used as Datasource............... F-3 methods to operate variables...... F-1 sent to screen-controlled objects F-1 data files, see .dat files data linkage........................................2-4 Data Management System Library....G-4 Datasource and SL-SMS................................ F-3 Class ........................................... F-2 in State Instances........................ E-6 Instances of................................. F-2 objects freeing memory ..................... E-6 memory allocation ................. E-6 see also Preview simulation .................................... F-2 types of........................................ F-2 Datasource Management System (SL-DMS) ............................ F-1, G-2 Datasource Management System Library ............................G-7 date as axis on Graph ........................4-18 conversion routines ....................4-23 datflag, in generic State .................... E-4 DATSCREEN GISMO ................A-7, E-3 datscreen State behavior .................. E-7 dbflag flag.........................................3-49 DC (Device Coordinate) .....................8-2 deactivate method....................E-9, E-10

Version 6.2a- 26 May 2006

SL-GMS Reference

iii

Index

default double-buffering Mode............... 3-50 files default settings..................... 2-13 Text fonts ..................................... 9-3 for SL-GMS ............................ 9-1 default window position...................... 8-9 definevars method .............................E-8 demo directory (SL-GMS)......... G-5, G-8 Device Coordinates ........................... 8-2 dispatching X events......................... C-2 display assembly area double buffering ......................... 3-48 display dynamics definition of .........................3-6, 3-11 DISPLAY environment variable ........ C-3 display process, streamlining........... 11-9 displaying a Model ............................. 8-4 double buffer option ......................... 3-49 double buffering ............................... 11-4 animation ................................... 3-48 hardware .................................... 3-48 marking for in SL-GMSDraw ...... 3-49 Modes ........................................ 3-50 software ..................................... 3-48 to minimize flicker ...................... 3-48 dummy variables.............................. 4-31 dxf2g conversion script.................2-5, 10-5 utility................................... 10-5, D-4 dynamic action action types.................................. 3-5 definition of .................................. 3-2 examples ..................................... 3-2 move ............................................ 3-2 types Attribute.................................. 3-5 Graph ..................................... 3-6 Icon Switch............................. 3-6 Point Changes ....................... 3-5 Text ........................................3-5 Transformation .......................3-5 User-defined...........................3-6 dynamic behavior .............................. F-2 dynamic descriptions adding to Model object ...............3-44 array variables............................3-52 definition of...................................3-6 Dynamic Properties......................3-6 expressions in ............................3-34 format of .....................................3-27 function calls in...........................3-34 ranges in ....................................3-43 Renamed Vars ...........................3-57 syntax for display .......................3-27 trigger .........................................3-30 unconditional .................... 3-27, 3-28 value, conditional .......................3-28 dynamic expression definition of...................................3-7 evaluation...................................3-52 expression element ....................3-10 valid elements ............................3-10 dynamic graphical objects..................3-2 dynamics actions........................................3-28 display ..........................................3-6 driven by array variables 3-52, 11-10, C-1 driven by structure variables ......3-53 GISMO .........................................5-2 in non-replicating SubModels...11-16 input ...........................................3-11 optimized.................11-9, 11-10, C-1 dynarray dynamic action ..................3-52 DynProp attached to a GISMO ...................5-2 attached to GISMO ....................3-11 attached to Group ................... A-115 conditional dynamics................11-13

Version 6.2a- 26 May 2006

SL-GMS Reference

iv

Index

definition .............................2-3, 3-29 display dynamics ....................... 3-11 example ..................................... 3-36 example GISMO ........................A-32 execution order .......................... 3-33 expression ............................... 11-13 GISMO......................................... 5-3 hierarchy .................................... 3-33 highlighting a GISMO................... 5-5 input dynamics........................... 3-11 maximum length of .................... 3-29 optimizing memory space ............ 5-5 Samples..................................... 3-29 SL-GML versus SL-GMSDraw... 3-29 space between = and * .............. 3-29 specifying in SL-GMSDraw .......... 3-6 state_0 ("unselected") object ...A-115 state_1 ("selected") object .......A-113 structuring for optimization....... 11-13 European, versions of SL-GMS .......2-14 Event-handlers ...................................7-1 callback arguments ................... E-14 in SL-SMS ....................................7-1 in State class............................... E-9 methods .................................... E-12 Events codes............................................7-3 Event Query functions..................7-6 event query functions, examples..7-7 input handler methods............... E-10 modifier codes..............................7-4 processing loop ........................... E-2 processing sequence ...................7-1 query functions, using ..................7-7 timer ...........................................7-12 types of...................................... E-14 Window ..................................... E-14 ewidth action, example.....................3-31 example, trend Graph ......................4-12 expose Event .................................... E-2 expression element dynamic expression ...................3-10 expressions in dynamic descriptions...... 3-7, 3-34 valid elements in ........................3-10 Extent eliminating calculation of ..........11-15 for an object .............................11-14 externally-created window................8-13

E

-e option, AutoCAD........................... D-4 echo characters .................................E-6 ecolor action, example..................... 3-32 edge (Line) style ............................A-118 edge color (ecolor).........................A-118 Edit Data File window ...................... 3-61 endsource keyword preview ...................................... 3-65 Enhanced Screen Management System Library................................. G-5, G-8 Erase Update Mode......................... 3-50 erasing objects................................. 3-45 error in command file.......................... 12-2 error 11 bad alloc............................. 3-49 error 9 bad drawable........................ 3-49 error message Preview ...................................... 3-41 estyle attribute ...............................A-118

F

-f option, AutoCAD ............................ D-4 f_call GISMO.................. A-4, A-5, A-112 f_dscrn GISMO ................................. A-8 f_fill GISMO..................................... A-41 f_popup GISMO .............................. A-11 f_quit GISMO .................................. A-14 f_return GISMO............................... A-16 f_scrn GISMO ................................. A-18

Version 6.2a- 26 May 2006

SL-GMS Reference

v

Index

f_slide GISMO .................................A-56 f_state GISMO .................................A-21 f_textv GISMO .................................A-68 fcolor attribute ................................A-118 file collection of Views and Models.. 2-13 Noncontiguous binary-executable screen-description.......... 2-13 optimized for run time screen-load performance ................... 2-13 PostScript formatted screen-description.......... 2-13 suffixes 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-2 Model file to SL-GML command file.................. 12-2 Model files.................................. 12-2 filetypes conversion ................................. 2-11 reserved suffixes........................ 2-11 SL-GMS ..................................... 2-11 fill color (fcolor) ..............................A-118 fill pattern for fill color on monochrome ...... 10-1 FILL PERCENT GISMOs.................A-40 flag batcherase example ............................... 3-47 repair example ............................... 3-47 flickering, unwanted ......................... 3-48 font Cartographic Roman.................... 9-4 default ..........................................9-3 default set for SL-GMS ............................9-1 defining.........................................9-5 Hershey........................................9-4 PostScript...................................9-14 precision 1....................................9-4 preloading ................................11-15 scalable ................................ 9-2, 9-7 Simple Roman..............................9-4 TrueType family names..............9-10 fontdef program (Windows NT) ........9-11 fontdef program (Windows)..............9-11 fontdef.dat file customizing ..................................9-5 format ...........................................9-5 PostScript Workstation...............9-13 Windows NT....................... 9-9, 9-11 X Window System ........................9-6 XFontSet platforms ......................9-7 formal variables, Graphs ..................4-15 format description strings, Graphs ...4-21 format, of dynamic descriptions .......3-27 formatting strings in GraphAxes .............................4-17 FORTRAN programming language applying to C on-line examples ....1-1 freeflag, in generic State ................... E-4 function calls in dynamic descriptions..............3-34 Function Libraries SL-GMS components..................G-1

G

g_struct_define( ) .............................3-53 g_struct_member_define( ) ..............3-53 G_WS_DBUFF_CLEAR...................3-50 G_WS_DBUFF_ERASE ..................3-50 G_WS_LOOKUP_COLORS ............10-7 X Workstation option ..................10-1

Version 6.2a- 26 May 2006

SL-GMS Reference

vi

Index

G_WS_NOPASTE Workstation option5-1 generic State Class attributes of ..................................E-4 genlocfile utility.............................. D-14 GISMO "f" style .........................................A-1 "m" style .......................................A-1 Action Function Library ................ 5-3 Action Functions ................ 5-5, A-53 definition of........................... 3-12 Action functions syntax...................................A-81 activation...................................... 5-1 arrow shape .................................A-2 BUTTON ......................................A-3 BUTTON GROUP ......................A-24 BUTTON GROUP definition ...... 5-15 BUTTON GROUP highlighting... 5-25 BUTTON type appearance ......A-112 BUTTON type construction5-7, A-112 CALL............................................A-4 COLORCELLS...........................A-76 compatibility with platforms ..........A-2 Constructing a "GISMO helper" . 5-16 constructing a CHECK GROUP. 5-24 constructing a RADIO GROUP .. 5-19 construction .................................A-3 customizing ................................ 5-26 CYCLE.......................................A-37 DATSCREEN...............................A-7 definition ...................................... 5-1 definition of .................................. 2-4 diamond shape ............................A-2 DynProp attached ........................ 5-2 DynProp syntax ........................... 5-3 FILL PERCENT .........................A-40 fixed dimensions ......................A-112 flat "f" style ...................................A-1 functions in................................. 3-12 helper constructing .................... 5-16 helpers ...................................... A-24 highlighting behavior ....................5-5 in SL-SMS ................................... E-1 input dynamics .............................5-2 Library ..................2-4, 5-1, 5-28, E-2 Manager ...................................... E-1 Model names............................... A-2 Motif "m" style ............................. A-1 MULTIPLE SELECTION ........... A-44 naming conventions .................... A-3 output dynamics ...........................5-2 POPUP...................................... A-10 predefined ................... 2-4, 5-1, 5-27 purpose ........................................5-1 QUIT.......................................... A-13 rectangular .................................. A-2 RETURN ................................... A-15 return value of Action functions....7-1 sample construction .....................5-7 scaling ..............................A-1, A-112 SCREEN ................................... A-17 SCROLLBOX ............................ A-44 scrolling functions.......................5-26 SLIDER ..................................... A-55 STATE....................................... A-20 State-changing ............................ E-3 State-changing functions in......... E-4 TEXTENTRY ARRAY ............... A-59 TEXTENTRY VAR .................... A-67 three dimensional look ................ A-1 TOGGLE ................................... A-32 toggle group ...............................5-15 user-defined function....................5-3 using...........................................5-26 GISMO action function "flash" behavior ......................... A-84 "stayon" highlighting................ A-100 color index variable, setting....... A-83 create generic State class......... A-94 create State Class..................... A-97

Version 6.2a- 26 May 2006

SL-GMS Reference

vii

Index

cycle a variable ..........................A-83 datscreen State class, creation..A-84 deactivate event State .............A-100 DynProp action ........................A-100 exit SL-GMS ..............................A-94 fill percent ..................................A-90 highlight object...........................A-85 highlight selected text ................A-92 highlight Text Rectangle ............A-93 interpolate ..................................A-98 locator press ..............................A-85 locator release ...........................A-81 move slider box........................A-101 radio button array.......................A-94 radio buttons, index ...................A-95 scroll ........................................A-105 set array element .....................A-106 set hiliteindex .............................A-96 slider ..........................................A-90 slider index...............................A-101 State class installation ...............A-99 text content ..............................A-104 text entry ..................................A-102 Text Rectangle.........................A-103 Text Rectangle Group..............A-104 toggle array element ................A-106 gismoflag and Event-handling...................... 7-1 in generic State............................E-4 Glossary, SL-GMS.....................B-1, G-1 gm1 conversion script................ 12-6, D-1 gm2 conversion script....................... D-1 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-84 gms_fpercent_var1( ) .............A-41, A-85 gms_hilite_color( )..............................5-6 gms_hilite_color( )........ A-27, A-33, A-85 gms_hilite_color_selobj( ) .....A-60, A-68, A-86 gms_hilite_color_var( )...........A-27, A-86 gms_hilite_cycle( ) ...........................5-13 gms_hilite_cycle( ) .................A-37, A-87 gms_hilite_edge( )........ A-27, A-33, A-87 gms_hilite_edge_selobj( ) .....A-60, A-68, A-88 gms_hilite_edge_var( )...........A-27, A-88 gms_hilite_flip( ) ........... A-27, A-33, A-88 gms_hilite_flip_var( ) ..............A-27, A-89 gms_hilite_fpercent1( )...........A-41, A-90 gms_hilite_percent1( )............A-56, A-90 gms_hilite_percent2( )............A-56, A-91 gms_hilite_vis( ) ..5-22, A-27, A-33, A-91 gms_hilite_vis_var( ) .... 5-24, A-27, A-92 gms_hilitescroll_array( ) .........A-53, A-92 gms_hilitescroll_var( ) .. A-46, A-53, A-93 gms_motif on-line example, resolving problem with making ...................G-8 gms_popup_state_invoke( )..A-10, A-93, E-8 gms_quit( ) ..................... A-13, A-94, E-8 gms_radio_array( )....... 5-22, A-27, A-94 gms_radio_var( ) .......... 5-23, A-27, A-95 gms_radioscroll_var( ).. A-46, A-53, A-96 gms_return( )..................................... E-8 gms_screen_state_invoke( ) .A-17, A-97, E-8 gms_slider_var1( ) .................A-56, A-98 gms_state_invoke( ).................A-20, E-8 gms_state_pop( ) ...................A-15, A-99

gms_

gms_call( ) ............................... A-4, A-81 gms_call1( ) .....................................A-81 gms_color_select( ) ............... A-77, A-82 gms_cycle_var( ) ................... A-37, A-83

Version 6.2a- 26 May 2006

SL-GMS Reference

viii

Index

gms_state_return( ) .........................A-99 gms_stayon( ) ..................................A-20 gms_stayon_call( ).........................A-100 gms_text_array_slider_highlight( )...A-46 gms_text_array_slider_hilite( )........A-53, A-101 gms_text_array_slider_var( ) A-46, A-53, A-101 gms_textentry_array( )...................A-102 gms_textentry_var( ).. A-60, A-68, A-103 gms_textload_array( ).......... A-60, A-104 gms_textscroll_array( )A-46, A-53, A-104 gms_textscroll_lines( )A-46, A-53, A-105 gms_toggle_array( )....5-25, A-33, A-106 gms_togglescroll_array( ) ..... A-46, A-53, A-106

gmsI

gmsInitGismos( ) ............................... E-2

gmsM

gmsM2Save( )..................................2-13 gmsM2XGet( ).................... 11-16, 11-19 gmsMainInit( ) ................................... E-2 gmsMainInitStr( )............................... E-2 gmsMainLoop( ) ................................ E-2 using in Xt interface..................... C-2 gmsMGSave( ) .................................2-12 gmsModCacheCapacity( )..............11-20 gmsModCacheCount( ) ..................11-20 gmsModDynInitVarDefTable( ).........11-7 gmsModInst( ) ..................................3-18 gmsModNonReplicate( ) ................11-15 gmsModPermanent( ) ........ 11-18, 11-19 gmsMSave( )....................................2-13 gmsMXGet( )...................... 11-16, 11-19

gmsA

gmsAddLibPath( ) ............................ 11-4 gmsAddUserFctn( ).................3-35, 3-39 gmsAllVarsChanged( )................... 11-10 gmsAutoUpdateMode( )................. 11-10

gmsN

gmsNDCScale( ) ................................8-3 gmsNoFlagsMode( ).......................11-10 gmsNPXY( ) .......................................8-3

gmsB

gmsBitmap( ) ................................... 2-12

gmsD

gmsDoubleBufferFlag( )................... 3-50 gmsDynInit( ) ................................... 11-7 gmsDynUpdArrayFlag( ) ................ 11-10 gmsDynUpdate( )............................. 11-6

gmsO

gmsObjFree( ) ...................... 3-48, 11-19

gmsP

gmsProcessLowEvent( ) X interface ................................... C-3 Xt interface .................................. C-2 gmsPSave( ) ....................................2-13 gmsPsLViewWrite( )............... 9-16, 9-18 gmsPsPolyMaxPoints( ) ...................9-18 gmsPsViewWrite( )................. 2-13, 9-16 gmsPsWsProcArgs( )............. 9-16, 9-18 gmsPsWsProcArgsStr( ) ..................9-16

gmsE

gmsExtentMode(............................ 11-14 gmsExtentMode( ) ......................... 11-10 gmsExternalEventLoopFlag( ) ...C-2, C-3

gmsF

gmsFindObject( ) ........................... 11-14

Version 6.2a- 26 May 2006

SL-GMS Reference

ix

Index

gmsS

gmsStFreeAllVarDefs( )................... 11-5 gmsStM2Flag( ) ............................... 11-4 gmsStVarDefine( ) ........................... 11-7 gmsSubModReplicateMode( ) ....... 11-15 customization of .........................3-22 designing new ............................4-14 dynamic......................................3-21 format description strings ...........4-21 GRAPHS subdirectory .................4-1 grid in .........................................4-18 Library ..........................................4-2 positioning ....................................4-1 Preview ......................................4-11 Reference Point ...........................4-1 renaming variables of...................4-4 SL Graph Library........................3-21 template ........................... 3-21, 4-14 designing ..............................4-14 tick marks .....................................4-4 types of.........................................4-3 Graph template ................................4-30 dummy variables ........................4-31 example of general structure......4-37 GraphAxes ............................... 4-2, 4-16 date and time .............................4-18 examples ..............................4-22 logarithmic....................................4-6 non-graphic components............4-26 object..........................................4-14 definition of ...........................3-22 rescaling.....................................4-27 types...........................................4-20 used as grids..............................4-18 variable limits ...............................4-5 variables.......................................4-5 Graphical Modeling Dynamics ..........G-2 Graphical Modeling Dynamics Library .................................G-4, G-7 Graphical Modeling Function ............G-2 Graphical Modeling Functions Library .................................G-4, G-7 Graphical Modeling Language (SL-GML) ...................................12-1 graphical Models

gmsT

gmsTPrec0RotFlag( ) ...................... 9-11

gmsU

gmsUpdate( ) ................................... 11-6 gmsUseShadowMode( ) .....11-10, 11-14

gmsV

gmsVarChanged( ) ............................ 4-6 gmsVarDefine( ) with optomized dynamics......... 11-14 gmsVarTypeDefine( )....................... 3-53 gmsVuRSave( ) ............................... 2-12

gmsW

gmsWCScale( ).................................. 8-2 gmsWinFlags( ) setting of G_WS_NOPASTE ....... 5-1 gmsWorkst( ) interfacing X................................ C-3 using in SL-GMS/Xt interface ..... C-1 gmsWsDefaultOpts( ) ...................... 10-7 gmsWsPort( )................................... 3-48 gmsWsPortXY( ) .............................. 3-48 gmsWsWind( ) ................................. 3-48 gmsWsWindXY( ) ............................ 3-48

gmsZ

Graph autoscale ..................................... 4-6 background grid ........................... 4-3 components of ............................. 4-2 creating ...................................... 3-21

Version 6.2a- 26 May 2006

SL-GMS Reference

x

Index

refining ....................................... 12-1 Graphics Workstation Library ... G-4, G-7 Graphics Workstation System .......... G-3 GraphTrace...............................4-3, 4-28 actual data variables.................. 4-31 coordlimits.................................. 4-30 dynamics in ................................ 4-31 multi-color .................................... 4-7 multi-linestyle ............................... 4-8 non-graphic components of ....... 4-30 object ......................................... 4-14 object definition with SL-GML .... 4-28 object, definition of..................... 3-22 objects loaded with array of data4-36 updating ..................................... 4-32 variables ...................................... 4-5 graphtrace command in SL-GML.................................. 4-28 grey-scale ........................................ 10-4 grid GraphAxes................................. 4-18 in graphs .................................... 4-18 Group DynProp example ...................... 5-23 GUI screen states ............................ 2-10 GWS-X.............................................. C-1 gwsx interface library ........................ C-1 GWS-XT ........................................... C-1 gwsxt interface library ....................... C-1

I

IC (Internal Coordinate)......................8-2 implicit dynamic action definition of...................................3-8 inheritance, of methods States ........................................ E-10 initialization, SL-SMS ........................ E-7 initialize function example..................................... A-22 input dynamics definition of.................................3-11 input-event action use of ...........................................5-4 instancing Models at run time ..................................3-18 Internal Coordinate System................8-2 Internal Coordinates...........................8-2 IPC (Internal Pixel Coordinate) ..........8-2

J

Japanese, versions of SL-GMS .......2-14

K

keep_aspect_flag( ) method...............8-7 key causing event ..............................7-4 KEY_FILTER callback........................7-6 key_filter method............................. E-12 KEY_PRESS callback........................7-6 key_press method........................... E-12 KEY_RELEASE callback ...................7-6 key_release method........................ E-12 Keyboard Event................ 7-6, E-6, E-14 keysymdef.h file .............................. E-14 Korean, versions of SL-GMS ...........2-14

H

helper button.................................... 5-16 Hershey font............................................... 9-4 highlighting behaviors GISMO......................................... 5-4 hole caused by erasures ................... 3-45

L

languages, non-C...............................1-1 libdms................................G-2, G-4, G-7 libgmd................................G-2, G-4, G-7

Version 6.2a- 26 May 2006

SL-GMS Reference

xi

Index

libgms ............................... G-2, G-4, G-7 libgws................................ G-3, G-4, G-7 libgwsnt............................................. G-4 libgwsx .............................................. G-7 libgwsxt ............................................. G-7 library central SL-GMS C functions ....... G-1 GISMO.......................... 2-4, 5-1, A-3 libsms................................ G-3, G-4, G-8 libsmsmap................................. G-5, G-8 libsmsnew ................................. G-5, G-8 libsmsnt............................................. G-5 libsmsxm........................................... G-8 link order for SL-GMS applications ..... G-6, G-9 link32 command................................ G-6 linking, binary files .................... G-4, G-7 load times compare M1 filer to M2 filer ....... 11-2 loc_motion method ..........................E-12 loc_press method ............................E-12 loc_release method .........................E-12 localization files Unicode..................................... D-14 localization of SL-GMS .................... 2-14 Locator Event........................... 7-6, E-14 m1g conversion script .......2-5, 12-6, D-1 m1m2 conversion script ...2-5, 11-4, D-1, D-2 ma_call GISMO................................. A-5 ma_popup GISMO .......................... A-11 Main Functions, SL-GMS .................. E-2 majorspacing....................................4-26 majorticks .........................................4-16 spacing.........................................4-4 make procedure file...........................G-5 make utility ........................................G-8 Makefile file .......................................G-8 makefile file .......................................G-5 mapping ............................................ E-1 Mapping Application Library......G-5, G-8 mapping_factor description....................................8-9 Marker in Graphs......................................4-3 maxtracelength.................................4-28 md_button Model DynProp .....................................5-19 md_call GISMO................................. A-5 md_dscrn GISMO ............................. A-8 md_scrn GISMO ............................. A-18 md_state GISMO ............................ A-21 memory allocation ............................. E-6 method activate...................................... E-10 deactivate.................................. E-10 definevars ..................................... E-10 Input Event-handler................... E-10 notrecognized............................ E-10 reactivate................................... E-10 suspend..................................... E-10 types of........................................ E-9 update ....................................... E-10 user-defined .............................. E-10 Window Event-handlers ............ E-10 minorspacing....................................4-26

M

m_call GISMO ...................................A-5 m_dscrn GISMO ................................A-8 m_fill GISMO ...................................A-41 m_popup GISMO................... A-11, A-16 m_quit GISMO .................................A-14 m_sboxm GISMO ............................A-48 m_sboxs GISMO .............................A-48 m_scrn GISMO ................................A-18 m_slideh GISMO .............................A-56 m_slidev GISMO..............................A-56 m_state GISMO ...............................A-21 m_textv GISMO ...............................A-70

Version 6.2a- 26 May 2006

SL-GMS Reference

xii

Index

minorticks......................................... 4-16 spacing ........................................ 4-4 mkpixmap: could not create pixmap message .................................... 3-49 Model display in external window ......... 8-13 displaying in a window ................. 8-4 file conversion............................. D-1 functions required ....................... G-2 instancing at runtime ............................. 3-18 nesting of ................................... 3-18 pan and zoom ............................ 8-13 portability ................................... 12-5 setting name of .......................... 8-12 SubModels used ........................ 3-16 transporting ................................ 12-5 Variable Definition tables ........... 11-7 window default position....................... 8-9 setting location on screen ...... 8-9 setting position ....................... 8-7 setting size of ......................... 8-8 Model creation optimization................................ 11-1 Model Dynamic Properties window.. 3-45 Model Properties window................. 3-44 model_name( ) method.................... 8-12 monochrome display........................ 10-1 Motif applications, instructions for compiling and linking .................. G-8 Motif GUI builder tool ........................ C-2 Motif standard ....................................A-1 Motif widget....................................... C-1 Motif, using SL-GMS with .................. 2-9 mouse click, definition of ......................... 1-1 enable middle button ................... 5-1 middle button to activate a GISMO......... 5-1 right button to activate a GISMO .........5-1 movex and movey actions, example 3-31 ms_call GISMO ................................. A-5 ms_dscrn GISMO.............................. A-8 ms_scrn GISMO.............................. A-18 ms_state GISMO............................. A-21 MULTIPLE SELECTION GISMOs .. A-44 multiple Views ..................................12-7 printing .......................................9-16

N

Native Control Objects .......................2-4 NDC (Normalized Device Coordinate) .8-1, 8-2 nested variables ...............................3-59 nmake command...............................G-5 noerase dynamic action ...................3-48 in non-replicating SubModels...11-17 noerase option .................................3-50 non-replicated SubModels .............11-15 Normalized Device Coordinate Scale Factor changing.......................................8-3 default value.................................8-3 Normalized Device Coordinates.........8-1 View extent...................................8-5 Normalized Screen Coordinates (NSC) . 8-2 Normalized Window Coordinates description..................................8-10 Normalized Window Coordinates (NWC) ..........................................8-2 notrecognized methods................... E-10 example..................................... E-11 NT Graphics Workstation Library ......G-4

O

object

Version 6.2a- 26 May 2006

SL-GMS Reference

xiii

Index

dynamic graphical........................ 3-2 erasing ....................................... 3-45 substitution for optimization ....... 11-4 Object Dynamic Properties option ... 3-23 Object Dynamic Properties window . 3-23 Object Flags window doublebuffer............................... 3-49 noerase...................................... 3-50 Object Oriented Environment ........... G-3 Object Renamed Variables option ... 3-55 Object Renamed Variables window. 3-55 object(s) dynamics editing .................................. 3-23 renaming variables .................... 3-55 OLIT widget ...................................... C-1 on-line example programs ........ G-5, G-8 operating system idiosyncrasies....... G-3 optimization...................................... 11-1 array variables ........................... 11-5 disable freeing SubModels ...... 11-18 disabling calculation of extents 11-14 disabling Shadow objects ........ 11-14 font pre-loading........................ 11-15 Model creation ........................... 11-1 object substitution ...................... 11-4 scoping variables ....................... 11-5 structuring DynProps ............... 11-13 SubModel cache ...................... 11-19 suppress SubModel replication 11-15 user-defined functions ............. 11-10 Variable Definition tables ........... 11-5 Optimization techniques .................. 11-1 optimized dynamics ...... 11-9, 11-10, C-1 override of Window Manager Quit option E-15 parametric instancing definition of.................................3-18 for Graphs ..................................3-21 in SL-DRAW...............................3-19 Pascal programming language applying to C on-line examples ....1-1 performance enhanced ...................................11-5 maximizing pixmap.....................3-49 optimizing with Array Dynamics .3-52 permanent flag ...............................11-18 pixmap double buffering .........................3-48 freeing ........................................3-48 reconstruction.............................3-49 Plot Graph ..........................................4-3 plotclear.................................. 4-34, 4-35 plotreset ...........................................4-34 plotshiftx ...........................................4-34 plotshifty ...........................................4-34 Polyline in Graphs......................................4-3 PostScript output........................9-17 Polyline limit PostScript output........................9-17 popflag, in generic State ................... E-5 POPUP GISMO........................A-10, E-3 popup State behavior ........................ E-7 portability, of Model files........... 2-5, 12-5 positioning a window ..........................8-7 PostScript color ...........................................10-4 default fonts..................................9-3 fontdef.dat file.............................9-13 output files..................................9-14 polyline point limit.......................9-17 printer .........................................9-14 standard coordinates..................9-14 standard mode ...........................9-14 standard page size.....................9-14

P

pan changing position of WC-window8-13

Version 6.2a- 26 May 2006

SL-GMS Reference

xiv

Index

text ............................................. 9-14 precision, Text ................................... 9-2 predefined State Instance..................E-7 Preview Graph ......................................... 4-11 option ......................................... 3-61 test data ..................................... 3-63 variable changing type....................... 3-62 Preview Options option testing Model ................................... 3-61 Preview Options window.................. 3-62 printer Postscript ................................... 9-14 printing to PostScript from code....... 9-16 programming languages .................... 1-1 Project.............................................. 12-7 project files....................................... 2-13 pscolordef.dat file............................. 10-4 manipulation...............................2-12 SL-XImage File format ...............2-12 Xwd format .................................2-12 reactivate method.....................E-9, E-10 redraw action, example ....................3-32 redraw dynamic action in non-replicating SubModels...11-16 Reference Point Graph ...........................................4-1 Renamed Variables Scrollbox............4-9 RenamedVars ................................... A-3 and updating behavior................3-57 example for RADIO GISMO ...... A-29 renaming variables...........................3-18 example......................................4-12 see also Rename Vars, SL-GMSDraw rescaling, of GraphAxis ....................4-27 reserved variable names............... 3-55, A-108 resize Event ...................................... E-2 RETURN GISMOs .......................... A-15 reverse video....................................10-4 RGB values ......................................10-2 rotate action, example......................3-30 rotation of precision 0 TrueType fonts)..........................9-11 Run-time Functions, SL-GMS ............2-5

Q

query functions, for events................. 7-7 QUIT GISMOs .................................A-13 quitting an application override of Window Manager Quit option .............................E-15

R

RADIO button ........................ 5-15, A-24 RADIO GISMO ................................A-25 radio3 GISMO..................................A-28 radio-highlighting behavior...............A-53 range interpolation ............................... 3-43 scaling........................................ 3-43 ranges, in dynamic descriptions3-43, 4-4 raster files definition .................................... 2-12 import and export....................... 2-12

S

scalable Text fonts ..................... 9-2, 9-7 scaling GISMOs .................................. A-112 Text fonts ............................. 9-2, 9-7 scoping variables .............................11-5 screen color index..................................10-4 SCREEN GISMO .....................A-17, E-3 Screen Management System Library G-4 screen State behavior ....................... E-7 screen State management ................ E-2

Version 6.2a- 26 May 2006

SL-GMS Reference

xv

Index

SCROLLBOX GISMOs ....................A-44 scrollbox window..............................A-53 scrolling functions examples ...................................A-53 scrolling menus................................A-53 Shadow object preventing the creation of ........ 11-14 with object erasure................... 11-14 Simple Roman fonts underscore and bracket characters9-4 simulation Datasource .......................F-2 SL Graph Library ............................. 3-21 SL-DMS ..................................... 2-5, G-2 SL-GMD............................................ G-2 SL-GMF ............................................ G-2 coordinate-specifying to functions 8-3 SL-GML ........................................... 12-1 example commands................... 4-29 SL-GMS description of ............................... 2-1 Glossary...............................B-1, G-1 Main Functions ............................E-2 SL-GMS / X Interface........................ C-3 SL-GMS / Xt Interface....................... C-1 SL-GMS AX/Developer...................... 2-8 SL-GMS C++/Developer.................... 2-8 SL-GMS J/Developer......................... 2-9 SL-GMS Mapping application library . 2-6 SL-GMS Run-time Function Libraries directory location for ........... G-4, G-7 SL-GMSDraw purpose........................................ 2-3 SL-GWS............................................ G-3 SLIDER GISMOs .............................A-55 SL-OOE ............................................ G-3 SL-SMS .....................................E-1, G-2 SL-SMS-WNT .................................. 2-10 SL-SMS-XM..................................... 2-10 software double buffering ................ 3-48 spacing, tick mark .............................. 4-4 special keys........................................1-1 sprintf( ) using in SL-GMS/Xt interface...... C-2 st30flag, in generic State................... E-5 startup sequence, SL-GMS..............10-3 State Class data structure, generic ................ E-5 Event-handlers in ........................ E-9 generic ........................................ E-5 Instance components .................. E-5 Instance, generic......................... E-5 methods ...................................... E-9 STATE GISMO.........................A-20, E-3 State Instances ................................. E-7 attributes of ................................. E-6 inheritance of methods.............. E-10 predefined ................................... E-7 State Management System Library...G-8 State Management System (SL-SMS) ..................... 2-5, E-1, G-2 State object, definition....................... E-5 State variable definition table ...........11-5 state_0 object................................ A-114 state_1 object................................ A-112 State-changing GISMOs ................... E-3 str_done method ............................. E-12 String Events............................E-6, E-14 structure variables............................3-53 SubModel cache........................................11-19 disable freeing..........................11-18 dynamic Chart ............................3-21 dynamic Graph...........................3-21 dynamic instancing.....................3-16 dynamics in non-replicating......11-16 instancing at run time ............................3-18 non-replicated Variable Definition tables......11-7 suppressing replication ............11-15

Version 6.2a- 26 May 2006

SL-GMS Reference

xvi

Index

used in construction of Models .. 3-16 using .......................................... 3-16 Variable Definition tables ........... 11-7 SubModel(s) renaming variables .................... 3-55 suffixes, file ...................................... 2-11 suppressing replication of SubModels........................... 11-15 suspend method ...................... E-9, E-10 labeling.........................................4-4 major ticks ..................................4-16 minor ticks ..................................4-16 on Graphs ....................................4-4 spacing.........................................4-4 time as axis on Graph ........................4-18 conversion routines ....................4-23 format .........................................4-19 timeofday variable, in DynProp ..... A-109 Timer Events ....................................7-12 toggle button CHECK...................................... A-24 RADIO....................................... A-24 toggle GISMO group ........................5-15 TOGGLE GISMOs .......................... A-32 toggle group .................................... A-24 toggle3 GISMO ............................... A-34 tprec0_rot_flag( )..............................9-11 tracelength .......................................4-33 traceline............................................4-28 tracemarker ......................................4-28 transformation combining multiple .....................11-2 transporting Models between computers....................12-5 traversal index..................................3-52 trend Graph ........................................4-3 dynprop ......................................4-34 example......................................4-13 trigger ...............................................3-30 TrueType fonts .................................9-11 type checking preview variables .......................3-63

T

-t option, AutoCAD............................ D-5 template Graph ......................................... 4-14 definition of........................... 3-21 template designer, Graphs .............. 4-18 test data preview ...................................... 3-63 Text change string in Model............... 12-2 default fonts ................................. 9-3 for SL-GMS ............................ 9-1 defined by .................................... 9-1 DynProp object .......................... 5-18 fonts scalable.................................. 9-7 highlighting.................................A-53 PostScript .................................. 9-14 precision ...................................... 9-2 precision 1 fonts........................... 9-4 scalable fonts............................... 9-2 sizing behavior............................. 9-2 TextEdit object ...................................E-6 in State Instance ..........................E-6 TEXTENTRY ARRAY GISMOs .......A-59 textentry GISMO, variables for ........A-70 TEXTENTRY VAR GISMOs ............A-67 tick mark axes ............................................. 4-4 label ..................................4-16, 4-17

U

unconditional dynamic action definition of...................................3-8 underscore character, in Simple Roman and Cartographic Roman fonts ....9-4

Version 6.2a- 26 May 2006

SL-GMS Reference

xvii

Index

Unicode localization files ................ D-14 unmapping .........................................E-1 unwanted flickering .......................... 3-48 update method...................................E-9 description of .............................E-10 inheritance of .............................E-10 updflag, in generic State ....................E-5 User interaction.................................. 2-4 user-defined methods .....................................E-10 user-defined function example ..................................... 3-38 GISMO......................................... 5-3 in application program ............... 3-39 in dynamic descriptions ............. 3-35 in DynProp ................................. 3-37 previewing dynamics error message...................... 3-41 user-defined functions ................... 11-10 userfctns.c file.................................. 3-39 example ..................................... 3-39 userfctns.o file.................................. 3-35 userfctns_initialize( ) ...............3-35, 3-39 example ..................................... 3-41 using SubModels ............................. 11-1 usr_set_color( )................................ 3-37 as GraphAxis limits ......................4-5 nested ........................................3-59 renaming example............................... A-38 renaming GraphTrace ..................4-6 reserved ......................... 3-55, A-108 structure .....................................3-53 types of, in Preview ....................3-62 video, reverse...................................10-4 View description....................................8-5 printing .......................................9-16 view_ndc_extent( ) method ................8-6 view_wc_extent( ) method .................8-6 view_wcextent..................................8-13 ViewMgrState...................................8-13 Views, multiple .................................12-7 virtual workstations............................G-3 vis action, example...........................3-30 visflag, in generic State ..................... E-5 visibility.............................................5-22

W

WC (World Coordinate)......................8-1 WC-window size of...........................................8-6 widget Motif ...........................................2-10 Xt based interfacing with SL-GMS.. C-1 win_destroy method ...............E-13, E-15 win_destroy_override method E-13, E-15 win_enter method............................ E-12 win_expose method ........................ E-12 win_focus_in method ...................... E-12 win_focus_out method .................... E-12 win_leave method ........................... E-13 win_map method............................. E-13 win_position( ) method .......................8-9 win_position_offset

V

valuelimits ........................................ 4-26 VarDefs definition ......................................B-6 variable array........................................... 11-5 scoping ...................................... 11-5 Variable Definition tables ................. 11-5 attached to Models .................... 11-7 variable names, valid characters in . 3-28 Variable Reference .......................... 3-28 Variable Reference, definition of........ 3-7 variables

Version 6.2a- 26 May 2006

SL-GMS Reference

xviii

Index

default value .............................. 8-10 description ................................. 8-10 examples ................................... 8-10 win_position_offset attribute default value .............................. 8-12 examples ................................... 8-11 win_position_offset( ) method example ....................................... 8-9 win_resize method...........................E-12 win_unmap method .........................E-13 Window Events........................................E-14 window creation ........................................E-2 default position............................. 8-9 externally create ........................ 8-13 positioning.................................... 8-7 setting location on screen ............ 8-9 setting the size............................. 8-8 Window Event-handler methods......E-10 Windows NT default fonts ................................. 9-3 fontdef.dat file .............................. 9-9 objects ....................................... 2-11 using SL-GMS with .................... 2-10 WinModState ..................................... 8-1 Workstation(s) raster file description.................. 2-12 World Coordinate View extent .................................. 8-5 World Coordinate Scale Factor (WCSF) changing ...................................... 8-2 default value ................................ 8-2 World Coordinate Scale Factor (WCSF)........................................ 8-4 World Coordinate System (WCS) ...... 8-4 World Coordinates ............................. 8-1 WsEvent class ................................... 7-6

X

X and Motif Enhanced State Management System Library ............................G-8 X as opposed to Xt............................ C-3 X error 11 bad alloc message ..........3-49 X error 9 bad drawable message .....3-49 X event gathering .............................. C-2 X event-loop function external, SL-GMS/X interface ..... C-4 X Graphics Workstation Library ........G-7 X Interface......................................... C-3 X Toolkit (Xt), SL-GMS interface....... C-1 X Windows (X), SL-GMS interface.... C-1 X Workstation default fonts..................................9-3 XFontSet platforms fontdef.dat file...............................9-7 XK_ key symbol codes.................... E-14 XListFonts( ).......................................9-7 Xt Graphics Workstation Library .......G-7 Xt Interface........................................ C-1 XtAppMainLoop( ) ............................. C-2 xvaluelimits.......................................4-30 Xwd, raster file format ......................2-12

Y

yvaluelimits.......................................4-30

Z

zooming............................................8-13 zoomrect( ) method ..........................8-13

Version 6.2a- 26 May 2006

SL-GMS Reference

xix

Information

SL-GMS Reference

450 pages

Report File (DMCA)

Our content is added by our users. We aim to remove reported files within 1 working day. Please use this link to notify us:

Report this file as copyright or inappropriate

519641


You might also be interested in

BETA
Microsoft Word - Document2
SL-GMS Reference
HYSYS 3.2 User Guide
HYSYS User Guide