WklRibbon

Dim myWklRibbon As New WklRibbon

Makes the ribbons, the File view and the context menus of a database from one model of commands, and runs them: the conditions under which an element shows, values set by code, and the actions.

None

WklRibbon is an object, not a control. It has three uses:

• Designer and store. ShowDesigner opens the ribbon designer for the current database (also from the add-in menu Database Tools › Add-Ins › WKL Ribbon Designer). Save writes a model into the current database: the model into the table USysWklRibbon, each ribbon's RibbonXML into USysRibbons, the application ribbon into the database property CustomRibbonID, and the callbacks into the module basWklRibbon. Access shows a changed ribbon after the database was closed and opened again, as for ribbons written by hand.
• Generator. Check, Canonical, RibbonNames, RibbonXml and ModuleText work on a model text without Access; the build tool uses them (ribbonModel in access-app.json).
• Runtime. The generated module basWklRibbon passes every ribbon callback to a WklRibbon object through hidden members, which are not for application code: it answers labels, visibility and readiness, and runs the action of a command. Code gets the same object with WklRibbonObject(), a function of the module, to set values (Visible, Enabled, Label, Pressed), ask again (Invalidate) or listen to Action.

The state of the ribbons belongs to the database in the Access session, not to one object: a new object finds it again, also after a project reset (an unhandled error, End). Conditions: a command, tab, group or tab of the File view shows when the connection profile (the one set with Profile, else the one most linked tables use, as WklLinkManager.DetectEnvironment), the kind of database (ACCDB, ACCDE, runtime) and a function of the application (returning True) all agree. Hiding is a convenience, not a protection: whoever can open the database can run the action anyway, so the check belongs into the data source.

Callbacks never fail towards Access: when the runtime cannot answer, an element stays hidden, and a failing action raises ActionError instead of a message box. A function named as action should handle its own errors: an unhandled error in it shows the VBA error dialog, as for every function a ribbon calls.

Created with New WklRibbon or CreateObject.

' In the module of the start form: the ribbon follows the signed-in user.
Private WithEvents mRibbon As WklRibbon
 
Private Sub Form_Load()
    Set mRibbon = WklRibbonObject()
    mRibbon.Enabled("cmdExport") = Nz(TempVars("darfExportieren"), False)
End Sub
 
Private Sub mRibbon_Action(ByVal Command As String, ByVal Pressed As Boolean, Cancel As Integer)
    If Command = "cmdDelete" And Me.Dirty Then Cancel = True
End Sub

None

Function Check(ByVal Model As String) As String

Checks a model and returns its problems.

Return value: String – One problem per line, in the language of the components; empty when the model can be saved. A text that is no model gives its error as the only line; Check never raises an error.

None

None

Declared by WklRibbon.

Function Canonical(ByVal Model As String) As String

Returns a model in its fixed text form.

Return value: String – The text the database keeps and the build tool exports: keys in fixed order, defaults left out, two spaces indentation, LF line ends.

A text that is no model raises wkeInvalidValue. The canonical text of a canonical text is the same, byte for byte.

None

Declared by WklRibbon.

Function RibbonNames(ByVal Model As String) As String

Returns the names of the ribbons of a model.

Return value: String – The names separated by semicolons, in the order of the model.

None

None

Declared by WklRibbon.

Function RibbonXml(ByVal Model As String, ByVal Name As String) As String

Returns the RibbonXML of one ribbon of a model.

Return value: String – The XML for the column RibbonXML of USysRibbons.

A model with problems raises wkeInvalidValue with the first problem; an unknown name raises wkeKeyNotFound.

None

Declared by WklRibbon.

Function ModuleText(ByVal Model As String) As String

Returns the text of the callback module basWklRibbon for a model.

Return value: String – The module with its Attribute VB_Name line, as LoadFromText reads it.

None

None

Declared by WklRibbon.

Function Load() As String

Returns the model of the current database.

None

Return value: String – The model text from USysWklRibbon; empty when the database has none.

Needs an Access database open in this process; elsewhere it raises wkeNotConfigured.

None

Declared by WklRibbon.

Sub Save(ByVal Model As String, Optional ByVal WriteModule As Boolean = True)

Saves a model in the current database.

The model, the ribbons and CustomRibbonID are written at once; the module follows once the VBA procedure that called Save has ended, because Access replaces no module while VBA runs. Only the rows of USysRibbons that belong to the model (now or before) are replaced; other ribbons stay. A model with problems raises wkeInvalidValue; a refused write raises wkeSourceError.

None

Declared by WklRibbon.

Function ShowDesigner() As Boolean

Opens the ribbon designer for the current database.

None

Return value: Boolean – True when it was closed with OK (the model is saved then).

After OK the context menu assignments of the page Assignments are written into the forms and reports (see ApplyAssignments). Forms and reports that are open are left alone; a message names them.

None

Declared by WklRibbon.

Sub Invalidate()

Asks every loaded ribbon again for labels, visibility and readiness, and makes the context menus again.

