WklActionBar

Dim myWklActionBar As WklActionBar
Set myWklActionBar = Me!ControlName.Object

The header of a page or an application shell: a band with title, subtitle and status, and below it a command row with a primary command, split buttons, a More menu and a group at the right edge.

None

One bar serves a whole shell. Place it above the subform that shows the pages and let the shell set the commands of the page it shows - in one assignment as JSON (Commands) or one by one (AddCommand). Every choice arrives in one event, CommandClick(Key): a click, an entry of a menu, the menu of a split button, an access key, a shortcut, or Invoke by a screen reader.

The bar measures its buttons itself. When the row is too narrow, commands leave it from the end and appear at the end of the More menu; the primary command leaves last, and the right group (wcpRight, for example Export and Refresh) always stays. Commands with wcpMenu are always in More. A command with children (Parent of other commands) is a split button: its main part runs the command, its arrow opens the children.

An & in a caption marks the access key; Alt and the letter run the command, or open More - from any control of the form. A letter the bar does not use goes on to Access. A command's Shortcut works anywhere in the form, subforms included, while the form is shown; list each combination in one place only - in the bar or in WklDockLayout.ShortcutKeys. Shortcuts are not watched on Excel and Word UserForms.

Commands set in design view are stored with the form. Set in form view, they are not a change of the form, so a shell that fills the bar per page does not ask to be saved. CommandClick runs after the click, key or menu has been handled, so the procedure may show a message box or change the page.

The band takes BackColor and ForeColor; the command row keeps the window color, so the buttons stay readable on a dark band. In high contrast mode the bar uses the system colors. Screen readers hear a toolbar named by the title, with a button per command.

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.

Private Sub ShowPage(ByVal page As String)
    Me!sfPage.SourceObject = page
    With Me!barShell.Object
        .Caption = Me!sfPage.Form.Caption
        .Subtitle = Nz(Me!sfPage.Form.Tag, "")
        .ClearCommands
        .AddCommand "neu", "&Neu", "E710", wcpStandard, "^N"
        .AddCommand "bearbeiten", "Bearbei&ten", "E70F"
        .AddCommand "issue", "&Issue key ...", "E8D7", wcpPrimary
        .AddCommand "lock", "&Lock key ...", "", wcpMenu
        .AddCommand "export", "E&xportieren ...", "EDE1", wcpRight
        .AddCommand "refresh", "&Aktualisieren", "E72C", wcpRight, "{F5}"
    End With
End Sub
 
Private Sub barShell_CommandClick(ByVal Key As String)
    RunAreaCommand Key
End Sub

None

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

Gets or sets the title in the band.

None

Property value: String – The title; empty (default) shows the caption of the form the bar stands on.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the line under the title.

None

Property value: String – The text; empty (default) for none.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the color of the band.

None

Property value: OLE_COLOR – An OLE color; default the window background. The command row below keeps the window color.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the color of the title, and of the subtitle while SubtitleForeColor is -1.

None

Property value: OLE_COLOR – An OLE color; default the window text color. Choose it with enough contrast to BackColor.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets all commands as JSON text.

None

Property value: String – A JSON array of objects, one per command, in order: key and caption are required; glyph, placement (standard, primary, menu, right), shortcut, parent, tooltip, beginGroup, enabled, visible are optional. Empty for none.

Setting the text replaces the whole set, so a shell can keep one text per page. A text with an error - invalid JSON, a name the bar does not know, an entry that breaks a rule of AddCommand - raises wkeInvalidValue (or wkeDuplicateKey) naming the entry (“Befehl 3: …”), and the commands stay as they were.

Read/write.

Me!barShell.Object.Commands = "[{""key"":""neu"",""caption"":""&Neu"",""glyph"":""E710"",""shortcut"":""^N""}," & _
    "{""key"":""refresh"",""caption"":""&Aktualisieren"",""glyph"":""E72C"",""placement"":""right""}]"

Declared by WklActionBar.

Sub AddCommand(ByVal Key As String, ByVal Caption As String, Optional ByVal Glyph As String = "", Optional ByVal Placement As WklCommandPlacement = wcpStandard, Optional ByVal Shortcut As String = "", Optional ByVal Parent As String = "", Optional ByVal Tooltip As String = "", Optional ByVal BeginGroup As Boolean = False)

Adds a command.

None

None

Declared by WklActionBar.

Sub RemoveCommand(ByVal Key As String)

Removes a command together with its children.

None

None

Declared by WklActionBar.

Sub ClearCommands()

Removes all commands.

None

None

None

Declared by WklActionBar.

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

Gets or sets whether a command can be run.

