WklDockLayout

Dim myWklDockLayout As WklDockLayout
Set myWklDockLayout = Me!ControlName.Object

A control placed behind the areas of a form that arranges them in zones - left, top, right, bottom and the fill area in the middle - whenever the form changes size, with a splitter strip after every docked area that the user drags to resize it or double-clicks to fold it away.

None

Draw the layout over the areas in the detail section and send it to the back (Arrange › Send to Back). By default (FillSection) it then fills the visible part of the detail section at every size of the form window - title, search and commands belong into the form header, status lines into the form footer - and arranges its areas in that room; no form code is needed. With FillSection off it keeps its own rectangle; anchor it in both directions (Horizontal Anchor and Vertical Anchor: Both) so Access resizes it with the window. Leave the anchors of the areas to the designer (property Custom, […]): with Set up on applying it gives each area on OK the horizontal anchor of its place (the fill area and the areas above and below it left and right, an area on the right right, an area on the left left) and keeps the vertical anchor at top; the layout reads these anchors at run time, so the areas reach beyond 22 inches. Do not set the anchors of areas by hand or by code: Access stretches anchored controls without telling the object model, and the layout only accounts for the anchors the designer gives.

The areas are the controls named in Panes, or - when Panes is empty - the controls lying inside the layout, taken off its edges in turn: a control along one whole edge becomes a docked area there (the thinnest first), and the largest control left over fills the rest. Every docked area keeps its designed width or height; when the layout becomes too small, the fill area shrinks first, then the docked areas from the inside out, each down to its minimum size.

The layout itself is visible only as the splitter strips; elsewhere it neither covers the areas nor takes the mouse. A drag shows a half-transparent strip while the mouse moves and arranges once when the button is released; Esc cancels. A collapsed area keeps its strip at the edge, so a double click or a drag brings it back.

PaneSize, PaneCollapsed, PaneZone and Layout act only in form view and are not saved with the form, so a run-time arrangement never changes the design.

Without any code, the layout remembers the arrangement per Windows user (AutoSaveLayout, on by default): every change by the user or by code is stored, and the next time the form opens the arrangement comes back. In Access it goes into the local table USysWklLayout of the database (created with the first stored arrangement; one row per Windows user and layout, so a front end shared by several users keeps them apart); on Excel and Word UserForms into the registry of the current user. An arrangement equal to the design is not stored, so Reset removes it. Layout remains for code that keeps arrangements elsewhere: a text set before the form shows wins over the remembered one.

Tab groups: areas with the same group in Panes share one place in their zone, under a tab strip with one tab per card (PaneCaption); one card is shown at a time, the others are hidden in the same rectangle. The group lies where its first card stands in the docking order; size, folding and zone belong to the whole group. The user chooses a card with a click on its tab, code with GroupPane; AfterTabChange reports every switch with its reason.

