Scripts that Manipulate Objects at Runtime

Before you begin, make sure you understand Scripting Basics. You should also have some basic code experience in the .NET environment.

You may be creating a display in which you want to change an object's property or insert objects onto the display in runtime mode. There is no native way to do that in GraphWorX64 while you are in runtime mode. However, by using scripting you can alter the runtime appearance of 2D objects as well as insert 2D objects. This topic describes how to do this. Keep in mind that displays cannot be saved in runtime mode; if you wish to save the changes that you make during runtime, you must change back to configuration mode and then save your display. Topic are:

Change Object Properties in Runtime Mode
Insert Objects in Runtime Mode
Shapes and Dynamics, Inheriting a Base Class

At this time, scripting cannot change or insert 3D objects.

Change Object Properties in Runtime Mode

You can use a script to manipulate an object in runtime by changing its properties. In this example, you will see how to change the color of an ellipse and how to hide it.

In configuration mode in GraphWorX64, insert a 2D ellipse onto the display and give the ellipse a name. For help doing this, refer to Shapes.
Add a button to the display (for help doing this, refer to Buttons); this button will run a script that will change the Fill color and shape of the ellipse.
Write the script that accomplish this. The first line of code will create a GwxEllipse variable and will get a reference to the ellipse itself. The second line will change the Fill property of the ellipse, and the last line, sets the horizontal radius equal to the vertical radius, which will change it into a circle. The resulting code should resemble the following:

var ellipse : GwxEllipse =

ThisConfiguration.GetObjectByName("Ellipse1");

ellipse.Fill = Brushes.HotPink;

ellipse.RadiusX = ellipse.RadiusY

Enter runtime mode and test your script. You should see the ellipse’s Fill color change to the one defined in the script when clicking the button.

Clicking the Button Changes the Color and Shape

Tip. You can find all properties in the GENESIS64 API Reference Help, which is available from the Start menu. This help file contains all Methods and Properties for all classes.

Insert Objects in Runtime Mode

In this example, you will use a script to insert a blue rectangle into a GraphWorX64 display while in Runtime mode.

Create a new display.
Add a button, and set its Command property to Run Script. Instead of double-clicking on the event name to generate a default-named function, enter CreateRectangle as the function name.
Press Enter to go to the Script Editor to edit this new function.
On the Code View tab, declare the Rectangle object, create the object including its size and color, and then display the object. Add the following lines to the body of the function:

//declare variable

var myRectangle : GwxRectangle;

// set rectangle properties

myRectangle = GwxRectangle.Create(ThisConfiguration,

new

Rect(50,50,200,100),

ThisConfiguration.Root,

false,

null);

// change rectangle color

myRectangle.Fill = Brushes.Blue;

Save the display.
Enter Runtime mode and test the button. When you click the button, a blue rectangle should appear in the display.
Return to Configuration mode. Note that the rectangle is now part of the display. This is the intended behavior.

You can use this scripting behavior to generate multiple, uniform objects in your display configuration. Write a script that will draw all the objects for you in Runtime, then go back into Configuration Mode and use the newly-created objects.

What Just Happened?

Let's look more closely at the code provided above.

First, the script declares a variable of the type GwxRectangle. To figure out which type you should use, look in the GENESIS64 API Reference Help, which is available from the Start menu. The API Reference Help lists all classes that are available inside the GraphWorX64 namespace. Although there are many different classes available, they are named in a way that tells you what they are. Generally, the name of the class is GwxObjectType, where ObjectType is the type of the object such as Rectangle, Ellipse, Dynamic, etc.

Next, the script creates a rectangle with specific properties. If you look at the API Reference Help, you will find the declaration for the function, as shown below. As you type the function in your script editor, you should also see IntelliSense which guides you to the different parameters you need.

GwxRectangle Function Declaration in the GENESIS64 API Reference Help

There are five parameters:

GwxConfiguration is a GraphWorX64 configuration. This example uses the global variable ThisConfiguration to satisfy this criterion. (For more information, refer to Using Global Variables in Scripts).
dimensions provides the dimensions of the rectangle. This example uses a structure inside the .NET framework library; the name of the structure is called Rect, which takes the left, top, width, and height (Rect(50,50,200,100)) of the rectangle as numbers (Doubles to be exact) respectively.
parentElement is the rectangle's parent element. In this example, the parent is the root of the display since there is no other object on the display. The script gets to the root by using ThisConfiguration.Root.
selectAfterCreate determines whether to select the rectangle after it is created. Since we do not want to select the object after creating it, the script uses false.
initializePropertiesFrom is a location to initialize the properties of the rectangle. It asks for a GraphWorX64 element, but since we cannot derive from this class as specified in the API Reference, the example provides a null object.

The last line of the script (myRectangle.Fill = Brushes.Blue;) determines the color for the rectangle. As you type, a window lists colors under the Brushes class.

Shapes and Dynamics, Inheriting a Base Class

In the previous examples, GwxEllipse and GwxRectangle have the property Fill, which allows you to specify the color that fills the object. There are more Methods and Properties that are common among the different GraphWorX64 shapes. If you examine the GENESIS64 API Reference Help closely, you will notice that under the GwxEllipse Class and GwxRectangle Class declarations, both inherit another class called GwxShape. This is where these two classes obtain their shared properties and methods. Since there are shared properties and methods, knowing how to use a method or property for one type of GwxShape means you know how to use it for all of the shapes. This concept applies to all shapes within GraphWorX64. (For a list of all shapes, refer to Shapes.)

The idea, however, does not stop at shapes. It could apply to other objects. For example, if you look at the GwxProcessPoint class (for a process point, which is a dynamic) and if you drill down enough, you will find a class called GwxDynamic. And if you know how to use the DataSource properties on a process point object, you will know how to use the same properties on other dynamics, like a color dynamic, because all dynamics inherit the same base class.