WklNavBar

Dim myWklNavBar As WklNavBar
Set myWklNavBar = Me!ControlName.Object

The navigation of an application shell: a column of symbols, or symbols with captions and group headers, with entries at the top (ungrouped or in groups) and entries at the bottom edge, count badges and one selected entry.

None

The bar switches between three modes: expanded (symbols, captions, group headers), compact (the narrow symbol column) and hidden. The user switches between expanded and compact with the toggle button at the top or with ToggleShortcut (Ctrl+B by default).

Events come only from the user. Every property and method called by code changes the bar silently: an application that opens a page in Navigate and then marks the entry of that page with SelectedKey cannot run into a loop. A click or Enter on an entry raises BeforeNavigate, where Cancel keeps the current entry (for example while the open page has unsaved changes), and then Navigate. Choosing the selected entry again raises both events again, so the user can return to the start of a page.

Groups, entries and the entry selected when the form opens are designed in design view (or by code there) and stored with the form. The designer (property sheet: row Custom [...], Opening the designer) edits them without code: the page Entries lists groups and entries in the order of the bar, adds, removes and moves them, and sets key, caption, symbol (chosen from a gallery of the Windows symbol font, searchable by code or name), place (top, a group, bottom edge), visibility, enabled state and the entry selected when the form opens; removing a group keeps its entries, ungrouped at the top. The pages Darstellung (mode, width, toggle button, colors, font) and Verhalten (pinning, shortcut, per-user memory) set the other designed properties; a preview shows the bar expanded and as the symbol column. OK writes every changed property into the form; a key used twice or an invalid shortcut keeps the designer open and names the problem. Badges are run-time values and are never stored; set them when the form opens and whenever the counts change.

Pinned decides where the expanded bar stands. Pinned (default), it stands beside the page and takes its width. Unpinned, the bar keeps the width of the symbol column, and the expanded bar lies over the page until the user chooses an entry, presses Esc or clicks outside it; the page never changes its size. A form never opens with the expanded bar lying over the page.

The bar is one stop in the tab order, like a list box. With the focus on it, Up and Down move between the toggle button, the group headers and the enabled entries, Home and End go to the first and last of them, Enter or Space act on the focused one (switch, fold the group, choose the entry), and Left and Right fold and unfold a focused group header; Tab moves on to the next control. While the expanded bar lies over the page, these keys move through it and the focus stays with the bar. When a key changes the width of the bar, Access rebuilds its window; the bar takes the focus back afterwards.

UI Automation presents the bar as a list named “Navigation”: the toggle button, the groups (also in the symbol column, where they have no header) with their entries, and the entries without a group. An entry's name includes its badge (“Sessions: 3”, with “(Warning)” or “(Error)” for those kinds, and “new” for a dot); disabled entries are reported as not available. Selecting or invoking an entry through UI Automation is the user's choice and raises BeforeNavigate and Navigate.

Inside a WklDockLayout the bar sets the size of its area through the layout's PaneSize; the user drags the layout's strip. Outside a layout it changes its own width.

Instead of designed entries, the bar can read its groups and entries from a table, query or SQL statement (RecordSource, KeyField, TextField … as in WklTreeView), so the navigation of an application is kept in one place. A row is a group when another row names it in ParentField; all other rows are entries. The designed entries stay stored with the form and come back when RecordSource is cleared. A row that cannot be taken as it is never stops the form: it is skipped or shown without the faulty value, and LoadProblems names it.

Each row can also name a target (TargetKindField, TargetField), which the bar then shows without code: a page in the subform control TargetControl, a form or a report. The user's choice runs BeforeNavigate, the check for unsaved changes of the page (ConfirmUnsavedChanges), shows the target, and then changes the selection and raises Navigate; if the target cannot be shown, the selection stays. NavigateOnOpen shows the target of the selected entry when the form opens. When a form that is the form target of an entry becomes the active window - a click on its window or document tab, Ctrl+F6, DoCmd.SelectObject or SetFocus in code, also for a pop-up form - the bar selects that entry without an event, as the navigation pane of Access marks the open object.

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 navigation of a shell form: the subform sfPage shows the page of the chosen entry.
Private Sub Form_Load()
    With Me!navMain.Object
        .Clear
        .AddItem "home", "Start", "E80F"
        .AddGroup "data", "Data"
        .AddItem "tables", "Tables", "E8A5", "data"
        .AddItem "sessions", "Sessions", "E716", "data"
        .AddItem "settings", "Settings", "E713", "", wnpBottom
        .SetBadge "sessions", 3, wskWarn
        .SelectedKey = "home"
    End With
    Me!sfPage.SourceObject = "frmHome"
