Layout Windows

From The Foundry MODO SDK wiki
Jump to: navigation, search

Layout Windows are a config construct for defining windows. You can think of it as layout.createOrClose, but instead of having to provide the window definition entirely through arguments, you can define them through a config construct.

layout.window vs. layout.createOrClose

layout.createOrClose allows an entire window definition to be defined through arguments passed to the command. This means that the command string is overly complex, easily to introduce mistakes into, and difficult to change, especially if the same window is supposed to be used for a key mapping, a button in a form and an entry in a menu.

layout.window has only three arguments, with all the window state defined in the configs. This makes it easier to use the same window definition in multiple places, and to add new functionality in the future. It is also more readable in the configs. In the future I may add a "window definition editor" in the preferences to help manage these windows.

layout.window also supports features that layout.createOrClose doesn't, such as pinned popover support, popover resizing support, and better support for remembering window size and position. layout.window should be used when opening defining windows whenever possible.

Config Definition

Inside of the root-level Frame atoms, there can be any number of LayoutWindow hashes, each representing a different window definition. The hash is used in a manner similar to a forms's hash to define the window, and layout.createOrClose's "cookie". Under the has are all the atoms that define the window.

 Frame
   LayoutWindow <hash>
     Title <@table@msg@>
     Tooltip <@table@msg@>
     Size <w> <h>
     SizeMin <w> <h>
     SizeMax <w> <h>
     Maximize <boolean>        // Only for "standard" windows
     Style <styleName>         // standard, palette, popoverRollOff, popoverClickOff, popoverPointAt
     PointAtPopoverPreferSides <boolean>
     PostRestoreCommand <commandString>
     Icon <iconResourceName>   // Displayed on buttons in forms
     Opaque <boolean>          // For popovers like the Color Picker where transparency is bad
     Contents <type> <hash>    // See below
     SwitcherClass <class>     // Switcher bar class; layout overrides it
     ShowSwitcherBar <boolean> // Enable/Disable switcher bar entirely on normal/palette windows
     PostPopFocus <hash>       // Hash of a viewport in the layout that gets a "popped focus" event
     HelpKey <key>
     Pinnable <boolean>        // Makes popovers pinnable (defaults to false)
     OpenPinned <boolean>

Basic Properties

These define the basic style and dimensions of the window.

  • Style: One of the available window styles: standard, palette, popoverRollOff, popoverClickOff, popoverPointAt.
  • Contents: This can be either the string "(layout)" followed by the name of the layout to restore an entire layout into the window, or a viewport type name followed by a matching viewport preset to restore that
  • Title: Title displayed in the window's titlebar, usually a message looking in the form of @table@msg@
  • Size: Size of the window's client area (i.e.: not including window decoration/borders), which may be overridden if the user has resized the window between innovations.
  • SizeMin: Minimum size below which the window cannot be resized smaller.
  • SizeMax : Maximum resizable size of the window.
  • Maximize: If true, the window is opened maximized on Windows.
  • PostRestoreCommand: Command to execute after the window opens.
  • SwitcherClass: For non-popover windows, this is the class used by the window's Switcher Bar.

Form Button Properties

These are used to set up how a layout.window button appears in a form.

  • Tooltip: Tooltip display on a layout.window button in a form
  • Icon: Resource name of the icon to display when layout.window is used as a button in a form.
  • HelpKey: Key used to look up help when used as a button in a form.

Popover Properties

These are used to modify the behavior of popover windows.

  • Opaque: Forces popover windows to be opaque. Useful for special case windows where the exact colors are important, such as color pickers.

viewport into the window. The latter avoids the need to create a complete layout if you just want to show a single viewport.

  • PointAtPopoverPreferSides: If true, a point-at popover will prefer to open to the left/right of the point-at location, rather than above/below it.
  • Pinnable: If true, this makes popovers pinnacle. Only click-off and point-at popovers can be pinned.
  • OpenPinned: If true and Pinnable is set, the popover will open pinned.
  • PostPopFocus: After opening a popover, the viewport with this viewport preset hash will receive a "popped focus" event, allowing it to do special post-restore behaviors like focusing an edit field.
  • ViewCanClosePopover: The viewport with this viewport preset hash has the ability to close the popover in certain situations, such as when hitting enter in an edit field performs and action and then dismisses the popover.

Instancing a Layout Window

layout.window is used to instance one of these config definitions as a window. The command is fairly simple:

layout.window hash:string <?open:boolean> <pin:boolean> <popUnderMouse:boolean>

In a form, it is commonly deployed as:

layout.window myWindowhash open:?

The pin argument will force pinnable popover windows to open as pinned. If popUnderMouse is set to false, a non-pointing popover will open at its last position instead of under the mouse. This is most commonly used with the pin argument.

Closed Window Config State

When the window is closed, the window size and position are stored in a LayoutWindowState hash in the root Frame atom of the config. This information is used when layout.window opens a previously-opened window, overriding the defined window size and position.

On quit, the hashes of pinned popover layout windows are stored in an OpenOnLaunch hash in the root Frame atom, so that they can be restored when the app is relaunched.