Topics
Building a GUI
Add a GUI by going to the Tools Menu > Graphical User Interfaces > Add.
Once you have added a GUI, two windows will open. The window on the left is called the GUI builder. This window provides you with several tools for building your GUI.
The window on the right is called the GUI canvas. This window shows what your GUI looks like. Initially it is blank. We will add GUI views to it in a drag-drop fashion from the GUI builder window.
As an example, we will create a simple GUI that allows you to edit the max speed, acceleration, and deceleration variables of an operator object. First, let's drag a few simple views onto our GUI canvas. From the top panel of the GUI builder, drag a button onto the GUI canvas.
You can now select the button by clicking on it. When the button is selected, you will see a dotted outline around it, as well as a black square to the bottom right of it.
To move the button, just click and drag the button to the location you want it at. To change the size of the button, click and drag the black square.
Now add three static views and three edit views onto the GUI canvas, as shown below.
Change View Names
Now we want to change the names and attributes of our GUI views. Collapse the controls toolbar by pressing on the "Controls" button in the gui builder. First, let's make the button an OK button that will apply the edits the user has made, and then close the window. Click on the button. Then click on the "View Attributes" radio button in the gui builder window. Notice that the button and its attributes are now shown in the tree view of the GUI builder.
Click on the button name ("button4" in our case) and rename it to "OK". On the left are some commonly used attributes that can be added to the button. To add an attribute, just drag it from the icon grid on the left to a blank area in the tree view.
Add an apply attribute and a close attribute to the button. The apply attribute causes all coldlinks and hotlinks found in the view to be applied to their respective destination nodes when the button is pressed. coldlinks and hotlinks will be explained later. The close attribute causes the window to close when this button is pushed.
Alternative Method - Alternatively, instead of adding the apply and close attributes, you could add the following code the the OnPress attribute of the button:
applylinks(ownerview(c));
postclosewindowmessage(ownerview(c));
This code would have the same effect as the apply and close attributes.
Now click on the first static view. Again, the static view and its attributes should appear in the tree view of the GUI builder. For the name of the first static view, enter "Max Speed". You will not see the name change on the static view until the view is refreshed. Now click on the second static view and set its name to "Acceleration". Then click on the last static view and change its name to "Deceleration".
Now that you have made a few changes to the GUI views we will refresh the GUI canvas to see these changes. Click on the GUI canvas window and then press the F5 button. This will change the GUI canvas from editing mode to regular viewing mode. Now your window should look like a normal window without the dotted lines around it.
Notice that the label views are now not large enough to fit the text that they are showing. To fix this, go back into editing mode by selecting the GUI canvas window and pressing F5 again. Now rearrange the sizes and locations of your views so that there is enough room to show the entire text of the labels.
Link the Edit Views
Now let's connect the edit views up to their proper nodes in the model. First let's explain some concepts. Click in a blank area in your GUI canvas. This will cause the tree view of the GUI builder to show the attributes of the main GUI window.
Notice that there is an attribute called objectfocus. Right now this attribute shows the path "MAIN:/project/model". Later on, though, once you've associated an operator with this GUI, and then double-click on the operator to open this window, the objectfocus attribute will be changed. It will specify a path to the operator you are editing. For example, you've associated an operator named Bob with this GUI. When you double-click on Bob, an instance of this GUI is created, and its objectfocus attribute is set to the string path: "MAIN:/project/model/Bob". This is important to know when creating edit fields that are linked to our object. Now let's go back to the first edit field.
Click on the first edit view to view its attributes in the tree. Add a coldlink attribute from the list on the left.
Now enter the following as the text of the coldlink attribute: @>objectfocus+>variables/maxspeed
Links should be made to a node that contains some desired value. Sometimes linking directly to the object property node is undesireable, such as code nodes. In this case, link to a label and use the label value as part of the code property (use executestring()).
The coldlink/hotlink text specifies a path to a node that the edit field is to be associated with. This path starts at the coldlink node itself, and should specify a path to the maxspeed variable node on the operator. The different symbols in the path are ways of specifying how to traverse the tree to the destination node.
The coldlink you have specified does the following:
- Starting at the coldlink node, go to its ownerview, or the main GUI window (@).
- From there, go into its attribute tree and find the attribute named objectfocus (>objectfocus).
- Interpret the text of the objectfocus node as a path to a node, and go to that node (+). Remember that when we open this window for our Bob operator example, the objectfocus attribute will be changed to "MAIN:/project/model/Bob". So it will now go to our Bob operator in the model.
- From there, go into the object's (Bob's) attribute tree, and find the node name variables (>variables).
- From there, go into the node's sub-tree and find the node named maxspeed (/maxspeed).
Now connect the other two edit views. Click on the second edit view, then in the tree view add a coldlink attribute and specify its text as: @>objectfocus+>variables/acceleration. Do the same for the last edit view and set its coldlink attribute to: @>objectfocus+>variables/deceleration.
Direct Model Objects to This GUI
Now that we've finished creating our GUI, let's direct an operator in our model to this GUI. Drag an operator into your model. Select it by holding Control or Shift down and clicking on the operator.
Now go back to the GUI builder window, and from its menu, select "GUI Options > Redirect Selected Objects to this GUI".
This will redirect all selected objects in the model to use this GUI instead of their usual properties window. Now close the GUI builder window. This will automatically close the GUI canvas window as well. Now double click on the operator you have selected. This will open the GUI window you have designed instead of the normal properties window.
Make some changes to the max speed, acceleration and deceleration values, then press the OK button to apply those changes. Open the window again to verify that your changes were applied correctly.
