A workspace describes an arrangement of named panes within a window in a user interface.  You define this arrangement by starting with the root pane taking the entire window area, then recursively subdividing outer panes into two or more inner panes. You can have any number of levels of pane subdivision, and at any level, there are two ways to do it.

Workspace main window contains
   a top menu and toolbars pane,
   a central main pane containing {
      a left navigation pane,
      a right content pane
   },
   a bottom status bar pane
.

Workspace options dialogue contains
   a tabbed preferences pane,
   a tabbed security pane,
   a tabbed advanced pane
.

There are some options you can give to individual panes.  For split panes, you can set a size in pixels (from divider to edge) or as a percentage of the outer pane size.  You can set them as fixed, in which case the user cannot drag the divider.  You can set them as splittable, which allows the user to further subdivide them at run time.  For tabbed panes, you can set them as closable.  This puts up a red close glyph on the right of the pane's tab, allowing the user to close the tab by clicking on it.  Here is an example with some options set for split panes.

Workspace main window contains
   a 50 pixel fixed top menu and toolbars pane,
   a central main pane containing {
      a 30% left navigation pane,
      a splittable right content pane
   },
   a 25 pixel fixed bottom status bar pane
.

When you are developing your code, you build your user interface by showing objects in panes using a particular layouts.  In the definition file, you can specify that a particular pane display only layouts of a particular type (form, grid, lookup, etc.) or only objects of a particular class, or both.  Here is an example showing this.

Workspace options dialogue contains
   a tabbed preferences pane for preferences form layouts,
   a tabbed security pane for security options form layouts,
   a tabbed advanced pane for advanced options form layouts
.

As well as defining workspaces in your definition file, you can also create workspaces at run time.  This can be done using standard operations in the user interface, or programmatically in your code.  Such workspaces have all the features described here, and can also record the actual objects displayed in each pane, and the layouts used to display them.  This means that the standard operations Save Workspace and Restore Workspace can save and restore the exact state of a window in the user interface.

Syntax

Workspace = "workspace" WorkspaceName WorkspaceSize "contains" Panes ;
WorkspaceName = <symbol> { <symbol> } ;
WorkspaceSize = [ "size" <integer> "by" <integer> ] ;
Panes = Pane  { "," Pane } ;
Pane = "a" PaneSize PaneQualifiers PanePosition PaneName
       "pane" PaneContent [ "containing" "{" Panes "}" ] ;
PaneSize = [ <integer> ( "%" | "pixel" ) ] ;
PaneQualifiers = { ( "fixed" | "splittable" | "closable" ) } ;
PanePosition = ( "top" | "bottom" | "central" | "left" | "right" | "tabbed" ) ;
PaneName = <symbol> { <symbol> } ;
PaneContent = [ "for" [ TargetName ] [ PaneLayoutTypes ] "layouts" ] ;
TargetName = <symbol> { <symbol> } ;
PaneLayoutTypes = PaneLayoutType { "or" PaneLayoutType } ;
PaneLayoutType = ( "form" | "grid" | "lookup" | "tree" | "control" ) ;

See Grammar Notation in Syntax Sections for an explanation of the format and symbols used here

Description

Workspace

This defines a workspace.  You must give it a WorkspaceName, but the WorkspaceSize is optional.  You must include at least one Pane.

WorkspaceName

The name can consist of one or more symbols and must be unique within the package.

WorkspaceSize

If you include this optional clause, then you are specifying the width and height respectively in pixels of the top level pane in the workspace.

Panes

One or more Pane definitions, separated by commas.  You usually write each pane definition on a separate line.

Pane

When defining a pane, the only mandatory clauses are the PanePosition and PaneName.  To subdivide a pane into inner panes, include the containing { Panes } clause.  If you include this, you may not include a PaneContent clause.

PaneSize

You can specify size either in pixels or as a percentage.  Within an outer pane, all inner panes must use either pixels or percentages, but not a mixture.  If you give percentage sizes for all inner panes they must add up to 100%.  If you give pixel sizes for all inner panes you may not give a pixel size for the outer pane.

PaneQualifiers

If you specify the fixed qualifier, then this pane will have a fixed size, and the user will not be able to resize it by dragging a pane divider.  If you specify the splittable qualifier, then the user will be able to split this pane into inner panes at run time, using standard operations.  Both of these qualifiers are applicable to panes with any PanePosition except tabbed.  The closable qualifier is applicable only to tabbed panes.  If specified, the tab for the pane will have a close glyph, allowing the user to remove the pane along with its tab.

PanePosition

This specifies the position of a pane relative to its sibling inner panes within an outer pane.  You must specify this for all panes.  Within an outer pane, the positions of all the inner panes must be mutually compatible.  The allowed combinations are as follows.  There is no requirement on the ordering or inner panes.

PaneName

You must give all panes a name, which can comprise of one or more symbols.  Pane names must be unique within the entire workspace.

PaneContent

You can include this clause only if the pane is not subdivided into inner panes.  You can include a target class, layout types or both.  This clause restricts the content that can be shown in a pane.  Furthermore, if you request than an object be shown in a window, but don't specify a pane name, then this informs the choice of pane that the Persistate run time makes for you.

TargetName

This is the name of an object class in either the package you are defining, or in a package you imported using a package reference.  If you include this, then only objects of this class can be shown in the pane.

PaneLayoutTypes

You can include one or more of these to restrict the type of layout that can be shown in the pane.