End Sub
 
Private Sub navMain_BeforeNavigate(ByVal Key As String, Cancel As Integer)
    ' Stay on a page with unsaved changes.
    If Me!sfPage.Form.Dirty Then Cancel = True
End Sub
 
Private Sub navMain_Navigate(ByVal Key As String)
    Select Case Key
        Case "home": Me!sfPage.SourceObject = "frmHome"
        Case "tables": Me!sfPage.SourceObject = "frmTables"
        Case "sessions": Me!sfPage.SourceObject = "frmSessions"
        Case "settings": Me!sfPage.SourceObject = "frmSettings"
    End Select
End Sub

None

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

Gets or sets the key of the selected entry.

None

Property value: String – The key of an entry (case does not matter), or an empty string for none.

Setting the key raises no event. Hidden and disabled entries can be selected by code, so the bar can follow a page that the application opened by other means; a hidden selected entry is simply not highlighted, and an entry folded away in a collapsed group marks its group header instead. A key that no entry has raises wkeKeyNotFound. Set in design view, it is the entry selected when the form opens.

Read/write.

None

Declared by WklNavBar.

Property Get Mode() As WklNavBarMode
Property Let Mode(RHS As WklNavBarMode)

Gets or sets how much of the bar is shown.

None

Property value: `WklNavBarMode` – wnmExpanded (default), wnmCompact or wnmHidden.

Setting the mode by code raises no event; ModeChanged occurs only when the user switches. On an unpinned bar wnmExpanded opens the expanded bar over the page. Values outside 0-2 raise wkeInvalidValue.

The bar takes the width of its mode beside the page. Inside a WklDockLayout it sets the size of its area, as PaneSize would, and wnmHidden folds the area away (PaneCollapsed); the page in the neighboring area moves along. Without a layout the bar changes its own width, and the controls beside it stay where they are. The new width follows the property after the current event procedure has finished, because Access rebuilds the windows of the form's ActiveX controls for it.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets whether the expanded bar stands beside the page or lies over it.

None

Property value: Boolean – True (default): beside the page, taking its width; False: over the page, while the bar keeps the width of the symbol column.

An unpinned expanded bar lies over the page in a window of its own - also over subforms, which Access draws over ActiveX controls - without taking the focus from the form. It closes, with ModeChanged, when the user chooses an entry, presses Esc, clicks anywhere else or switches to another program, and it moves with the Access window. A form whose bar is designed or remembered unpinned and expanded opens with the symbol column.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the width of the expanded bar.

None

Property value: Long – Twips from 2400 to 7200 (160 to 480 pixels at 100 % scaling); default 3600.

Values outside the range raise wkeInvalidValue. The symbol column is always 48 pixels wide at 100 % scaling and grows with the display scaling.

The user sets the width by dragging: inside a WklDockLayout the layout's strip beside the expanded bar, otherwise the right edge of the expanded bar; the right edge of the bar lying over the page as well. A drag of the strip beside the symbol column is undone, and folding the bar's area with the strip hides the bar (ModeChanged with wnmHidden).

Read/write.

None

Declared by WklNavBar.

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

Gets or sets whether the toggle button (three lines) stands at the top of the bar.

None

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

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the key combination that switches the bar between expanded and compact.

None

Property value: String – A combination such as "Strg+B" (default), "Ctrl+Shift+N" or "F12"; modifiers in German or English (Strg/Ctrl, Umschalt/Shift, Alt); an empty string for none. The property returns the form of the language of the components (Strg+Umschalt+N in German, Ctrl+Shift+N in English).

A letter or a digit needs Ctrl or Alt; alone or with Shift only it would take characters away from the text boxes of the form, and such values raise wkeInvalidValue.

