Levure API
- levureAppGetENV
- levureAppHasProperty
- levureApplicationDataFolder
- levureApplicationState
- levureAppPrintConfig
- levureBuildProfile
- levureBuildStandalonesForTesting
- levureExternalsLoadedInMemory
- levureFinishLoadingApplication
- levureFrameworkFilename
- levureFrameworkFolder
- levureGetUIStacks
- levureInitializeAndRunApplication
- levureInitializeFramework
- levureIsHelperLoaded
- levureLoadAppConfig
- levureLoadExternalEditorServer
- levurePackageApplication
- levureRelativeAppFolderPath
- levureReloadRegisteredKey
- levureRunApplication
- levureSetApplicationFont
- levureSetApplicationFontSize
- levureShutdownApplication
- levureStandaloneFilename
- levureStandaloneFolder
- levureStandaloneName
- levureStandaloneStackName
- levureTestApplicationInSimulator
- levureVersion
Type: function
Syntax: __useLevureFileWithThisEngine(<pVersionRange>)
Summary: Checks that all dependencies are present and performs a simple check for circular dependencies.
Returns: nothing
Description:
The check only looks for circular dependencies between A and B. It doesn't look for circular connections between A, B, and C where A depends on B and B depends on C but C depends on A.
Type: command
Syntax: errorDialog <pError>
Summary: Displays errors that occur in a standalone during initialization or cleanup.
Description:
If an error occurs in a standalone while the framework is loading or shutting down the application then the error will be displayed and the application will quit. The assumption is that something unexpected happened and you don't want your application lingering around in memory unable to quit.
Type: function
Syntax: levureAppFolder()
Summary: Returns path to the folder where the app.yml file is located.
Returns: Path to file
Examples:
put levureAppFolder() into tAppFolder
Type: function
Syntax: levureAppGet(<pIndexedArray>)
Summary: Gets an app property.
Returns: Mixed as it depends on property value
Parameters:
| Name | Description |
|---|---|
pProp |
The property to check. This can be a string or an indexed lookup array. If a string then nested keys can be separated by the > character. |
pCheckExistence |
Pass in true to throw an error if pProp does not exist in the internal sAppA array. This can be used to ensure that a valid setting is being added to app.yml. |
Description:
This handler targets the internal array that was created when the app.yml file was loaded.
Examples:
put levureAppGet("preferences filename>user>default")
# Use an indexed lookup array
put "preferences filename" into tIndexA[1]
put "user" into tIndexA[2]
put "default" into tIndexA[3]
put levureAppGet(tIndexA)
Type: function
Syntax: levureAppGetConfig()
Summary: Returns the internal array that was created when reading the app.yml file.
Returns: Array
Examples:
put levureAppGetConfig() into tAppA
put tAppA["name"]
Type: function
Syntax: levureAppGetENV()
Summary: Returns the environmental variables stored in the .env file.
Returns: String
Description:
During development you can place an .env file alongside the app.yml file. The format is
a key=value pair, one per line. This function will return an array of key/values.
Use the .env file to store values you don't want stored in a git repository. For example,
you should store the password used to password protect your application in the .env file.
As long as the .env file is not stored in your version control repository the password
will not be stored in the repository.
The Levure application packager will use this function to check for a password when packaging your application.
Examples:
# Assumes your .env file has a PASSWORD=VALUE line in it
put levureAppGetENV() into tEnvA
put tEnvA["PASSWORD"]
Type: function
Syntax: levureAppHasProperty(<pIndexedArray>)
Summary: Use to check if a property name is among the keys in the application configuration array.
Returns: True/False
Parameters:
| Name | Description |
|---|---|
pProp |
The property to check. This can be a string or an indexed lookup array. If a string then nested keys can be separated by the > character. |
Description:
This handler targets the internal array that was created when the app.yml file was loaded. If it is possible
that an application property doesn't exist then use this function before calling levureAppGet() or
levureAppSet. Both handlers will throw an error if the target property doesn't exist.
Examples:
put levureAppHasProperty("preferences filename>user>default")
# Use an indexed lookup array
put "preferences filename" into tIndexA[1]
put "user" into tIndexA[2]
put "default" into tIndexA[3]
put levureAppHasProperty(tIndexA)
Type: function
Syntax: levureApplicationDataFolder(<pUserOrShared>)
Summary: Returns the folder where application data is stored for the application.
Returns: Path to folder
Parameters:
| Name | Description |
|---|---|
pUserOrShared |
Pass in shared for the shared folder path. Pass in user for the user folder path. Default is user. |
Description:
This handler combines the standard folder where application data is stored
on the current system with the application data folder defined in the app.yml file.
Examples:
put levureApplicationDataFolder("user") into tUserDataFolder
Type: function
Syntax: levureApplicationState()
Summary: Returns the current state of the application.
Returns: "loading", "running", "shutting down"
Description:
Returns a value of loading, running, or shutting down. These values reflect the
internal state of the Levure application.
While Levure is loading application files at startup
the state is loading.
When Levure has begun to shut down the application (e.g. the user quit the application) then
the state is shutting down.
In all other cases the state is running.
Examples:
# In app.livecodescript
on appleEvent pClass, pId, pSender
# don't process events if application isn't running
if levureApplicationState() is not "running" then pass appleEvent
...
end appleEvent
Type: function
Syntax: levureAppPrintConfig()
Summary: Returns a text representation of the internal array that was created when reading the app.yml file.
Returns: Array
Examples:
put levureAppPrintConfig()
Type: command
Syntax: levureAppSet <pIndexedArray>, <pValue>
Summary: Sets an app property for the life of the current session.
Returns: Empty
Parameters:
| Name | Description |
|---|---|
pProp |
The property to check. This can be a string or an indexed lookup array. If a string then nested keys can be separated by the > character. |
pValue |
The value to set the property to. |
pCheckExistence |
Pass in true to throw an error if pProp does not exist in the internal sAppA array. This can be used to ensure that a valid setting is being added to app.yml. |
Description:
This handler targets the internal array that was created when the app.yml file was loaded. The value will only be updated for the current session. The app.yml file is not updated.
Examples:
levureAppSet "multiple instances", true
put "preferences filename" into tIndexA[1]
put "user" into tIndexA[2]
put "default" into tIndexA[3]
levureAppSet tIndexA, "com.mycompanyname.myapp-shared"
Type: function
Syntax: levureAppStackFilename()
Summary: Returns the filename of the app stack file.
Returns: Path to file
Examples:
put levureAppStackFilename() into tAppStackFilename
Type: function
Syntax: levureAppStackName()
Summary: Returns the name of the app stack.
Returns: "app"
Description:
If you ever need to refer to the app stack by name you can call this function. It
saves you from hard coding app in your code.
Examples:
dispatch "MyCustomMessage" to stack levureAppStackName()
Type: command
Syntax: levureBuildExtensions <pOnlyBuildMissing>
Summary: Builds extensions configured in the app.yml file.
Returns: Error message
Parameters:
| Name | Description |
|---|---|
pOnlyBuildMissing |
Pass in true to only build extensions which don't already exist. |
Description:
If the app.yml file includes references to the source code files (*.lcb) for extensions then this command will compile the source code and update the .lcm file for the extension.
This command can be useful if you are running the application for the first time on a system that doesn't have compiled versions of the extensions.
Examples:
levureBuildExtensions
Type: function
Syntax: levureBuildFolder()
Summary: Returns the folder where the packager will place builds.
Returns: Path to folder
Examples:
put levureBuildFolder() into tBuildFolder
launch document tBuildFolder & "/build.log"
Type: function
Syntax: levureBuildProfile()
Summary: Returns the name of the build profile used to package the version of the application that is running.
Returns: Build profile name
Description:
When you package an application you package a specific build profile. This handler returns the name of the build profile that was used. When running in the IDE "development" is returned.
Examples:
put levureAppGet("version") into tVersionString
if the levureBuildProfile() is "beta" then
put " (BETA)" after tVersionString
end if
Type: command
Syntax: levureBuildStandalonesForTesting
Summary: (Desktop apps only) Builds a standalone that loads all of your development files when launched.
Returns: Error message
Description:
This handler will create standalone engines that can be used for testing on your target platforms.
A test folder will be created in the builds folder that is configured in your app.yml file.
The test folder will have executables for each desktop platform that you standalone.livecode stack
has been configured for in Standalone Settings.
None of the actual application stacks are bundled with the executables. When you launch any of the executables the executable will load the files from your development folder. This allows you to quickly test changes while running from a standalone.
The Levure packager will attempt to include the Remote Debugger (available in LiveCode 9 and above for Business licenses) if it is available.
Examples:
levureBuildStandalonesForTesting
Type: function
Syntax: levureExternalsLoadedInMemory()
Summary: Returns a list of externals that are loaded into memory and available in the message path.
Returns: CR delimited list of external package names
Examples:
set the wholematches to true
put levureExternalsLoadedInMemory() into tExternals
put "revXML" among the lines of tExternals
Type: command
Syntax: levureFinishLoadingApplication
Summary: Finishes loading the application during the startup sequence.
Returns: Empty
Description:
This handler is called "in time" during the startup sequence. You will not call this handler in your code.
Type: function
Syntax: levureFrameworkFilename()
Summary: Returns the path to the levureFramework.livecodescript file.
Returns: Path to stack file
Examples:
put the levureFrameworkFilename() into tFile
Type: function
Syntax: levureFrameworkFolder()
Summary: Returns the path to the folder where the levureFramework.livecodescript file is located.
Returns: Path to folder
Examples:
put the levureFrameworkFolder() into tFolder
Type: function
Syntax: levureGetUIStacks(<pFilterByKeys>)
Summary: Returns an array of all ui category assets.
Returns: Numerically indexed array. "name", "filename", and "key". "key" is the key the UI assets is listed under in app.yml.
Parameters:
| Name | Description |
|---|---|
pFilterByKeys |
If you only want UI components of a specific key(s) then pass in a list using this parameter. |
Examples:
put levureGetUIStacks() into tAllUIStacksA
put levureGetUIStacks("templates") into tTemplateUIStacksA
Type: command
Syntax: levureInitializeAndRunApplication
Summary: Initializes and runs the application.
Returns: Empty
Description:
This handler is used internally by the framework to initialize and run the application.
Typically you will never need to call this handler as it is called automatically at startup
when your application is running in a standalone or when you click the button in the
standalone.livecode stack.
Examples:
# In this example "MyStandalone" is the name of the standalone.livecode stack
start using stack "MyStandalone"
dispatch "levureInitializeAndRunApplication" to stack "MyStandalone"
Type: command
Syntax: levureInitializeFramework
Summary: Initializes the application without running it.
Returns: Error message
Description:
This handler is used internally by the framework to load the configuration information, load
all helpers, libraries, frontscripts, backscripts, behaviors, and ui assets. The PreloadApplication
message will be dispatched to the app stack.
Typically you will never need to call this handler. If you need to troubleshoot something
without runing your application you can call this handler after opening the standalone.livecode
file in the IDE. See example.
Examples:
# In this example "MyStandalone" is the name of the standalone.livecode stack
start using stack "MyStandalone"
dispatch "levureInitializeFramework" to stack "MyStandalone"
put levureAppGetConfig() into tA
put tA["version"]
Type: function
Syntax: levureIsHelperLoaded(<pHelperFolderName>)
Summary: Returns true if a helper is loaded.
Returns: True/False
Parameters:
| Name | Description |
|---|---|
pHelperFolderName |
The name of the helper folder. |
Examples:
put levureIsHelperLoaded("preferences") into tUsePrefs
Type: command
Syntax: levureLoadAppConfig <pBuildProfile>
Summary: Loads the app configuration data into memory and resolves all file references in it.
Returns: Error message
Parameters:
| Name | Description |
|---|---|
pBuildProfile |
This will be used to filter out assets using the "build profiles filter" property of each asset. |
Description:
When calling this command in the IDE the app.yml file will be read into memory.
When calling this command in a standalone the configuration information is stored as a
custom property of the app stack.
The app.yml file can contain relative folder and file references. All relative references will be resolved when calling this handler.
Examples:
levureLoadAppConfig
answer levureAppGet("name")
Type: command
Syntax: levureLoadExternalEditorServer <pPort>
Summary: Starts the server that listens for changes to application stack scripts.
[pPort]: Pass in a port if you plan on having two different Levure applications open in two different instances of the IDE. Otherwise the default port should suffice.
Returns: Empty
Description:
This handler allows you to work on a Levure application in the IDE and edit all of your script only stacks using
an external editor. The handler loads a stack into the IDE that starts a server on the localhost. The server listens
for requests notifying the server that a script only stack has been updated. The server will then update the script
of the matching stack in memory.
This handler is typically called in the InitializeApplication message that is sent to the app stack.
Currently Sublime Text is the only editor that will work using this setup. If you have the LiveCode language module installed for LiveCode then each time you save a LiveCode file in Sublime Text a request is sent to the server.
Examples:
command InitializeApplication
if the environment is "development" then
levureLoadExternalEditorServer
end if
end InitializeApplication
Type: command
Syntax: levurePackageApplication <pBuildProfile>
Summary: Packages up a levure application for distribution.
Returns: Error message
Parameters:
| Name | Description |
|---|---|
pBuildProfile |
The profile to build (e.g. release or beta). The profile must be defined in your app.yml file. |
Description:
When you are ready to package up your application for distribution to someone you call this handler.
The build profile that you pass in is the value that will be returned by levureBuildProfile() when
running the standalones.
When packaging the application stacks will be encrypted if A) the encrypted stacks property is true in the app.yml
file and B) a password can be located. The password can be stored in the app.yml file (not advisable if you store your
project in a version control system) or in the .env file that sits alongside the app.yml file (add a PASSWORD=VALUE line).
During the packaging process any properties defined in the build profiles > all profiles and build profiles > pBuildProfile
sections of your app.yml file will affect how the application is packaged. Below is a description of properties you can define.
The packager callback stackfiles property in app.yml points to a stack that will receive the
finalizePackagedAssets pBuildProfile, pBuildProfile, @xAppA, pAppFolder,
finalizeStandaloneForPlatform pBuildProfile, pPlatform, pAppA, pAppFolder, pFolderSavedIn,
finalizePackageForPlatform pBuildProfile, pPlatform, pAppA, pAppFolder, pOutputFolder,
and packagingComplete pBuildProfile, pOutputFolder, pAppA messages.
The certificates > macos > name property is the name of the certificate that the packager should use to sign your applications on macOS.
The packager will prefix the certificate with Developer ID Application: for apps being distributed outside of the Mac App Store
and with 3rd Party Mac Developer Application: for apps being distributed through the Mac App Store, and with Mac Developer: for apps built
for testing Mac App Store applications. The packager assumes you are
distributing through the Mac App Store if the name of pBuildProfile is "mac app store" and for development if pBuildProfile is
"mac app store development".
The copy files property determines which files will be copied into the output folder.
Examples:
levurePackageApplication "release"
Type: function
Syntax: levureRelativeAppFolderPath()
Summary: Returns the path to the folder where the app.yml file is located relative to the location where the standalone stack is located.
Returns: Relative path to folder
Description:
If standalone.livecode and app.yml are in the same directory then this function returns empty.
Examples:
put levureRelativeAppFolderPath() into tRelativePath
Type: command
Syntax: levureReloadRegisteredKey <pKey>
Summary: Sends message to helpers that need to process a registered key.
Returns: error
Description:
Dispatches the loadRegisteredKeyFile message to the stack specified by the helper
in the register component > callback stack setting. The message allows the helper
to process the file in some way. For example, if the helper works with yaml files
then the helper can read the yaml files when this message is sent.
The helper can add data to the internal array by marking the parameter as being passed by reference in the handler definition.
Type: command
Syntax: levureRunApplication
Summary: Begins running the application during the startup sequence.
Returns: Empty
Description:
This handler is called "in time" during the startup sequence. You will not call this handler in your code.
Type: command
Syntax: levureSetApplicationFont <pFont>
Summary: Sets the default font that all open stacks will inherit.
Returns: nothing
Parameters:
| Name | Description |
|---|---|
pFont |
The font to assign to the textFont property. |
Type: command
Syntax: levureSetApplicationFontSize <pSize>
Summary: Sets the default font size that all open stacks will inherit.
Returns: nothing
Parameters:
| Name | Description |
|---|---|
pSize |
The value to assign to the textSize of the stack. |
Type: command
Syntax: levureShutdownApplication
Summary: Cleans up and shuts down the application when running in a standalone.
Returns: empty
Description:
You should not need to call this handler in your own code. The framework calls this handler
when the shutdown message is received. An auto updater would call this function as well
when unloading the application prior to update.
When this handler is called it will dispatch PreShutdownApplication to the app stack.
Type: function
Syntax: levureStandaloneFilename()
Summary: Returns the path of the application standalone.
Returns: Path to file
Examples:
put levureStandaloneFilename() into tAppFilename
Type: function
Syntax: levureStandaloneFolder()
Summary: Returns the path to the folder the application standalone is in.
Returns: Path to folder
Description:
On macOS the path points to the folder where the application bundle is located, not the actual executable file inside of the application bundle.
If called in the IDE this returns the path where the standalone.livecode stack file is located.
Examples:
put levureStandaloneFolder() into tAppFolder
Type: function
Syntax: levureStandaloneName()
Summary: Returns the name used for the application executable on the current platform.
Returns: Name
Description:
The standalone name is the value assigned to the Name in the Standalone Builder with the
appropriate suffix added (e.g. .app for macOS, .exe for Windows, and nothing for Linux).
Examples:
put levureStandaloneName() into tAppExecutable
Type: function
Syntax: levureStandaloneStackName()
Summary: Returns the short name of the standalone.livecode stack.
Returns: Stack short name
Examples:
put levureStandaloneStackName() into tStackName
Type: command
Syntax: levureTestApplicationInSimulator <pSimulator>,<pBuildProfile>
Summary: Packages the application and launches it in a simulator.
Returns: nothing
Parameters:
| Name | Description |
|---|---|
pSimulator |
ios or android. |
pBuildProfile |
The profile to build (e.g. release or beta). The profile must be defined in your app.yml file. Default is release. |
Description:
See levurePackageApplication for details about packaging process. The only difference
is that this handler will build the application in a temporary folder
and will launch the simulator after packaging is complete.
Type: function
Syntax: levureVersion()
Summary: Returns the version of the Levure framework in use.
Returns: The version in format x.x.x.x
Type: command
Syntax: packagerDidFinishBuildingStandaloneForTesting
Summary: Message sent from the packager script.
Description:
Move along. Nothing to see here.
Type: command
Syntax: packagerDidFinishPackagingApplication <pStandaloneStackFilename>,<pBuildProfile>,<pSimulator>
Summary: Message sent from the packager script.
Description:
Move along. Nothing to see here.
Type: function
Syntax: yamlFileToArray(<pFilename>)
Summary: Converts a YAML file to an array.
Returns:
the result: Error message
it: Array
Parameters:
| Name | Description |
|---|---|
pFilename |
Path to YAML file. |
Description:
Converts a YAML file to an array. You must use the same spacing throughout the file for indentation.
Note that there are some limitations with regards to YAML that is supported:
- Comments are not supported.
-
- is not supported
Examples:
put yamlFileToArray(tFilename) into tYamlA
put the keys of tYamlA
Levure is an application development framework written for LiveCode.