Layout Windows

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.

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.

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.

• ‘’’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.

‘’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.