The combination works wherever the focus is on the form, in subforms as well, and the control that has the focus does not receive the key. In a text box with rich text formatting the key stays with Access, so Ctrl+B remains bold there. On a UserForm the combination works while the bar has the focus.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the background color.

None

Property value: OLE_COLOR – An OLE color; default the system color of button faces.

Under a Windows high contrast theme the bar draws with the theme's window, text and highlight colors instead of BackColor, ForeColor and AccentColor, and fills the selected entry with the highlight color.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the color of captions, symbols and group headers.

None

Property value: OLE_COLOR – An OLE color; default the system color of button text.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the color of the selection mark at the left edge of the selected entry.

None

Property value: OLE_COLOR – An OLE color; default the system highlight color.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the font of captions and group headers.

None

Property value: String – A font name; default "Segoe UI". An empty name raises wkeInvalidValue.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the size of captions.

None

Property value: Long – Points from 6 to 72; default 9. Group headers use one point less, in Segoe UI Semibold.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the mode, pinning, width and collapsed groups as text, to keep a user's arrangement.

None

Property value: String – JSON text such as {"format":"WklNavBar","version":1,"mode":"compact","pinned":true,"width":3600,"collapsedGroups":["data"]}; an empty string restores the design.

The selected entry is not part of the text: which page opens is the application's decision. Groups of the text that the bar no longer has are ignored. An unpinned expanded state is applied as the symbol column. A text not written by a WklNavBar raises wkeInvalidValue.

Read/write.

None

Declared by WklNavBar.

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

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

None

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

Remembered are mode, pinning, width and collapsed groups - the content of Layout - in the same storage as the layout controls (USysWklLayout in Access, the registry of the user on UserForms); see WklDockLayout.AutoSaveLayout. The state is restored once, when the bar first shows in form view, unless code set Mode, Pinned, ExpandedWidth, Layout or called Reset before; it is stored after every change by the user or by code and removed when it equals the design. Restoring raises no event. Inside a WklDockLayout the bar's mode decides the width of its area, also over a width the layout remembered.

Read/write.

None

Declared by WklNavBar.

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 – Up to 255 characters; empty (default) for “form name.control name”.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets all groups and entries as text, as they are stored with the form.

None

Property value: String – JSON text with the arrays groups (key, caption, collapsed, visible) and items (key, caption, glyph, group, position, visible, enabled); an empty string for none.

Setting the text replaces all groups and entries; the selection stays when its entry still exists. Code gets wkeInvalidValue for a text with an entry or group that cannot be added (no key, a duplicate key, an invalid glyph code, an unknown group); nothing changes then. When a form opens, a damaged stored text is read as far as possible, so the form always opens. Badges are not part of the text.

Read/write.

None

Declared by WklNavBar.

Sub AddGroup(ByVal Key As String, Optional ByVal Caption As String = "")

Adds a group for entries at the top.

Groups appear in the order they were added, below the ungrouped top entries. An empty key raises wkeInvalidValue, a key in use wkeDuplicateKey. A group and an entry may share a key.

None

Declared by WklNavBar.

Sub AddItem(ByVal Key As String, Optional ByVal Caption As String = "", Optional ByVal Glyph As String = "", Optional ByVal Group As String = "", Optional ByVal Position As WklNavBarPosition = wnpTop)

Adds an entry at the end of its group or area.

Bottom entries stand at the bottom edge, never scroll and have no group; a group for a bottom entry raises wkeInvalidValue, as do an empty key and an invalid glyph code. A key in use raises wkeDuplicateKey, an unknown group wkeKeyNotFound.

None

Declared by WklNavBar.

Sub RemoveItem(ByVal Key As String)

Removes an entry; when it was selected, no entry is selected afterwards (without an event).

None

None

Declared by WklNavBar.

Sub RemoveGroup(ByVal Key As String)

Removes a group with all its entries.

None

None

Declared by WklNavBar.

Sub Clear()

Removes all groups and entries; mode, pinning and width stay.

None

None

None

Declared by WklNavBar.

Sub SetBadge(ByVal Key As String, ByVal Count As Long, Optional ByVal Kind As WklStatusKind = wskNeutral, Optional ByVal Dot As Boolean = False)

Sets the count badge of an entry.

