Skip to content

Levure API

Trevor DeVore edited this page Feb 22, 2019 · 36 revisions

__useLevureFileWithThisEngine

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.


errorDialog

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.


levureAppFolder

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

levureAppGet

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.

If the property passed in does not exist then an error will be thrown.

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)

levureAppGetConfig

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"]

levureAppGetENV

Type: function

Syntax: levureAppGetENV()

Summary: Returns an environmental variable 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 a key value.

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("password") into tPassword

levureAppHasProperty

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)

levureApplicationDataFolder

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

levureApplicationState

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

levureAppPrintConfig

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()

levureAppSet

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"

levureAppStackFilename

Type: function

Syntax: levureAppStackFilename()

Summary: Returns the filename of the app stack file.

Returns: Path to file

Examples:

put levureAppStackFilename() into tAppStackFilename

levureAppStackName

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()

levureBuildExtensions

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

levureBuildFolder

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"

levureBuildProfile

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

levureBuildStandalonesForTesting

Type: command

Syntax: levureBuildStandalonesForTesting

Summary: 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

levureExternalsLoadedInMemory

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

levureFinishLoadingApplication

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.


levureFrameworkFilename

Type: function

Syntax: levureFrameworkFilename()

Summary: Returns the path to the levureFramework.livecodescript file.

Returns: Path to stack file

Examples:

put the levureFrameworkFilename() into tFile

levureFrameworkFolder

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

levureGetUIStacks

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

levureInitializeAndRunApplication

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"

levureInitializeFramework

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"]

levureIsHelperLoaded

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

levureLoadAppConfig

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")

levureLoadExternalEditorServer

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

levurePackageApplication

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 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"

levureRelativeAppFolderPath

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

levureReloadRegisteredKey

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.


levureRunApplication

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.


levureShutdownApplication

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.


levureStandaloneFilename

Type: function

Syntax: levureStandaloneFilename()

Summary: Returns the path of the application standalone.

Returns: Path to file

Examples:

put levureStandaloneFilename() into tAppFilename

levureStandaloneFolder

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

levureStandaloneStackName

Type: function

Syntax: levureStandaloneStackName()

Summary: Returns the short name of the standalone.livecode stack.

Returns: Stack short name

Examples:

put levureStandaloneStackName() into tStackName

levureTestApplicationInSimulator

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.


levureVersion

Type: function

Syntax: levureVersion()

Summary: Returns the version of the Levure framework in use.

Returns: The version in format x.x.x.x


packagerDidFinishBuildingStandaloneForTesting

Type: command

Syntax: packagerDidFinishBuildingStandaloneForTesting

Summary: Message sent from the packager script.

Description:

Move along. Nothing to see here.


packagerDidFinishPackagingApplication

Type: command

Syntax: packagerDidFinishPackagingApplication <pStandaloneStackFilename>,<pBuildProfile>,<pSimulator>

Summary: Message sent from the packager script.

Description:

Move along. Nothing to see here.


yamlFileToArray

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:

  1. Comments are not supported.
    • is not supported

Examples:

put yamlFileToArray(tFilename) into tYamlA
put the keys of tYamlA
Clone this wiki locally
You can’t perform that action at this time.