Scripted Panels

There exists within Maya a special and specific type of panel, called a scripted panel . This is an apt name , as they are panels defined by scripts. The term panel is slightly misleading in its use here, however. As we have just learned, a panel under its correct definition in MEL is little more than a complex type of control. However, within the Maya interface that users are familiar with, a panel is a much more complex item.

In Figure 11.25, we see a typical modeling panel. However, it is not just the modelPanel panel type, as we saw in the last UI project; it is in fact a modelPanel with a menu above it.

Figure 11.25: A Modeling pane.

All of the so-called panels that users are familiar with are, in actuality, collections of different panels and controls assembled together in a script. Again, this seemingly complicated structure opens up an immense amount of power and flexibility to the user who wants to exploit it.

Creating these user panels with scripts allows us to both modify the predefined scripted panels, such as the Graph Editor, and create our own. Creating scripted panels allows us to dock our custom controls in the view panes, and to tear off those panels into a window, essentially giving us two UI options with one definition.

The process of designing a scripted panel is similar to that used to design a floating window. However there are some additional considerations to remember. First and foremost is the realization that the user can and probably will resize the panel both to miniscule size and up to full screen. Second is that creating panels leaves an entry in the Panels menu of each pane. This means that if we make 300 tools, each creating a scripted panel for its UI, our menu becomes incomprehensibly filled with entries.

The solution to the first issue is just to plan for any resizing that might occur. This means becoming familiar with layouts that can accept dramatic resizing and still be useful. In most situations this means using a formLayout , a scrollLayout , or a frameLayout , if not a combination of all three. Using these layouts, as well as the appropriate alignment and attachment arguments on the controls and sub-layouts used in the panel, will allow us to construct a panel that accepts almost any resizing while still retaining a useful and appealing appearance.

One thing to remember about constructing designs for resizing in panels is that the user often has a good reason for resizing the panel. For example, if your UI has sliders, and the user makes the UI full screen, it is likely that he wants to have more finite control over the sliders, so they should grow and shrink with the panel. Likewise, if your panel has a large number of buttons , they should resize down as much as possible, but not necessarily become full screen.

The second issue is much less complicated. The answer is to only use scripted panels when necessary or when their benefits are worth an entry into the panel listing. This is more a judgment call than anything else, although other considerations of the production might play a role in the decision.

One last word on creating scripted panels before we delve into the details. The Maya engineers put a great amount of time, effort, and research into creating the scripted panels that exist already. Although it is possible to edit the ones that exist, or to recreate them, it is wise to consider whether it is truly necessary to do so. Ask yourself if it would it be easier and more efficient to create a window UI to act as this editor, rather than having to dissect and perform open script surgery on one of AliasWavefront s UI scripts?

Creating a scripted panel involves multiple procedures and a reliance on Maya s internal structures. Ironically, we do not create scripted panels with the scriptPanel command. We use instead the scriptedPanelType command. This command essentially defines the scripted panel name, and the various procedures that will be called during different actions the user might take. These actions are termed callbacks . In Example 11.26 we see the scriptedPanelType command, which defines a panel type called examplePanel .

Example 11.26: Defining a scripted panel called exampleScriptedPanelType.

 scriptedPanelType         -createCallback exampleCreateCallback         -initCallback exampleInitCallback         -addCallback exampleAddCallback         -removeCallback exampleRemoveCallback         -deleteCallback exampleDeleteCallback         -saveStateCallback exampleSaveStateCallback         -unique true         exampleScriptedPanelType; 

The first flag, -createCallback , defines the procedure that will be used to create the panel entry. In this procedure, we create any panel type objects, such as outlinerPanels , hyperPanels , and the like; however, we create them unparented. This is also the procedure in which we do all our initializing procedures, such as checking for the existence of optionVars , initializing global variables , and other standard initializations. Not that these initializations need to be carried out by this procedure itself; they can be located in another procedure that is called from this create procedure.

The -initiCallback argument specifies what procedure will be called whenever file “new or file “open is called, either from code or from the user interface. It allows us to embed behavior into the panel to reinitialize whenever the scene itself changes.

The procedure executed by the “addCallback argument is the one that actually defines the appearance of the UI. This is also the procedure where we parent any editors created in the procedure called from the “createCallback . By default, when the procedure begins, the parent object is the layout. If we need to explicitly name a parent of an object to be the panel, we can capture it to a variable by calling setParent “query at the very beginning of the procedure.

The “removeCallback procedure is where, and again this should be no surprise, we execute commands associated with the removal of the scripted panel. This is where we update any global variables to store the state of the controls in the panel, as well as where we unparent any editors from the panel.

The “deleteCallback actually deletes the panel from existence. Therefore, the procedure here would delete any editors created in the createCallback , and clear any global arrays that might have been declared.

The last callback flag, the “saveStateCallback returns a string, which is executed after the procedure specified by the createCallback flag. This requires some careful and often extensive coding of the return string to create an effective return string. It is used to restore the state of a panel to its state as it existed the last time it was closed during this Maya session.

The “unique flag is used to guarantee that we only have one instance of a panel, likely accessing and editing the same set of global variables, open at one time.

The final argument is the name of the scripted panel object itself.

All the procedures called from the callback flags of the scriptedPanelType command, except the -saveStateCallback flag, follow the declaration format of global proc procName ( string $panelName ) . The procedure called from the “saveStateCallback flag follows a similar structure, with the obvious addition of the string return declaration, global proc string procName ( string $panelName ) .

We will now take the slider portion of the blender window created in Project 11.3 and build a scripted panel out of them, essentially creating an optimized Blendshape panel.