In the symbol column the badge sits at the upper right of the symbol, in the expanded bar at the right end of the row. Badges are not stored with the form.

None

Declared by WklNavBar.

Property Get BadgeCount(ByVal Key As String) As Long

Returns the count of an entry's badge.

Property value: Long – The count; 0 for no badge or a dot.

Read-only.

None

Declared by WklNavBar.

Property Get ItemVisible(ByVal Key As String) As Boolean
Property Let ItemVisible(ByVal Key As String, RHS As Boolean)

Gets or sets whether an entry is shown.

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

Read/write.

None

Declared by WklNavBar.

Property Get ItemEnabled(ByVal Key As String) As Boolean
Property Let ItemEnabled(ByVal Key As String, RHS As Boolean)

Gets or sets whether the user can choose an entry.

Property value: Boolean – True (default); False draws the entry dimmed, and clicks and keys pass it by. Code can still select it.

Read/write.

None

Declared by WklNavBar.

Property Get ItemCaption(ByVal Key As String) As String
Property Let ItemCaption(ByVal Key As String, RHS As String)

Gets or sets the caption of an entry.

Property value: String – Any text; empty for the key.

Read/write.

None

Declared by WklNavBar.

Property Get ItemGlyph(ByVal Key As String) As String
Property Let ItemGlyph(ByVal Key As String, RHS As String)

Gets or sets the symbol of an entry.

Property value: String – A glyph code as for AddItem; invalid codes raise wkeInvalidValue.

Read/write.

None

Declared by WklNavBar.

Property Get ItemGroup(ByVal Key As String) As String

Returns the group of an entry.

Property value: String – The key of its group, or an empty string.

Read-only.

None

Declared by WklNavBar.

Property Get ItemPosition(ByVal Key As String) As WklNavBarPosition

Returns where an entry stands.

Property value: `WklNavBarPosition` – wnpTop or wnpBottom.

Read-only.

None

Declared by WklNavBar.

Property Get ItemExists(ByVal Key As String) As Boolean

Returns whether an entry with the key exists.

Property value: Boolean – True or False; never raises an error.

Read-only.

None

Declared by WklNavBar.

Property Get ItemCount() As Long

Returns the number of entries, top and bottom, shown or not.

None

Property value: Long – 0 or more.

Read-only.

None

Declared by WklNavBar.

Property Get ItemKey(ByVal Index As Long) As String

Returns the key of the entry at a place.

Property value: String

Read-only.

Dim i As Long
With Me!navMain.Object
    For i = 0 To .ItemCount - 1
        Debug.Print .ItemKey(i), .ItemCaption(.ItemKey(i))
    Next
End With

Declared by WklNavBar.

Property Get GroupCollapsed(ByVal Key As String) As Boolean
Property Let GroupCollapsed(ByVal Key As String, RHS As Boolean)

Gets or sets whether a group is folded in the expanded bar.

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

The user folds a group by clicking its header. The symbol column always shows all entries, with lines between the groups. Set in design view, the value is the group's state when the form opens; folded groups are part of Layout.

Read/write.

None

Declared by WklNavBar.

Property Get GroupVisible(ByVal Key As String) As Boolean
Property Let GroupVisible(ByVal Key As String, RHS As Boolean)

Gets or sets whether a group with all its entries is shown.

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

Read/write.

None

Declared by WklNavBar.

Property Get GroupCount() As Long

Returns the number of groups.

None

Property value: Long – 0 or more.

Read-only.

None

Declared by WklNavBar.

Property Get GroupKey(ByVal Index As Long) As String

Returns the key of the group at a place.

Property value: String

Read-only.

None

Declared by WklNavBar.

Sub Toggle()

Switches between expanded and compact as the toggle button does; a hidden bar becomes expanded. Raises no event.

None

None

None

Declared by WklNavBar.

Sub Reset()

Restores the design: mode, pinning, width and the folding of the groups as designed. Content, badges and selection stay.

None

None

None

Declared by WklNavBar.

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

Gets or sets the table, query or SQL statement the bar reads its groups and entries from.

None

Property value: String – A table or query name, or an SQL statement; an empty string (default) for the designed entries (Items).