Keyboard: F6 and Shift+F6 move the focus from area to area in docking order, around the end - wherever the focus is on the form; this replaces Access's own F6, which steps between the form's sections. Layouts nested in each other (a page form with its own layout in an area of a shell's layout) form one cycle: F6 steps through the page's areas where the page stands in the shell's order and then goes on to the shell's next area. The layout is also a tab stop: Tab and Shift+Tab step through its splitter strips and go on to the next control after the last one; on a strip the arrow keys across it change the size of its area by 8 pixels (Ctrl+arrow by 1 pixel), Home and End to its limits, and Enter or Space fold the area away and back, each with BeforeLayoutChange and AfterLayoutChange like a drag. A group's tab strip is a tab stop too, just before the group's splitter strip: the left and right arrow keys show the neighboring card, Home and End the first and last one, without wrapping at the ends. UI Automation presents the layout as a pane whose children are its strips, each a slider (UI Automation Thumb) named after its area and zone (“Trennleiste lstNav, links”) with the area's size in twips as value, which a client can set, and an expand/collapse state; a tab strip is a Tab named after its group whose TabItems are the cards, named by their tab text and selectable.

On Excel and Word UserForms the layout follows the size of the UserForm itself, keeping the distance to the right and bottom edge it had when the form was first shown - also without code in UserForm_Resize. Sizes are twips there too (1 point = 20 twips).

An ActiveX control: inserted into a form in design view (Form Design › Controls › ActiveX Controls); reports are not supported. VBA reaches it through the Object property of the control, where ControlName is the name of the control on the form.

' The layout remembers each user's arrangement by itself. A button gives the user the
' designed arrangement back; the remembered one is removed with it.
Private Sub cmdDefaultLayout_Click()
    Me!Layout1.Object.Reset
End Sub

None

Property Get Panes() As String
Property Let Panes(RHS As String)

Gets or sets the areas of the layout, their zones and minimum sizes, in docking order.

None

Property value: String – Entries separated by semicolons, each Name=Zone or Name=Zone,MinSize with the zones Left, Top, Right, Bottom and Fill and the minimum size in twips, for example sfNavigation=Left,1500; sfDetails=Bottom; sfMain=Fill; Name=Zone:Group makes the area a card of a tab group, for example sfProps=Right:Seite; sfMemo=Right:Seite; a card with a minimum size names the group before the size, Name=Zone:Group,MinSize, for example sfEditMain=Right:Seite,3402 (Right,3402:Seite is refused); empty (default): the controls inside the layout, by position (no tab groups).

An earlier entry is docked further out and spans the full height or width that is left when its turn comes. A tab group is one area: its minimum size is the largest minimum size of its cards, so it is enough to give the size on one card. An entry that does not follow the form raises wkeInvalidValue at once; a name the form does not have raises it when the layout first arranges. Changing the value in form view makes the layout read its areas anew, as Refresh does.

Read/write.

None

Declared by WklDockLayout.

Property Get MinPaneSize() As Long
Property Let MinPaneSize(RHS As Long)

Gets or sets the smallest width or height of an area whose Panes entry names no minimum size.

None

Property value: Long – Twips; default 0.

Read/write.

None

Declared by WklDockLayout.

Property Get SplitterSize() As Long
Property Let SplitterSize(RHS As Long)

Gets or sets the width of the splitter strips.

None

Property value: Long – Twips; default 75 (5 pixels at 96 dpi).

Read/write.

None

Declared by WklDockLayout.

Property Get BackColor() As OLE_COLOR
Property Let BackColor(RHS As OLE_COLOR)

Gets or sets the color of the splitter strips.

None

Property value: OLE_COLOR – An OLE_COLOR; default the system color for buttons (vbButtonFace).

Read/write.

None

Declared by WklDockLayout.

Property Get Layout() As String
Property Let Layout(RHS As String)

Gets or sets the zones, sizes and collapsed areas as text, to keep a user's arrangement.

None

Property value: String – JSON text such as {"format":"WklDockLayout","version":1,"panes":[{"name":"sfNav","zone":"left","size":3000,"collapsed":false}]}; an empty string restores the design.

Areas of the text that the form no longer has are ignored, and areas added to the form since keep their design, so a stored text never breaks a changed form. A text not written by a WklDockLayout raises wkeInvalidValue. Set in design view, the text is kept and applied when the form opens.

Read/write.

None

Declared by WklDockLayout.

Property Get PaneSize(ByVal Name As String) As Long
Property Let PaneSize(ByVal Name As String, RHS As Long)

Gets or sets the width (left and right zone) or height (top and bottom zone) of an area.

Property value: Long – Twips; the layout limits it when arranging, so that the area keeps its minimum size and leaves room for the others.

Setting the value arranges at once and raises no event. An unknown name raises wkeKeyNotFound; in design view wkeNotConfigured.

A WklNavBar in an area sets that area's size and folding itself, from its Mode and ExpandedWidth, and adopts the size the user drags the strip to; code sizes such an area through the bar's properties rather than through PaneSize.

Read/write.

None

Declared by WklDockLayout.

Property Get PaneCollapsed(ByVal Name As String) As Boolean
Property Let PaneCollapsed(ByVal Name As String, RHS As Boolean)

Gets or sets whether an area is folded away.

Property value: Boolean – True when the area is hidden and its room given to the others; its splitter strip stays at the edge.

Access refuses to hide the control that has the focus; that area then stays where it was.

Read/write.

None

Declared by WklDockLayout.

Property Get PaneZone(ByVal Name As String) As WklDockZone
Property Let PaneZone(ByVal Name As String, RHS As WklDockZone)

Gets or sets the zone of an area.

Property value: `WklDockZone` – A WklDockZone; the area keeps its size and its place in the docking order.

Read/write.

None

Declared by WklDockLayout.

Property Get PaneNames() As String

Returns the names of the areas in docking order, from Panes or found by position.

None

Property value: String – Control names separated by semicolons; in design view read anew from the form each time.

Read-only.

None

Declared by WklDockLayout.

Sub Refresh()

Reads the positions of the areas anew from the form, for example after code moved or resized controls; the user's arrangement - the remembered one as well - is dropped and hidden areas are shown again.

None

None

None

Declared by WklDockLayout.

Sub Reset()

Restores the design: sizes and zones as designed, no area collapsed. The remembered arrangement of the user is removed.

None

None

None

Declared by WklDockLayout.

Sub Arrange()

Arranges the areas at once in the current size, for example after code moved or resized one of them.

None

The arrangement follows the zones, sizes and folded areas of the layout, not the Visible property of the controls: an area hidden by code keeps its room, and Arrange does not show it again. To take an area away at run time, fold it with PaneCollapsed; to read new positions after code moved controls for good, call Refresh.

None

Declared by WklDockLayout.

Property Get AutoSaveLayout() As Boolean
Property Let AutoSaveLayout(RHS As Boolean)

Gets or sets whether the layout remembers the arrangement per Windows user and restores it when the form opens.

None

Property value: Boolean – True (default) or False.

The arrangement is restored once, when the layout first arranges in form view, and stored after every change by the user or by code; a new size of the form changes no arrangement and stores nothing. Set the value to False in the property sheet, or in Form_Open, to keep each opening at the design - for example when code restores arrangements from a table of its own through Layout. Switching it off does not remove what was stored.

Storage: in Access the table USysWklLayout (fields UserName as DOMAIN\name, LayoutKey, Layout, Changed); Access treats tables named USys... as system tables and hides them unless system objects are shown. On UserForms the registry key HKEY_CURRENT_USER\Software\The White Knight Labs\Access Framework\Layouts, one value per LayoutKey. A database opened read-only cannot store; the arrangement is then simply not remembered. Areas the form no longer has are ignored when restoring, as for Layout.

Read/write.

None

Declared by WklDockLayout.

Property Get LayoutKey() As String
Property Let LayoutKey(RHS As String)

Gets or sets the name under which the arrangement is remembered.

None

Property value: String – Text of up to 255 characters; empty (default): the name of the form and of the control, such as frmOrders.Layout1.

Set a key of its own when the same form must keep several arrangements, or on UserForms, where UserForm1.Layout1 in two workbooks would share one arrangement. Set it in the property sheet or in Form_Open, before the layout first arranges.

Read/write.

None

Declared by WklDockLayout.

Property Get FillSection() As Boolean
Property Let FillSection(RHS As Boolean)

Gets or sets whether the layout always fills the visible part of the detail section, whatever its size and place in design view.

None

Property value: Boolean – True (default): the layout takes the inside of the form window without the form header and footer (on a UserForm the inside of the UserForm) and follows every size of the window; False: the layout keeps its own rectangle and follows its anchors.

With FillSection the form's width and the detail section's height are narrowed back to the window when it shrinks, so no scroll bars remain. With False this does not happen: once the window has grown beyond the form's designed width, Access widens the form to the areas the layout arranged and keeps the anchored layout at that width when the window shrinks again - a horizontal scroll bar remains until the form is opened anew. Use False only where the layout must keep a rectangle of its own, for example beside other controls in the detail section. With False the layout arranges where it stands now and as large as its window is: code that moves or sizes it (Left, Top, Width, Height) and calls Arrange gets the areas in the new rectangle (from 1.45.2; before, they stayed at the place of the design). After code has set Width or Height of a layout that Access anchors, the form keeps reporting that value while the window grows with the anchors; compute nothing from it - the layout follows its window. Controls in the detail section that are not areas are covered; the designer names them. Where there is no detail section to fill - the layout on a tab page or in a form header or footer, or a form not shown yet - the layout arranges in its own rectangle as with False. Forms saved before this property existed fill the section when opened with this version. The layout fills at most 31 680 twips (22 logical inches: window pixels divided by the Windows scaling) in each direction, the largest control Access allows; on a larger window the rest stays empty (from 1.50.1).

Read/write.

None

Declared by WklDockLayout.

Property Get GroupPane(ByVal Group As String) As String
Property Let GroupPane(ByVal Group As String, RHS As String)

Gets or sets the card a tab group shows.

Property value: String – The name of the card's control.

Form view only. Setting it shows the card, raises AfterTabChange with wtcCode and no BeforeTabChange - code has decided already. When the focus is in the card that goes, the new card gets it first: Access refuses to hide the control that has the focus (error 2165). Moving the focus out of a subform saves its changed record, as a click into another subform does. The card shown is part of the user's arrangement and comes back the next time the form opens (AutoSaveLayout). Errors: wkeKeyNotFound for an unknown group or area, wkeInvalidValue for an area of another group.

Read/write.

' Show the notes of the record when the user asks for them.
Private Sub cmdNotes_Click()
    Me!Layout1.Object.GroupPane("Seite") = "sfMemo"
End Sub

Declared by WklDockLayout.

Property Get PaneCaption(ByVal Name As String) As String
Property Let PaneCaption(ByVal Name As String, RHS As String)

Gets or sets the text of a card's tab.

Property value: String – The text; empty (default): the caption of the form the subform shows, or else the control name.

Set in design view - in the designer, page Bereiche, column Register - it is saved with the form; set in form view it applies until the form closes.

Read/write.

None

Declared by WklDockLayout.

Property Get GroupNames() As String

Gets the names of the tab groups in docking order, separated by semicolons; empty without groups.

None

Property value: String

Read-only.

None

Declared by WklDockLayout.

Property Get PaneGroup(ByVal Name As String) As String

Gets the tab group an area belongs to.

Property value: String – The name of the group; empty when the area is in none.

Read-only.

None

Declared by WklDockLayout.

Property Get ShortcutKeys() As String
Property Let ShortcutKeys(RHS As String)

Gets or sets the key combinations of the whole form that raise the event Shortcut.

None

Property value: String – Combinations in SendKeys notation, as in the AutoKeys macro of Access, separated by semicolons: ^1;^2;^N;^S;{F5};{ESC}. ^ is Ctrl, + Shift, % Alt; then one letter or digit, or a named key in braces (F1 to F24, ESC, ENTER, TAB, BS, DEL, INS, HOME, END, PGUP, PGDN, UP, DOWN, LEFT, RIGHT). Empty (default) for none. A letter or digit without Ctrl or Alt, an unknown key, or a combination listed twice raises wkeInvalidValue, and the list stays as it was.

An application shell built on the layout - navigation, a list and a detail area as subforms - needs keys that work wherever the focus rests: Ctrl+1 to switch the page, Ctrl+N for a new record, F5 to read again. Access offers this only per database (the AutoKeys macro) or per form without its subforms (KeyPreview). The layout watches every key the user presses in its form, subforms included, before Access and the control with the focus see it, and raises Shortcut for a listed combination.

The list is saved with the form and can be set in design view. The keys are watched in form view on an Access form; on Excel and Word UserForms the layout reports none. A modal dialog or another form in front receives its keys as usual.

Read/write.

None

Declared by WklDockLayout.

Property Get ColorScheme() As WklColorScheme
Property Let ColorScheme(RHS As WklColorScheme)

Gets or sets the color scheme the control draws in.

None

Property value: `WklColorScheme` – wcoAutomatic (default), wcoLight, wcoDark or wcoHighContrast.

wcoAutomatic follows, in this order, Windows high contrast mode, then the color set of the database design (Access: Design › Themes or Colors), and draws light when the database has no design or the control is on an Excel or Word UserForm. Office's own design setting and the Windows app mode are not followed: a database looks the same on every PC. In high contrast mode the control always uses the system colors. The scheme colors the background and the bars between the areas (while BackColor keeps the system default), the grip dots and the tab strips of tab groups; a BackColor you set wins over the scheme. Every text keeps a contrast of at least 4.5:1. The control reads the database design after it is first drawn, never while Access draws the form, and again when the form opens anew. The value is saved with the form.

Read/write.

None

Declared by WklDockLayout.

Event BeforeLayoutChange(ByVal Pane As String, ByRef Size As Long, ByRef Collapsed As Boolean, ByRef Cancel As Integer)

Occurs after the user released a dragged splitter strip or double-clicked it, before the areas move.

Changes made by code (PaneSize, PaneCollapsed, PaneZone, Layout, Reset) and new sizes of the form raise no event.

In a form module: Private Sub <ControlName>_BeforeLayoutChange(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklDockLayout.

Event AfterLayoutChange(ByVal Pane As String)

Occurs after the areas moved because the user dragged or double-clicked a splitter strip.

In a form module: Private Sub <ControlName>_AfterLayoutChange(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklDockLayout.

Event BeforeTabChange(ByVal Group As String, ByVal Pane As String, ByRef Cancel As Integer)

Occurs when the user chooses another card of a tab group - a click on its tab, an arrow key on the tab strip or a screen reader - before the card is shown.

Not raised for GroupPane set by code or when the remembered card comes back.

In a form module: Private Sub <ControlName>_BeforeTabChange(...). Parameters passed by reference can be changed by the procedure.

None

Declared by WklDockLayout.

Event AfterTabChange(ByVal Group As String, ByVal Pane As String, ByVal Reason As WklTabChangeReason)

Occurs after a tab group shows another card.

This is the one place to load what a card shows - its SourceObject, a record source, the commands that belong to it - because it comes with every switch, also with GroupPane by code, as Access's tab control raises Change when code sets its Value. When the form opens, the card shown first raises no event (Access's tab control raises none either); only a remembered card other than the group's first one is reported, with wtcRestore. Load the first card in Form_Load; see How to: Build a side bar with cards.

In a form module: Private Sub <ControlName>_AfterTabChange(...). Parameters passed by reference can be changed by the procedure.

Private Sub Layout1_AfterTabChange(ByVal Group As String, ByVal Pane As String, ByVal Reason As Long)
    ' Fill the blocked list only when it is shown for the first time.
    If Pane = "sfBlocked" And Me!sfBlocked.SourceObject = "" Then
        Me!sfBlocked.SourceObject = "frmBlocked"
    End If
End Sub

Declared by WklDockLayout.

Event Shortcut(ByVal Key As String, ByRef Handled As Boolean)

Occurs when the user presses a combination of ShortcutKeys anywhere in the form, in a subform as well.

The event occurs before Access acts on the key, so Handled = True keeps Access from saving a record on Shift+Enter or from moving between sections on F6. A form without a Shortcut procedure loses no key, because Handled stays False. While an event procedure of the same layout runs, keys are not reported. Nested layouts that list the same combination each raise Shortcut until one of them takes the key.

In a form module: Private Sub <ControlName>_Shortcut(...). Parameters passed by reference can be changed by the procedure.

Private Sub Form_Load()
    Me!Layout1.Object.ShortcutKeys = "^1;^2;^N;{F5}"
End Sub
 
Private Sub Layout1_Shortcut(ByVal Key As String, Handled As Boolean)
    Select Case Key
        Case "^1": Me!sfMain.SourceObject = "frmSessions": Handled = True
        Case "^2": Me!sfMain.SourceObject = "frmCertificates": Handled = True
        Case "^N": Me!sfMain.Form!Grid1.Object.NewRecord: Handled = True
        Case "{F5}": Me!sfMain.Form!Grid1.Object.Requery: Handled = True
    End Select
End Sub

Declared by WklDockLayout.