MAXScript rollouts

Contents
1. What is a rollout ?

2. A first rollout

2.1 Adding user interface elements 2.2 Example user interface

3.User interface layout

4. User interface events

5. Generated code

6. Palisade generator

7. Opening and closing the rollout

8. Installing a button

1. What is a rollout ?
In 3D Studio Max , a rollout is a top level user interface component that acts as a container for other user interface components. There is a visual editor that can be used to add user interface components into a rollout and this tool also allows you to change the properties of these user interface components (such as the caption, width, height, position, tool tip ... )

The interesting fact is that the visual editor generates code that supports a full round trip. Changes in the code are reflected back into the visual editor, and changes made in the editor are reflected back into the code.

Normally, a rollout is shown as a sub window of the 3D Studio Max environment and this subwindow will be shown when a user presses a button or when a users clicks on a menu item.
2. A first rollout

The first rollout will be a simple "Hello World" rollout , and we will integrate this rollout in 3D Studio Max via the UI Customizer tool.

First we create a new script via the menu item  MAXScript --> New Script.

Instead of a utility we now create a macroscript , and define some properties for the appearance of this macroscript on a button or a menu item :
macroScript RolloutTest

category:"DAE Tools"
internalCategory:"DAE Tools"
buttonText:"RolloutTest"
icon:#("Systems",2)
tooltip :"This is a rollout test"
(

-- contents
)

A macroscript is defined by the following properties :

• category : provides an easy way to find scripts in the UI customizer (see further).
• internalCategory : the value of this property is used in .cui , .kbd and .mnu files.
• buttonText : if this macroScript is bound to a button, this is the text that will appear on the button.
• icon : the icon to use for this button. There are a number of predefined categories for icons, and the example uses the second icon from the "Systems" icon category.
• tooltip : The tooltip that will be shown when the mouse hovers overs the button or menuitem.

2.1 Adding user interface elements
Now we can start adding user interface elements via the visual editor. Place the cursor inside the body of the macroScript and click on the menu : Tools --> New Rollout

This will off course create a new rollout and start the visual editor :

Image 1 : Visual editor

The bottom row of the visual editor contains the user interface elements that can be added to the user interface.

The "Value" tab contains all the properties of the current component. Because we started with a new rollout the rollout itself is selected as current component.

For now , there are two important properties :

• name : this property will be the name for the rollout in the script. For this example , change this property to PalisadeRollout.
• caption : The title for the rollout. For this example, change this rollout to "Palisade generator".

Keep the visual editor open for the next part of this tutorial. As long as the visual editor is open, it is not possible to change the macroscript via the MAXScript Editor.

2.2 Example user interface
As an example we create a palisade generator user interface. To make things a little more interesting we add small variations in radius and height for the individual trunks of the palisade.

Image 2 : Palisade example

The user interface for the palisade generator allows the user to set the following parameters :

• number of trunks
• radius : the radius for the trunks of the palisade
• height : the height of the palisade
• color : the color for the trunks in the palisade

2.2.1 Number of trunks

We will set the number of trunks with the help of a spinner control. Select the spinner control component in the bottom row of the visual editor :

Image 3 : Select spinner component

Next click somewhere on the rollout and drag the outline for the spinner component :

Image 4 : Add spinner component

Next we need to set the properties of the new spinner component. The important properties are :

• name : this is the variable name for the spinner component. By default a spinner component has the prefix spn. Give this property the value spnNumberOfTrunks.
• caption : the caption for the spinner component. Give this property the value "Number of trunks :".
• range : the range for the spinner component. A range of  [1,100,10] means that the spinner component has a minimum of 1, a maximum of 100 and a default value of 10.
• type : the number of trunks is an integer, so set this property to #integer.

The position and dimension of the spinner component can be adjusted by dragging the control handles of the component on the rollout, but it is easer to use the "Layout" menu to align and space components.

The controller property allows you to directly set a rotation , translation or any controllable value for an object in the scene. We will not use this property in the

Important note : There are difficulties setting the range property when the locale is set to a language that uses the comma as a symbol for floating point numbers. In that case it is necessary to set the range in the script file.

回复 6# 铁豌豆


  我试试  好像我还没弄过这个东西。。。呵呵

呃。。怎么还是这样的啊。。好多的空格和换行。。又乱掉了。。。我还真不会发帖。。。
19silly 发表于 2009-10-20 12:47

还不错呀！！能看就好了。其实发布者是有编辑原帖的权限的，你找找编辑按钮！

呃。。怎么还是这样的啊。。好多的空格和换行。。又乱掉了。。。我还真不会发帖。。。

6. Palisade generatorNow we can add the code the generate the palisade. We use the random function to generate random variation in the trunks :

Open the Command Listener (F11) and type :

random 1.0 1.2

This function generates a random number between 1.0 and 1.2.

The code in the pressed event of the btnCreate button is the following :


