Creating a custom transformation editor (CustomEdit)

Uviewer3D is a full-featured 3D viewer, complete with a top-level object, a window, a view, and related editors. In this tutorial, we add sliders to the bottom of Uviewer3D's window so the user can rotate the object.

The tutorial illustrates:

•      how to customize an application component supplied by the GD Kit

• •      how to build editors

Starting up

1. 1.      Start AVS/Express and choose Single-window DataViewer with no viewer (select None as the Viewer type) from the startup dialog, from an existing AVS/Express session, start a new Single-window DataViewer with no viewer by selecting the appropriate entries from the File->New Application... dialog, or clear an existing SingleWindowApp workspace, as appropriate.

Construct the base application

Build an application using Read Geom and Uviewer3D, as shown in the diagram below.

 



Display the modules window by selecting Editors->Modules. Select the Browse button from the Read Geom user interface. A dialog box appears. Select teapot.geo, then select the OK button.

Resize the view's rendering panel

We now customize Uviewer3D. We start by resizing the view's rendering panel to create space at the bottom of the window for the sliders. AVS/Express' active execution model enables us to see the results of our changes as we make them.

Maximize Uviewer3D. 

The figure below shows what Uviewer3D looks like. The annotations indicate the class name and purpose of most of Uviewer3D's objects:

 

 



Scene defines the view's window. This is the object we want to modify.

Find the view's panel and export it's port.

2. 1.      Open Scene in DisplayParameters mode. Open View in DisplayParameters mode. Open ViewUI in DisplayParameters mode. Open ViewPanel in DisplayParameters mode.

Export the output port on panel.

Close ViewPanel.

Decrease the view's frame height by 100 to create room for the sliders:

3. 2.      Open ViewFrame in DisplayParameters mode. Open the height subobject to see height's value expression. Only the tail end of the expression is currently visible.

Change ViewPanel.UI.panel.height to ViewPanel.UI.panel.
height <+> - 100.

Press Return. The new height should appear in height's title bar.

Close ViewFrame.

Notice that the view window's rendering panel is now shorter, leaving room at the bottom for a set of sliders.

Close ViewUI. Close View. Close Scene.

We are now back to Uviewer3D's maximized window.

Create the transform editor

We now create a transform editor inside of Uviewer3D, which appears to the user as a set of three sliders at the bottom of the view's window.

Create the skeleton of the transform editor.

4. 1.      Maximize Scene_Editor.
5. 2.      Instance macro . Rename macro to MyXformEditor.

Maximize MyXformEditor.

Instance link, UIpanel, GDobject_templ, and GDxform_edit inside of MyXformEditor.

Export the link so it is an input port on MyXformEditor and connect link and UIpanel as shown in the following diagram.

 



Modify UIpanel by setting its y subobject to 415 and its width subobject to =>link.clientWidth. This positions the panel just below the view window and makes the panel the same width as the view window.

Change GDobject_templ to a reference by setting its ref_mode property to & using the Properties Editor. Export GDobject_templ so it is an input port on MyXformEditor.

Open GDobject_templ and export its xform subobject so it is an output port on GDobject_templ. Connect GDobject_templ and GDxform_edit as shown in the diagram below.

 



At this stage, MyXformEditor should appear as illustrated in the following figure.

 



Close MyXformEditor.

Connect the right input port of MyXformEditor to in_view.picked_obj. This provides MyXformEditor with an object to transform.

Export MyXformEditor.link so it is an output port on Scene_Editor.

Close Scene_Editor.

Connect the right output port of Scene to the right input port of Scene Editor. This provides MyXformEditor's panel a parent window for the three sliders that will be added.

Look at MyXformEditor

Take a closer look at MyXformEditor.

Maximize MyXformEditor. 

The figure below shows what MyXformEditor looks like. The annotations indicate the class name and purpose of two of MyXformEditor's objects (the other two objects are references for the macro):

 



Although MyXformEditor so far defines just the skeleton of a fully functional editor, it does illustrate the two main components of an editor:

•      An edit object -- Most base objects--DefaultView, DefaultCamera3D, DefaultModes, and so forth--have companion edit objects--GDview_edit, GDcamera_edit, GDmodes_edit, and so forth. You will see how these work as we go along.

•      A user interface -- The user interface consists of UI widget objects, like panels, sliders, buttons, and entry fields. Many of the widgets are connected to subobjects of the edit object.

Here is how an editor works: the user modifies a UI widget that's connected to an edit object; the edit object in turn updates the base object to which it is connected.

Create sliders and connect them to the panel

We now create three user-interface sliders inside MyXformEditor.

Instance a UIslider object and connect it to UIpanel, as shown in the diagram below. 

 



Notice that a slider appears in the viewing window.

Modify UIslider.  Do the following:

6. 1.      Rename it to Xrot. (Use the Rename pull-down command.)

Set its x position to 10.

Set its y position to 10.

Set its width to 150.

Set its min value to -180 and its max value to +180.

Set its title to "X rot".

Notice that the slider changes accordingly.

Similarly, instance, connect, and modify a second UIslider.  Do the following:

7. 1.      Instance UIslider and connect it to UIpanel, just as you did for the first UIslider.

Rename it to Yrot.

Set its x position to 170.

Set its y position to 10.

Set its width to 150.

Set its min value to -180 and its max value to +180.

Set its title to "Y rot".

Similarly, instance, connect, and modify a third UIslider.  Do the following:

8. 2.      Instance UIslider and connect it to UIpanel.

Rename it to Zrot.

Set its x position to 330.

Set its y position to 10.

Set its width to 150.

Set its min value to -180 and its max value to +180.

Set its title to "Z rot".

Connect the sliders to GDxform_edit

The next step is to connect the sliders to GDxform_edit.

Expose GDxform_edit's x_rot, y_rot, and z_rot output ports.  Do the following:

9. 1.      Open GDxform_edit.

If x_rot does not already have an output port, create one with the Add Output Port pop-up command.

Export x_rot's output port with the Export Port pop-up command. Remember that you must position the mouse pointer over the port when selecting the pop-up command.

Similarly, create and export output ports for y_rot and z_rot.

Close GDxform_edit.

Here is what GDxform_edit should look like, both opened and closed:

 



Connect the three UIsliders to GDxform_edit, as shown in the followoung diagram. Note that objects in the diagram have been shifted to make the connection lines clearer.

 



Configure GDxform_edit

The last step is to configure the transform editor so it executes properly.

Open GDxform_edit.

Set the transform editor's shell_vis subobject to 1.

This causes the Xrot, Yrot and Zrot subobjects to be updated when the xform subobject changes. This happens when an object in the view is transformed using the mouse. The Graphics Display Kit editors typically do not update the subobjects that are normally connected to UI widgets unless shell_vis is set to 1.

Set the transform editor's absolute subobject to 1.

This causes the transform editor to work in absolute mode instead of relative mode. This subobject must be set to either 0 or 1 for the editor to work properly.

Close GDxform_edit.

Try the application

Use the sliders you created to rotate the teapot.

Clean up

This completes the tutorial. The completed tutorial is available in Libraries.Examples.Graphics_Display.CustomEdit.

Close MyXformEditor. 

Close Scene_Editor.

Close Uviewer3D. 

Note that at this point, you could rename Uviewer3D and save it back into Libraries, thereby creating a customized viewer.

Delete the application.

 




---