Developer's Corner
Why do we need a calculator that shows the computational relationships among the operators and operands in a graph? Wouldn't it be easier to type in the formula in textual format? Wouldn't it be more efficient to write programs in textual code rather than using a visual/diagrammatic language? There are always arguments between textual and diagrammatic representations of computational programs. We created Visual Calculator for SansGUI not because we want to claim the success or failure on either side, but to use it for the following purposes:
Demonstrating how to take advantage of the SansGUI Modeling and Simulation Environment to create an object-oriented, visually programmable calculator.
Introducing a new paradigm for calculation-based utility programs, in addition to those that employ the physical calculator or the spread sheet metaphors.
Showing that diagrammatic representations of computation may, at times, be more comprehensible and traceable than their textual counterparts.
Paving the way for SansGUI developers to create full-blown visual calculators or other simulators based upon the experiences obtained from this simple example.
The Schema Definition file of Visual Calculator, named Calc.sgs, is located in the samples\Calc subdirectory of the SansGUI installation directory. We created it with the SansGUI Development Environment. If you have the SansGUI Run-Time Environment (SGrun) or the Demonstration Edition (SGdemo), you will not be able to open the Schema Definition nor to create one of your own. You are encouraged to go to ProtoDesign's web site and register for a 30-day evaluation license key to activate the SansGUI Development Environment. To know the license option you currently have, run SansGUI and select Help>About SansGUI... from pull-down menu to obtain a informational dialog.
To examine the Schema Definition, please open the Calc.sgs file. Here is a summary of how we created it:
We entered the simulator identification when we created Visual Calculator. The Simulator Identification dialog can be accessed by selecting Action>Change Identification... from the pull-down menu. The password is Calc. If you want to extend the Visual Calculator, please change the information here to include a new name for the calculator, along with your own company and group names. If you are just examining it, simply click on the Cancel button to close the dialog.
Having created a new Schema Definition for Visual Calculator, we created SimControl.Cycle.Calc simulation control class to indicate that it is for an in-process, cycle-driven simulator. To examine it, click on the first Simulator tab in the Left Pane, and click on the name or the icon of class Calc. A Grid View in the Right Pane will show all the attributes in this class. There is, however, no local attribute created for class Calc -- all are inherited from the Cycle intrinsic class. Double click on class Calc to see the Document Location and Memo field we entered for this simulator control class. Click on the Cancel button when you are done.
Double click on the Angle object below the Unit class to see the unit conversion table in a Object Properties dialog. We created this unit object for the sine wave generator. Again, click on the Cancel button when you are done.
The calculator operations are implemented in eight Base component classes. A summary of the classes can be found in the Introduction section. Here we examine the contents of the classes, especially how their attributes, port definitions, and class functions are specified. We created these classes by right clicking on the Base class in the Component (middle) tab in the Left Pane and selecting Create Subclass from the context menu. For you, simply double click on the name or the icon of class Add, or select Properties from the right click context menu.
Some notes regarding the base component classes in Visual Calculator follow:
We used the Change Icon... button in the lower right corner to select the icon for class Add. The icon was created in Visual Studio with a 32x32 and a 16x16 16-color icons. You can use other icon editing programs to create icons of your own as long as there are both 32x32 and 16x16 pixels in the icon file. All the icon files used in Visual Calculator can be found in the samples/Calc subdirectory.
The Document Location contains Calc/Add.htm as its value to indicate that the Add.htm file in the doc/Calc subdirectory will be used for on-line help when the user clicks on the big icon in the Properties dialog during run-time.
In the second DLL tab, we checked Evaluation function SG_xEval_Base_Add in both Call and Override fields. SansGUI will call this routine during the evaluation cycle of a simulation run and the user can supply an overriding routine to modify the behavior of addition operation in the SansGUI Run-Time Environment.
In the third Port tab, you can see how the ports of class Add are explicitly defined. Port 1 is for an input port and port 2 is for an output port. The Unique fields are not checked because we allow multiple connections to the same port.
The last tab, Connectivity tab, is not used in all component classes in Visual Calculator.
Both Base.SineGen and Base.Variable classes have class attributes. They are entered in the associated Grid View in the Right Pane. To see them, single click on the SineGen class name or its icon to obtain the Grid View in the Right Pane. You can see the definitions of the attributes by scrolling the Grid View, or right clicking on the name of an attribute and select Properties from the context menu. An Attribute Properties dialog will be displayed to show the definition of the one you just picked. Changes made in the Grid View are immediate. For changes made in the Attribute Properties dialog, however, you need to click on the OK button to commit them and close the dialog. For more operations on the attribute list, such as adding, deleting, or reordering the attributes, please consult Operating on Attribute Grid View section in Chapter 2 of the SansGUI Developer's Guide.
Some classes, such as Negate, SquareRoot, and Variable, allow only one input link. We simply check the Unique fields when defining their input Port 1. Class SineGen and class Constant do not allow input link at all.
Please go to the reference section of each class to find out more details. You may compare the reference information with the class definitions and the accompanying source code to gain more insights.
The Connector class is defined to include one single attribute -- Value. It is used to pass the value from one component to another.
After we have created all the classes, we use the SansGUI Development Environment to generate an Object Library with the default name Calc_<Major>_<Minor>.sgo. Also generated are C/C++ and Fortran source code for the class functions in each component class. We selected Action>Generate Next Build, Generate Test Release, or Generate Official Release from the pull-down menu to perform this task. By default, both C/C++ and Fortran code are generated and stored in a subdirectory named:
Calc_<Major>_<Minor>_<Patch>_<Build>, where
<Major> is the major release number.
<Minor> is the minor release number.
<Patch> is the patch level.
<Build> is the build increment.
You can look into the Generating Object Library section in Chapter 3 of the SansGUI Developer's Guide for more details.
The generated source files were then inserted into two Win32 DLL Projects, one for Visual C++ and the other for Visual Fortran. The two project were developed independently; therefore, you only need Visual C++ or Visual Fortran but not both. To examine the code in the class functions, perform the following steps. Please note that you don't need to close the SansGUI environment. SansGUI can work with Visual Studio in coordination, especially when you are debugging your code.
Start your Visual Studio IDE that comes with either Visual C++ or Visual Fortran.
Select File>Open Workspace to load Calc_1_1.dsw from the Calc_1_1 subdirectory if you are using Visual C++; or Calc_1_1F.dsw from the Calc_1_1F subdirectory if you are using Visual Fortran.
Once the workspace is loaded, switch to the File View and you will see the class functions being collected in the source files with the names corresponding to the classes.
Double click on any file to see the code, as you would do in your program development.
The Add, Subtract, Multiply, Divide classes do not contain any attribute. The code in the evaluation functions demonstrate how to process input links and deposit resulting values to output links. To learn how to access class attributes, you can start with the evaluation function in class Constant or class Variable because they have only one attribute, Value (fValue). Once it is understood, you can look into the evaluation function of class SineGen for a more elaborated coding example.
Consult Chapter 4 Developing In-Process Simulators in the SansGUI Developer's Guide, Chapter 2 SansGUI Data Object Format and Chapter 3 SansGUI Application Programming Interface in the SansGUI Reference Manual for more coding details. It is also a good idea to go through the code in other examples in the Getting Started guide and from ProtoDesign's web site.
The on-line documentation you are looking at right now was created by a 3rd party HTML authoring tool. It does not have to be all in HTML. You can include other types of files as long as you enter them correctly in the Document Location field in the Class Properties dialog (as shown above). SansGUI will invoke the associated application according to the extension settings in the user's Windows registry.
Details of Preparing On-Line Documentation can be found in Chapter 3 Generating and Maintaining Object Libraries in the SansGUI Developer's Guide.
The distribution files in Visual Calculator for SansGUI are described in the Welcome page. We created a directory structure for all these files and used a zip utility program to create and convert the zipped archive file into a self-extracting executable program. When the program is run, all the files are extracted and put in the corresponding locations, preserving the directory structure.
Please consult Chapter 7 Deploying Simulators in the SansGUI Developer's Guide for more details.
 |
 |
Visual Calculator for SansGUI Version 1.1
Copyright © 2001-2003 ProtoDesign, Inc. All rights reserved.