Property value: Boolean – True (default) or False. A disabled command is drawn gray; its click, access key and shortcut do nothing.

Set it from the state of the record, for example .CommandEnabled("sperren") = Me!lstPersons.Object.CanDelete. The children of a disabled command cannot run either.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets whether a command is shown.

Property value: Boolean – True (default) or False. A hidden command takes no place and its shortcut is not watched.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the caption of a command.

Property value: String – The text; an & marks the access key. An empty text raises wkeInvalidValue.

Read/write.

None

Declared by WklActionBar.

Property Get CommandCount() As Long

Gets the number of commands, children included.

None

Property value: Long – 0 without commands.

Read-only.

None

Declared by WklActionBar.

Property Get CommandKey(ByVal Index As Long) As String

Gets the key of the command at a position.

Property value: String – The key.

Read-only.

None

Declared by WklActionBar.

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

Gets or sets the caption of the More button.

None

Property value: String – The text; an & marks the access key. Default: More in the language of the components (&More, &Weitere, &Več, &Više, &Altro). An empty text raises wkeInvalidValue.

A bar that holds the default of any of these languages, for example &Weitere saved in a German session, counts as holding the default: it shows More in the language the components use at run time. A caption key such as @orders.more shows the application text of that key in the language of the session (see WklTexts); any other text is shown as it is.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the glyph of the More button.

None

Property value: String – A code of Segoe Fluent Icons, default E712; empty for none. An invalid code raises wkeInvalidValue.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the text of the status pill at the top right of the band.

None

Property value: String – The text, for example “Verbunden” or “aktualisiert 12:51”; empty (default) for none.

A change in form view is announced to screen readers.

Read/write.

None

Declared by WklActionBar.

Property Get StatusKind() As WklStatusKind
Property Let StatusKind(RHS As WklStatusKind)

Gets or sets the kind of the status, which sets the colors of the pill.

None

Property value: `WklStatusKind` – A WklStatusKind; wskNeutral by default. Other values raise wkeInvalidValue.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets a count shown beside the status pill.

None

Property value: Long – 0 (default) for none; above 99 the badge shows 99+. A negative value raises wkeInvalidValue.

Read/write.

None

Declared by WklActionBar.

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

Gets or sets the tooltip of a command.

Property value: String – The text; empty shows the caption and the shortcut (“New (Ctrl+N)”). Screen readers hear it as help text.

Read/write.

None

Declared by WklActionBar.

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 band and the command row while BackColor and ForeColor keep their defaults (a band color you set, such as the navy of a shell, wins), the lines, the status pill background, the command buttons as WklButton draws them and the menus; 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 WklActionBar.

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

Gets or sets the picture at the left of the band, for example the logo of the application.

None

Property value: String – A file (absolute, or relative to the folder of the database), the name of a shared image of the database, SVG text starting with <, or a data URI - the sources of WklImage.Source; empty (default) for no logo.

The logo is drawn at the height of the band less 8 pixels at the top and bottom, in its own proportions; title and subtitle move to the right of it and keep their height. A URL raises wkeInvalidValue at the assignment. A source that cannot be read (a missing file, an unknown image name) raises no error: the band is drawn without a logo. Outside Access (UserForms) a relative path is relative to the current folder of the process, and shared images are not available. The value is saved with the form.

Read/write.

Me!barShell.Object.Logo = "Firmenlogo"   ' a shared image of the database

Declared by WklActionBar.

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

Gets or sets the color of the subtitle.

None

Property value: Long – A color number as RGB() returns it (a system color such as &H80000008 is accepted too); -1 (default) for the color of the title (ForeColor). The type is Long, not OLE_COLOR, so that -1 can be assigned; the property sheet therefore offers no color builder for it, the designer does.

Available from release 1.59. With -1 the subtitle is drawn in the color of the title, as before 1.59; forms saved with an older release open with -1. Any other value is drawn as given, like ForeColor: choose a color with a contrast of at least 4.5:1 to the band (BackColor). In Windows high contrast, title and subtitle take the system's text color. The value is saved with the form. In the designer the card “Subtitle color” offers it, with the switch “Same as the title” for -1.

Read/write.

With Me!barShell.Object
    .ForeColor = vbWhite
    .SubtitleForeColor = RGB(212, 175, 55)   ' gold under a white title on a navy band
End With

Declared by WklActionBar.

Event CommandClick(ByVal Key As String)

Occurs when the user chooses a command: a click on its button, an entry of a menu, the main part of a split button, its access key, its shortcut, or Invoke by a screen reader.

A disabled or hidden command raises nothing. A command that only opens a menu (a menu command with children) raises nothing either; its children do.

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

None

Declared by WklActionBar.