VBA API Cookbook & Recipes for XLS Padlock

This topic provides a comprehensive collection of VBA code snippets (“recipes”) for advanced control over your protected application at runtime. Using the XLS Padlock VBA API, you can retrieve system information, manage saving and loading, customize the user interface, and interact with online features.

The two main API objects are:
– Application.COMAddIns("GXLSForm.GXLSFormula").Object for most runtime information.
– Application.COMAddIns("GXLS.GXLSPLock").Object for saving-related operations.

Each recipe below provides a ready-to-use VBA function or subroutine.

Application & System Information #

These recipes help you retrieve information about the application’s environment and status.

Check if the Workbook is Protected #

Use this to confirm that your code is running inside a protected application created by XLS Padlock.

Public Function XLSPadlockAvailable() As Boolean
    Dim XLSPadlock As Object
    On Error Resume Next
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    If Not XLSPadlock Is Nothing Then
        XLSPadlockAvailable = XLSPadlock.IsProtected()
    Else
        XLSPadlockAvailable = False
    End If
End Function

Get the Application’s EXE Filename #

Retrieves the filename of the running .exe file.

Public Function GetEXEFilename() As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    GetEXEFilename = XLSPadlock.PLEvalVar("EXEFilename")
    Exit Function
Err:
    GetEXEFilename = ""
End Function

Get EXE File and Product Version #

Retrieves the version strings you defined in the “EXE Version Info” section of XLS Padlock.

Public Function ReadVersionInfo(infoType As String) As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    ReadVersionInfo = XLSPadlock.PLEvalVar(infoType)
    Exit Function
Err:
    ReadVersionInfo = ""
End Function

Usage:
– ReadVersionInfo("ProductVersion") returns the Product Version.
– ReadVersionInfo("FileVersion") returns the File Version.

Get the User’s System ID #

Retrieves the unique System ID required for hardware-locked activation keys. This is the ID your customers will send you.

Public Function ReadSystemID() As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    ReadSystemID = XLSPadlock.PLEvalVar("SystemID")
    Exit Function
Err:
    ReadSystemID = ""
End Function

Get Command-Line Parameters #

Retrieves command-line parameters passed to your application’s .exe file.

Public Function ReadParamStr(index As Integer) As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    ReadParamStr = XLSPadlock.PLEvalVar("ParamStr" & index)
    Exit Function
Err:
    ReadParamStr = ""
End Function

Usage:
ReadParamStr(1) returns the first parameter, ReadParamStr(2) the second, and so on.

Saving & Loading Workbooks #

Manage secure save files (.xlsc or .xlsce) programmatically.

Get Current Save File Path #

Retrieves the full path to the secure save file that is currently loaded.

Public Function GetSecureWorkbookFilename() As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLS.GXLSPLock").Object
    GetSecureWorkbookFilename = XLSPadlock.GetSaveFilename()
    Exit Function
Err:
    GetSecureWorkbookFilename = ""
End Function

Get Local Save Folder Path #

Retrieves the path to the local folder where XLS Padlock stores your application’s settings and secure save files.

Public Function GetStoragePath() As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    GetStoragePath = XLSPadlock.PLEvalVar("SPath")
    Exit Function
Err:
    GetStoragePath = ""
End Function

Execute VBA Code After Saving #

XLS Padlock can automatically call the XLSPadlock_OnAfterSave subroutine after a user saves their work. This is useful for logging, showing a confirmation message, or other post-save actions.

Sub XLSPadlock_OnAfterSave(SaveFilename As String)
    MsgBox "The workbook has been successfully saved as: " & SaveFilename
End Sub

Open an Existing Save File with VBA #

Programmatically open a secure save file. Note that this will load the file in a new instance of Excel.

Public Sub LoadXLSPadlockSaveFile(FilePath As String)
    Dim XLSPadlock As Object
    On Error Resume Next
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    If Not XLSPadlock Is Nothing Then
        XLSPadlock.PLOpenSaveFile FilePath
    End If
End Sub

' Example of a caller function that shows a file browser:
Sub Load_Old_Save()
    Dim strFileToOpen As String
    strFileToOpen = Application.GetOpenFilename( _
        Title:="Please choose a save file to open", _
        FileFilter:="Save Files (*.xlsc),*.xlsc")

    If strFileToOpen <> "False" Then
        LoadXLSPadlockSaveFile strFileToOpen
    End If
End Sub

Suggest a Filename for the Save Dialog #

Set the default filename that appears in the “Save As” dialog box.

Public Sub SetSecureWorkbookFilename(Filename As String)
    Dim XLSPadlock As Object
    On Error Resume Next
    Set XLSPadlock = Application.COMAddIns("GXLS.GXLSPLock").Object
    If Not XLSPadlock Is Nothing Then
        XLSPadlock.SetDefaultSaveFilename Filename
    End If
End Sub

' Example: Set the default name to "my save.xlsc"
' Call SetSecureWorkbookFilename("D:\My Documents\my save.xlsc")

Save a Secure Copy without Prompt #

Save a secure copy of the workbook directly to a specified file path without showing the “Save As” dialog.

Public Function SaveSecureWorkbookToFile(Filename As String) As Boolean
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLS.GXLSPLock").Object
    SaveSecureWorkbookToFile = XLSPadlock.SaveWorkbook(Filename)
    Exit Function
Err:
    SaveSecureWorkbookToFile = False
End Function

' Example: Save the workbook directly
' If SaveSecureWorkbookToFile("D:\My Documents\my save.xlsc") Then
'   MsgBox "Workbook saved successfully."
' End If

Migrate User Data from a Previous Version #

If you release a new version of your workbook, you might need to import data from a save file created with a previous version.

➡ Learn how to migrate user data with VBA

User Interface #

Customize UI elements like dialog boxes.

Programmatically Hide Wait/Loading Dialogs #

You can hide the “Loading workbook, please wait…” dialog box with a VBA call instead of waiting for it to auto-close.

Public Sub HideLoadingDialog()
    Dim XLSPadlock As Object
    On Error Resume Next
    Set XLSPadlock = Application.COMAddIns("GXLS.GXLSPLock").Object
    If Not XLSPadlock Is Nothing Then
        ' A call with Option "3" and Value "0" hides the dialog.
        XLSPadlock.SetOption Option:="3", Value:="0"
    End If
End Sub

Online Activation & Validation #

Interact with XLS Padlock’s online features.

Check for an Internet Connection #

Tests whether an active internet connection is available on the user’s computer.

Public Function IsInternetAvailable() As Boolean
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    IsInternetAvailable = (XLSPadlock.PLEvalVar("InternetConnected") = "1")
    Exit Function
Err:
    IsInternetAvailable = False
End Function

Get the Online Activation Token #

Retrieves a hash of the activation token returned by the web server after a successful online activation.

Public Function GetValidationToken() As String
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    GetValidationToken = XLSPadlock.PLEvalVar("ValidationToken")
    Exit Function
Err:
    GetValidationToken = ""
End Function

Check if Online Validation Succeeded #

Gets the result of the last online validation attempt.

Public Function IsValidationOK() As Boolean
    Dim XLSPadlock As Object
    On Error GoTo Err
    Set XLSPadlock = Application.COMAddIns("GXLSForm.GXLSFormula").Object
    IsValidationOK = (XLSPadlock.PLEvalVar("ValidationSuccess") = "1")
    Exit Function
Err:
    IsValidationOK = False
End Function