WklApplication

Dim myWklApplication As New WklApplication

Keeps the settings of an application in its database - title, icon, start form, ribbon and the user interface of each mode - and writes them as Access's startup properties for the mode the database runs in.

None

WklApplication is an object, not a control (overview, tutorial). The model is a JSON text (version, title, icon, iconForFormsAndReports, startForm, ribbon, language, modes, profiles, adjustments; language is a language code in lower case and fixes the language of the application texts for the database, and of the WKL components when it is en, de, sl, hr or it, see Choose the language of the components); Save stores it in the table USysWklApp of the current database.

• Modes. The mode is measured, never configured (Mode): development is an ACCDB, administration an ACCDE in full Access, production an ACCDE in the runtime. Each mode has its own user interface - navigation pane, full menus, shortcut menus, special keys (F11, Ctrl+G), the bypass key (Shift at opening), status bar.
• When settings act. The title and the icon act at once, every other startup property only when the database is opened the next time. All of them stay writable in an ACCDE and in the runtime. Apply therefore names for each change when it acts.
• At start. An application calls EnsureApplication when it starts (for example in the start form's Form_Load). A copy built for one mode and run in another then corrects itself from the next opening on, and findings - a profile used outside its modes, a missing start form or icon, a damaged settings file - come back as text. It never stops the start.
• Not a protection. The locks prevent mistakes; they do not protect the database against a deliberate change: another DAO session can change or delete AllowBypassKey despite the DDL flag.
• Adjustments in operation. The model can release connections (relinking through WklLinkManager) and options to the operator. ShowSettings edits them, also in an ACCDE and the runtime; they are stored outside the database (%LOCALAPPDATA%\WKL\<database>\settings.json over %ProgramData%\WKL\<database>\settings.json), so a new version of the application keeps them. OptionValue reads an option.

Created with New WklApplication or CreateObject.

' In the start form: correct the startup properties for this mode and report findings.
Private Sub Form_Load()
    Dim findings As String
    findings = CreateObject("WklForms.Application").EnsureApplication()
    If Len(findings) > 0 Then Debug.Print findings
End Sub

None

Function Check(ByVal Model As String) As String

Checks a model without storing it.

Return value: String – The problems, one per line; empty when the model can be stored.

None

None

Declared by WklApplication.

Function Warnings(ByVal Model As String) As String

Names settings of a model that are allowed but risky, such as a production mode that leaves the bypass key on.

Return value: String – The warnings, one per line; empty when there are none. A text that is no model returns its reading error.

None

None

Declared by WklApplication.

Function Canonical(ByVal Model As String) As String

Returns a model in its fixed text form: keys in a fixed order, defaults left out. The same model always gives the same bytes, so the text can be kept in source control.

Return value: String – The canonical text.

A text that is no valid model raises wkeInvalidValue.

None

Declared by WklApplication.

Function Load() As String

Returns the model stored in the current database.

None

Return value: String – The model text; empty when none is stored.

None

None

Declared by WklApplication.

Function Save(ByVal Model As String, Optional ByVal Apply As Boolean = True) As String

Stores a model in the current database (table USysWklApp) and applies it.

Return value: String – What Apply returns; empty when not applied or nothing changed.

A model with problems raises wkeInvalidValue with the problems; a write Access refuses raises wkeSourceError.

None

Declared by WklApplication.

Function Apply() As String

Writes the startup properties of the stored model for the mode the database runs in.

None

Return value: String – One line per changed property with the moment it acts (“at once” or “at the next opening”); empty when every property was already set.

Without a stored model raises wkeNotConfigured; a stored model with problems raises wkeInvalidValue; a write Access refuses raises wkeSourceError. When the title or the icon changed, the title bar is refreshed at once.

None

Declared by WklApplication.

Function EnsureApplication() As String

Applies the stored model and returns the findings; call it when the application starts.

None

Return value: String – The findings, one per line: a profile used outside the modes its rule names, a start form or icon the database lacks, a settings file that cannot be read, a write Access refused. Empty when there are none, and always empty without a model.

Never raises an error and never stops the start: a refused write is a finding as well.

None

Declared by WklApplication.

Property Get Mode() As WklAppMode

Returns the mode of the current database, measured from the file (ACCDB or ACCDE) and from Access (full or runtime).

None

Property value: `WklAppMode` – wamDevelopment, wamAdministration or wamProduction.

Read-only.

None

Declared by WklApplication.

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

Gets or sets the connection profile the profile rules use.

None

Property value: String – A profile name such as DEV, TEST or PROD; an empty text returns to the detected profile.

Without a value set, the profile is the one most linked tables use (as WklLinkManager.DetectEnvironment). The value is shared with WklRibbon and WklNavPane and lasts for the Access session.

Read/write.

None

Declared by WklApplication.

Function OptionValue(ByVal Key As String) As String

Returns the value of an option of the application.

Return value: String – The value adjusted in operation (the user's settings file over the machine's), else the option's default in the model.

An adjusted value that does not fit the kind of the option counts as not adjusted. Without a stored model raises wkeNotConfigured; a key the model does not declare raises wkeKeyNotFound. Option is a VBA keyword, hence the name of the method.

None

Declared by WklApplication.

Function ShowSettings() As Boolean

Opens the settings for operation: server and database of the connections of the current profile, and the options the model releases.

None

Return value: Boolean – True when the dialog was closed with OK.

Works in an ACCDB, an ACCDE and the runtime. OK writes only what differs from the stored settings into the user's settings file and relinks the tables (WklLinkManager.EnsureLinks). Without a stored model raises wkeNotConfigured; when the model releases nothing, or its condition does not hold in this session, raises wkeNotAvailable.

None

Declared by WklApplication.

Function ShowDesigner() As Boolean

Opens the designer of the application for the current database (also from the add-in menu Database Tools › Add-Ins › WKL Application Designer).

None

Return value: Boolean – True when the designer was closed with OK.

Pages: General (title, icon file, start form from the database's forms, ribbon from USysRibbons, with a preview of the title bar), Modes (the startup options of development, administration and production as a table, with the defaults), Profiles (the modes each connection profile may run in), Adjustable in operation (relinking, options, who may open ShowSettings) and Check (problems and warnings). OK checks the model with the rules of Check, stores a newly chosen icon file, saves the model and applies it as Save does; title and icon act at once, the other startup options at the next opening. A broken rule keeps the designer open on the page Check and saves nothing; warnings do not block. Requires a database open in Access (wkeNotConfigured otherwise).

None

Declared by WklApplication.

Sub SaveIcon(ByVal Path As String)

Stores an icon file in the current database (table USysWklApp) as the application's icon.

Access shows only .ico and .bmp files as an application icon; another file, a missing file or one larger than 1 MB raises wkeInvalidValue. The icon travels with the database, so a copy on another computer shows it too.

None

Declared by WklApplication.

Function StartupProperties(ByVal Model As String, ByVal Mode As WklAppMode) As String

Returns the startup properties a model wants for a mode, as text: what the build tool writes into the delivered copy of a database without opening it.

Return value: String – One line per property, separated by CR LF: name, YesNo or Text, the value (True/False for Yes/No), and 1 or 0 for the DDL flag, separated by tabs.

The icon is not part of the result: its path is a file of the computer that runs the application, which EnsureApplication writes at the first start. A model with problems or a mode outside WklAppMode raises wkeInvalidValue.

None

Declared by WklApplication.

Function CheckTrust(Optional ByVal Path As String = "") As WklTrustCode

Returns whether Access runs the code of an application file for the signed-in Windows user without asking, and if not, why.

Return value: `WklTrustCode` – A WklTrustCode; wtuOk when the code runs.

The check reads what Access reads: the trusted locations of the user and of group policies (with their subfolders, network paths, a policy that allows only its own locations or switches all of them off), the macro setting of the Trust Center, also when a policy sets it, the mark of the web of the file (a file downloaded from the internet) and a policy that disables ActiveX controls. It changes nothing.

The result is what the settings give a user who does not click Enable content: the code of the current database may run now because someone enabled it, while the next start or another user gets the result of CheckTrust. A digital signature of the VBA project is not read: with Disable all macros except digitally signed macros a signed file is reported as wtuSignatureMissing. The codes of group policies (11, 12, 13, 20, 40) follow where the Office administrative templates place the values.

A path needs no Access, so a setup or a support tool can call the method before the first start (the package contains tools\deploy\Test-AccessTrust.ps1, which does exactly that). Without a path the method needs a database open in Access (wkeNotConfigured otherwise).

Dim app As New WklApplication
If app.CheckTrust() <> wtuOk Then
    MsgBox app.TrustReport(), vbExclamation
End If

Declared by WklApplication.

Function TrustReport(Optional ByVal Path As String = "") As String

Returns the result of CheckTrust as text in the language of the WKL components: the cause, a line break (CR LF), and what to do.

Return value: String – Two sentences. They name the folder of the file and, where one is involved, the trusted location by its name.

None

None

Declared by WklApplication.

Property Get Version() As String

Returns the release of the registered WKL components, for example 1.55.0.

None

Property value: String – The release as x.y.z, the same as in the CHANGELOG and in the file properties of the DLLs.

COM creates the object from the DLL registered for the user in the bitness of the caller, so the value names the release that answers there; an Access already running keeps the release it loaded until it ends. Releases before 1.55 have no Version and carry the file version 0.1.0; their release shows only in the folder name of the release package.

Read-only.

None

Declared by WklApplication.

Property Get Build() As String

Returns the release and the commit the registered WKL components were built from, for example 1.55.0+3f2a9c1e....

None

Property value: String – The release as in Version, a plus sign and the full commit id of the source; the release alone for a build made outside the repository.

Version is the value to compare; Build names the exact source, so a measurement or an error report can be traced back to it later. The commit is the one the components were compiled from, not necessarily the commit the release tag points to: a release commit that changes only documentation follows it (in 1.56.1 the build names b6331ac, the tag v1.56.1 points to 026ef59).

Read-only.

None

Declared by WklApplication.