The bar is bound when RecordSource and KeyField are set. It reads the source the first time it needs its content - when the form shows it, also in design view, or when code reads or changes entries - and again on Requery. Saved queries may refer to form controls; the bar fills such parameters as Access does when a form opens the query. Setting RecordSource or a field property reads the source again on next use; the designed entries are shown in between.

The rows replace the designed entries in the bar, but Items keeps returning the designed entries, and they are what is stored with the form. Code can still add, change and remove entries of a bound bar; the changes last until the next Requery.

A source that cannot be read leaves the designed entries in the bar; the error is in LoadProblems, and Requery raises wkeSourceError with the text Access reported.

The designer's page “Datenquelle” sets the source, the fields and the targets without code and shows what the bar will read. Its button “Vorlagetabelle anlegen” creates a table with the fields Key, Caption, Glyph, ParentKey, SortOrder, Visible, Enabled (both with the default value Yes), Place, TargetKind and Target, writes the designed entries into it - a group becomes a row its entries name in ParentKey; a group without entries is left out, because no row names it - and binds the bar to the table.

Rules for the rows:

• A row is a group when another row names it in ParentField; all other rows are entries. An empty parent field means an ungrouped entry. The bar has one level of groups: a row below an entry of a group, and a group that has a parent itself, are skipped.
• Rows without key and repeated keys (the first row wins; case does not matter) are skipped; an unknown parent skips the row as well.
• An invalid glyph code, place or target kind is ignored and the row is shown. A target in a group row is ignored, because choosing a group header folds the group.
• Entries at the bottom have no group: a bottom entry with a parent is shown ungrouped at the bottom.
• Siblings follow SortField: numbers by value, texts without regard to case, Null last; rows with equal values keep the order of the source.

Read/write.

' Binds the bar to the template table of the designer; usually set once on the page
' "Datenquelle" instead. Entries with the target kind Subform are shown in sfPage.
Private Sub Form_Load()
    With Me!navMain.Object
        .RecordSource = "tblNavigation"
        .KeyField = "Key": .TextField = "Caption": .GlyphField = "Glyph"
        .ParentField = "ParentKey": .SortField = "SortOrder"
        .VisibleField = "Visible": .EnabledField = "Enabled": .PlaceField = "Place"
        .TargetKindField = "TargetKind": .TargetField = "Target"
        .TargetControl = "sfPage"
        If Len(.LoadProblems) > 0 Then Debug.Print .LoadProblems
    End With
End Sub

Declared by WklNavBar.

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

Gets or sets the field with the key of a row; required for a bound bar.

None

Property value: String – A field name of RecordSource. Its values become the keys of the entries and groups (SelectedKey, Navigate, ParentField).

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the caption of an entry or group.

None

Property value: String – A field name, or an empty string to show the key.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the symbol of an entry.

None

Property value: String – A field name; its values are glyph codes of the symbol font such as E80F. Empty: entries without symbol.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the key of the group an entry belongs to.

None

Property value: String – A field name; empty: no groups.

A row that another row names in this field is a group. This is the rule of WklTreeView, so the same table can be shown in a tree.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the order of an entry among its siblings, and of the groups among each other.

None

Property value: String – A field name; empty: the order of the source.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the Yes/No field that shows or hides an entry or group.

None

Property value: String – A field name; empty: every row is shown. Null counts as Yes.

A Yes/No column of an Access table is never Null: a row added without a value is No and therefore hidden. Give the column the default value Yes.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the Yes/No field that lets the user choose an entry.

None

Property value: String – A field name; empty: every entry is enabled. Null counts as Yes.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field that puts an entry at the top or at the bottom edge.

None

Property value: String – A field name; its values are 0 or 1, top or bottom, oben or unten; Null means top. Empty: every entry at the top.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the kind of target of an entry.

None

Property value: String – A field name; its values are the numbers of WklNavTargetKind or the words Subform, Form, Report (also Unterformular, Formular, Bericht); Null means no target.

A form target opens a window of its own. When that form becomes the active window later - the user clicks its window or document tab, presses Ctrl+F6, or code calls DoCmd.SelectObject or SetFocus; a pop-up form as well - the bar selects the entry of that form, without BeforeNavigate or Navigate and without showing anything, as the navigation pane of Access marks the open object. A form opened by other means than the bar is followed the same way. The selection stays when it is an entry of that form already; among several entries of the form, the first shown and enabled one is selected. The bar follows only in form view on an Access form, not on a UserForm.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the field with the name of the form or report an entry shows.