None

Needed after a change the runtime cannot see, for example when the function named in a condition would now answer differently. Values set through Visible, Enabled, Label and Pressed take effect without it.

None

Declared by WklRibbon.

Sub InvalidateCommand(ByVal Command As String)

Asks the elements of one command again.

An unknown command raises wkeKeyNotFound.

None

Declared by WklRibbon.

Property Get Visible(ByVal Command As String) As Boolean
Property Let Visible(ByVal Command As String, RHS As Boolean)

Gets or sets whether a command is visible.

Property value: Boolean – Setting False hides the command wherever it stands; True shows it where its condition holds. Gets the effective visibility.

The value applies in addition to the condition: it can hide a command, not show one its condition hides. ResetCommand removes it.

Read/write.

None

Declared by WklRibbon.

Property Get Enabled(ByVal Command As String) As Boolean
Property Let Enabled(ByVal Command As String, RHS As Boolean)

Gets or sets whether a command can be run (default True).

Property value: Boolean – False grays the command out in the ribbon, the File view and the context menus.

Read/write.

None

Declared by WklRibbon.

Property Get Label(ByVal Command As String) As String
Property Let Label(ByVal Command As String, RHS As String)

Gets or sets the label of a command.

Property value: String – The text shown; set, it replaces the label of the model until ResetCommand.

Read/write.

None

Declared by WklRibbon.

Property Get Pressed(ByVal Command As String) As Boolean
Property Let Pressed(ByVal Command As String, RHS As Boolean)

Gets or sets the state of a toggle button.

Property value: Boolean – True when pressed.

Read/write.

None

Declared by WklRibbon.

Sub ResetCommand(ByVal Command As String)

Removes visibility, readiness and label set by code for a command.

None

None

Declared by WklRibbon.

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

Gets or sets the connection profile the conditions use.

None

Property value: String – For example DEV, TEST or PROD; empty for the profile most linked tables use (as WklLinkManager.DetectEnvironment, empty when the database has no link configuration).

Setting it asks the ribbons again.

Read/write.

None

Declared by WklRibbon.

Sub ActivateTab(ByVal TabId As String)

Shows a tab of a loaded ribbon.

An unknown tab raises wkeKeyNotFound; a tab of a ribbon Access has not loaded raises wkeNotAvailable.

None

Declared by WklRibbon.

Sub Execute(ByVal Command As String)

Runs a command as if the user had chosen it: Action, then the action of the model.

None

None

Declared by WklRibbon.

Function EnsureMenus() As Long

Makes the context menus of the saved model as temporary command bars of this Access session, so a form, report or control naming one in Shortcut Menu Bar (ShortcutMenuBar) shows it.

None

Return value: Long – The number of context menus made.

Access forgets temporary command bars when it closes, so an application without a ribbon of the model calls EnsureMenus once when it starts; when a ribbon of the model loads, its onLoad makes the menus itself. It works in ACCDB, ACCDE and runtime. Calling it again makes the menus again from the saved model.

None

Declared by WklRibbon.

Function ApplyAssignments() As String

Writes the context menu assignments of the saved model into the forms and reports of the current database: Shortcut Menu Bar of the form or report itself, of a named control, or of every control of a kind.

None

Return value: String – The changes, one per line (frmCustomers.txtName: (none) -> ctxCustomer); empty when nothing had to change.

• Which assignment wins. An assignment naming a control wins over one for its kind of control. A menu of the model that is no longer assigned is removed from where the model had put it; a context menu the model does not know (made by the application itself) is never removed, only replaced where the model assigns another.
• Design view. Forms and reports are opened hidden in design view and saved only when something changed. One that is open is left alone and named in the result (frmCustomers: open, skipped).
• ACCDB only. An ACCDE has no design view: ApplyAssignments raises wkeNotAvailable there. Assign before making the ACCDE; the build tool does it after loading forms and reports.

None

Declared by WklRibbon.

Function ShowAssignments() As Boolean

Opens the ribbon designer on the page Assignments: which form, report, control or kind of control shows which context menu of the model. The add-in menu entry Database Tools › Add-Ins › WKL Shortcut Menu Designer calls it.

None

Return value: Boolean – True when it was closed with OK (the model is saved and the assignments written then).

Behaves like ShowDesigner; only the first page differs.

None

Declared by WklRibbon.

Event Action(ByVal Command As String, ByVal Pressed As Boolean, ByRef Cancel As Integer)

Occurs when the user chooses a command: a button, a menu entry, a task of the File view, a context menu entry, or Execute.

Events reach VBA only through a WithEvents variable on module level of a form, report or class: Set mRibbon = WklRibbonObject().

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

None

Declared by WklRibbon.

Event ActionError(ByVal Command As String, ByVal Description As String)

Occurs when the action of a command failed: the form or report does not exist, or the function is missing or raised an error Access reports to the caller. No message box is shown.

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

None

Declared by WklRibbon.