on  btnCreate pressed  do
        (
            posx = 0

for i = 1 to spnNumberOfTrunks.value do
            (
                radius = spnRadius.value * (random 1.0
1.2)
                trunkheight = spnHeight.value * (random 1.0
1.1)




posx = posx + radius

Cylinder position:[posx,0,0] radius:radius height:trunkheight





wirecolor:cpTrunkColor.color
                posx = posx + radius
            )
        )

The palisade generator starts at position [0,0,0] and generates the number of trunks that was set via the spnNumberOfTrunks spinner control. The value property of this variable contains the number of trunks.

First we define the posx variable that will store the current position for the trunk.

The for loop will be executed for each trunk , and the value of the radius and height are adjusted via the random function. The Cylinder constructor is used to create a new Cylinder for each trunk with the given position, radius, height and color properties. The new value for the posx variable is then the current posx value plus two times the value of the currrent radius.


7. Opening and closing the rollout
We need to add code the manage opening and closing the rollout. The complete script is :

macroScript RolloutTest

category:



"DAE Tools"
    internalCategory:
"DAE Tools"

buttonText:        
"RolloutTest"

icon:                 #("Systems",2)

tooltip :             "This is a rollout test"
(

local
palisadeFloater



rollout PalisadeRollout "Palisade Generator" width:162 height:154
    (

spinner spnNumberOfTrunks "Number of trunks : "
pos:[22,11] width:126



height:16

4. User interface events

There are two buttons on the user interface that will execute an action when clicked :

• Create button : create the palisade and close the rollout
• Cancel button : do not create the palisade and close the rollout

To handle the click event , select the Create button and go to the Event Handlers tab :

Image 11 : Adding Event Handlers

Select the pressed event.

Select the Cancel button and again, select the pressed event.

We are now ready with the user interface. Save the rollout and close the Visual MAXScript editor.


5. Generated code
The Visual MAXScript Editor should have created the following code :

    rollout PalisadeRollout "Palisade Generator" width:162 height:154
    (

spinner spnNumberOfTrunks "Number of trunks : "
pos:[22,11] width:126



height:16 enabled:true

range:[1,100,10] type:#integer
controller:""

spinner spnRadius "Radius :" pos:[22,31] width:126 height:16




range:[1,20,2] type:#float
controller:""

spinner spnHeight "Height : " pos:[22,51] width:126 height:16




range:[1,500,100] type:#float

colorPicker cpTrunkColor "Color :" pos:[22,71] width:126 height:24




title:"Choose a color"

button  btnCreate "Create" pos:[99,129] width:50 height:20

button btnCancel "Cancel" pos:[43,129] width:50 height:20



on  btnCreate pressed  do
        (


        )



on btnCancel pressed  do
        (


        )
    )

If the range property could not be set with the Visual MAXScript editor, it is now possible to adjust this property manually.

2.2.2 Radius and height

We use 2 spinner components for these 2 properties. The only difference with the number of trunks spinner component is that these 2 spinner components will have #float as type.

Add the spinner components to the rollout and adjust the properties :

For the radius parameter :

• name : spnRadius
• caption : "Radius :"
• range : [1,20,2]. This means that the minimum value the user can select is 1, the maximum value is 20 and the default value is 2.
• type : the radius is a float, so set this property to #float.

For the height parameter :

• name : spnHeight
• caption : "Height :"
• range : [1,500,100]. This means that the minimum value the user can select is 1, the maximum value is 500 and the default value is 100.
• type : the radius is a float, so set this property to #float.

Important note : There are difficulties setting the range property when the locale is set to a language that uses the comma as a symbol for floating point numbers. In that case it is necessary to set the range in the script file.

2.2.3 Color

Add a color component to the user interface. Select the following icon on the bottom component tool bar :

Image 5 : Color chooser

The important properties for this component are :

• name : cpTrunkColor
• caption : "Trunk color : "

2.2.4 Create and cancel button

Finally we need to add two buttons to create the palisade or to cancel creation. Choose the button component from the button tool bar :

Image 6 : Button component

Add two buttons to the rollout and set the following properties :

Create button :

• name : btnCreate
• caption : "Create"
• width : 50
• height : 20

Cancel button :

• name : btnCancel
• caption : "Cancel"
• width : 50
• height : 20

2.2.5 Intermediate result

The user interface is a bit of a mess now. The next section will discuss methods to assign a proper layout for all the components :

Image 7 : User interface

3.User interface layout

The visual MAXScript editor provides a number of tools to create a professional layout.

Select the components that you need to align by dragging a selection rectangle

Image 8 : Select components

Via the Layout menu it is now possible to align and distribute the components evenly :

• Click on Layout --> Align --> Left
• Click on Layout --> Make Same Size --> Width
• Click on Layout --> Make Same Size --> Height
• Click on Layout --> Space Evenly --> Down

Now select the two buttons and align them on the bottom right of the rollout :

Image 9 : Final result

Finally it is also possible to enable a grid (guide) for better control over the initial placement of the user interface components. Select the menu item :

Layout --> Guide Settings ...

The following dialog appears :

Image 10 : Guide Settings

Enable "Use Grid / Snap" to use a grid and change the "Grid Spacing" value if needed.