SingleWindowApp, MultiWindowApp
Synopsis
templates for two different styles of AVS/Express application
Description
These objects provide the basic framework for an application's user interface including a shell window, menu bar, status bar, exit functionality, toolbar, and a panel for UI editors. These objects are called the application UI and are kept in the "UI" subobject of SingleWindowApp and MultiWindowApp. SingleWindowApp's UI defines controls in a single shell window. MultiWindowApp's UI provides a single shell window for user interface controls, but each graphics display window is created in a separate shell window.
By default the UI subobject of the application is not visible in the Network Editor. To make this object visible, select the menu toggle Network Editor Options->Show Application UI and close and reopen the SingleWindowApp or MultiWindowApp object by double-clicking on it twice with the mouse. You should then see the UI subobject of your application in the upper left hand corner.
Most of the user interface for an application is defined by the components added to the application, such as Uviewer. These objects are called the component's UI. The application UI defines containers, both UIpanels and UIcmdLists, to hold the component's UI. Connections are automatically created between the application UI and the component's UI when components are instanced.
These connections are typed into different categories so that an application object panel shows up in the right place. For example, when you drop a Uviewer object into an application, it adds several entries to the Editors menu, tools to the toolbar, and either creates a separate shell window (MultiWindowApp) or adds a window to the Windows panel (SingleWindowApp). This process is described in more detail in the User's Guide .
Although these connections are originally made automatically, you can edit them just like any other connections in the system using the Network Editor. In this way, you incrementally reorganize the layout of your application. Since these connections are created automatically, they are not displayed as visible connection in the Network Editor. You must edit them by opening the object's value and editing the path names by hand.
These connections fall into two categories.
o Command connections are made from a UIcmdList or UIradioList in the application UI to a UIcmd (or UIoption) in the component's UI. These connections define menus in your application such as the Editors menu.
o Parent connections are made from a UI widget (often a UIpanel) in the component's UI to a UIpanel in the application UI.
A UIradioList is combined with a UIpanel in the application UI to form a stack. This stack serves as a container for a set of objects in the component UI that pair a UIpanel with a UIoption. The set parameter of the UIoption is connected to the visible parameter of the UIpanel. In this way, the stack maintains a list of UIpanels in which only a single UIpanel can be visible at a time. This visibility can either be controlled by a pull-down menu or an option menu. There are three stacks currently defined in the application UI: Editors, Modules, and Windows (SingleWindowApp only).
There are two different mechanisms used to create these automatic connection:
o The UImod_panel object defines a subclass of a UIpanel that has a UIoption controlling its vibility. This object always adds itself to the Modules stack (see below) and the mechanism used is not configurable.
o Other connections are performed using the GMOD.hconnect object. This object provides a flexible mechanism for controlling how connections are made. See the man page for GMOD.hconnect for more information.
If no application UI object is defined for a particular component UI object, it acts according to its default behavior rules. For a UIshell, there two default behaviors:
o Create a separate shell and make your panel visible immediately. In this case, the UIshell object is added as a child of the UIpanel in the component UI. For UImod_panel objects you can turn this behavior off by setting the property ui_default_shell=0 on the application object.
o Do nothing, leave the panel without a UI parent. In this case, the application developer can provide a UI parent connection by traversing to this object in the Network Editor and making the connection manually.
For a UIoption, the only default behavior is to do nothing when no container is found in the application UI.
In order to do edit the application UI, you need to know which objects in the SingleWindowApp and MultiWindowApp define which regions of the user interface in your application. You can move and resize panels, add new panel regions, add entries to the menu bar and existing pull-down menus, and so on.
This table describes the subobjects of the UI macros for SingleWindowApp and MultiWindowApp.
Example
Here are a few examples of different ways that you can modify the application UI:
Reconfigure the window layout of the application
UI.shell // application shell
UI.panel.UI.panel // Editors UI area
UI.status_bar // status bar
UI.Windows.IUI.panel // graphics window area
// (SingleWindowApp only)
InfoBar // Info panel
toolbar // toolbarFile
See Also Related Modules