None

Property value: String – A field name. An entry with a target kind but without a name has no target; LoadProblems names it.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets the subform control that shows targets of the kind wntSubform.

None

Property value: String – The name of a subform control on the form of the bar.

When the user chooses an entry with a subform target, the bar sets the control's SourceObject to the target, unless the control already shows it. A target kind wntSubform without a usable TargetControl shows a message and keeps the selection.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets whether the bar shows the target of the selected entry when the form opens.

None

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

When the form opens, the bar shows the target of the entry selected in the design (SelectedKey) once, as soon as its window exists, without asking about unsaved changes and without events: nothing was shown before. Entries without target show nothing. To open a different start page, set SelectedKey in Form_Load.

Read/write.

None

Declared by WklNavBar.

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

Gets or sets whether the bar asks before it leaves a page with unsaved changes.

None

Property value: Boolean – True (default): the bar asks whether to save the changes; False: it does not ask.

The bar checks only when a subform target would replace the page in TargetControl and that page has an unsaved record (Form.Dirty). A form or report target opens a window of its own and leaves the page as it is, and choosing the entry of the page already shown replaces nothing; neither asks.

The bar asks as Access does when a changed design is closed: “Do you want to save the changes to '<caption of the page's entry>'?” in a message box titled Microsoft Access. Yes saves, then changes the page; No undoes the changes, then changes the page; Cancel or Esc stays. If Access refuses to save the record - a validation rule, a required field - the bar shows Access's own message and the page stays. Whenever the page stays, the selection does not change and no Navigate follows.

The check runs after BeforeNavigate, so an application that checks pages itself can still cancel there.

With False the bar changes the page right away; Access then saves the record itself, as it does whenever a subform control gets another SourceObject.

Read/write.

None

Declared by WklNavBar.

Sub Requery()

Reads the groups and entries again from RecordSource.

None

The selection, the badges and the folded groups stay for keys that still exist; mode, pinning and width are not touched. Raises no event. Raises wkeNotConfigured when RecordSource or KeyField is not set, and wkeSourceError when Access cannot read the source.

None

Declared by WklNavBar.

Property Get ItemTargetKind(ByVal Key As String) As WklNavTargetKind

Gets the kind of target of an entry.

Property value: `WklNavTargetKind` – A WklNavTargetKind; wntNone for an entry without target, also for every designed entry.

Read-only.

None

Declared by WklNavBar.

Property Get ItemTarget(ByVal Key As String) As String

Gets the name of the form or report an entry shows.

Property value: String – The name, or an empty string for an entry without target.

Read-only.

None

Declared by WklNavBar.

Property Get LoadProblems() As String

Gets what went wrong when the bar last read RecordSource.

None

Property value: String – One line per problem: the read error, then each row that was skipped or shown without a faulty value (“Zeile 4: …”), counted in the order the rows were read. An empty string when there was nothing to report or the bar is not bound.

The bar never refuses a faulty table, so a form always opens; read this property while setting up a navigation table.

Read-only.

None

Declared by WklNavBar.

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 bar, its text and the selection mark while BackColor, ForeColor and AccentColor keep their system defaults (light keeps them as Windows draws them; dark and a database color set replace them), and the text of disabled entries; colors you set win; 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 WklNavBar.

Event BeforeNavigate(ByVal Key As String, ByRef Cancel As Integer)

Occurs when the user chooses an entry, before the selection changes.

Occurs on a click and on Enter, also on the entry already selected; never when code sets SelectedKey.

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

None

Declared by WklNavBar.

Event Navigate(ByVal Key As String)

Occurs after the user chose an entry and the selection changed.

Open the page of the entry here. An unpinned expanded bar has closed when the event occurs.

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

None

Declared by WklNavBar.

Event ModeChanged(ByVal Mode As WklNavBarMode)

Occurs after the user switched the bar with the toggle button or the shortcut, or closed the expanded bar lying over the page.

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

None

Declared by WklNavBar.