Scripts

• LXe_SCRIPT_UNKNOWN

• LXe_SCRIPT_ERROR

• LXe_SCRIPT_OPAQUE

• LXe_SCRIPT_READONLY

• LXe_SCRIPT_ALREADY_EXISTS

• LXe_SCRIPT_NOT_ENOUGH_ARGS

• LXe_SCRIPT_TOO_MANY_ARGS

• LXe_SCRIPT_RECOGNIZED_INVALID

• LXe_SCRIPT_LINEISCOMMENT

• LXe_SCRIPT_WARNING

---

LXsLOG_SCRIPTSYS

We also define a script subsystem that script clients can use for their messages

ILxScriptSysService

class ILxScriptSysService

The script system service provides a list of available script managers, rather than having clients browse the plug-in database themselves. Managers are sorted by their internal name (i.e., the name of the plug-in itself), which can also be obtained. Managers must be released when no longer needed. The objects returned by ByIndex(), NameByIndex() and Lookup() must be released by the caller.

Public Functions

LxResult ScriptQuery(LXtObjectID self, void **ppvObj)

LxResult Count(LXtObjectID self, unsigned int *count)

LxResult ByIndex(LXtObjectID self, unsigned int index, void **ppvObj)

LxResult NameByIndex(LXtObjectID self, unsigned int index, const char **name)

LxResult Lookup(LXtObjectID self, const char *name, void **ppvObj)

Managers can also be looked up by name.

LxResult UserName(LXtObjectID self, LXtObjectID manager, const char **name)

Some user interface information about a manager can be read with these functions. User strings are looked up in the message table matching the manager’s name with “{scriptservice} ” prefixed.

LxResult Desc(LXtObjectID self, LXtObjectID manager, const char **name)

LxResult UserValueCount(LXtObjectID self, int *count)

The list of user values can be walked directly, or a specific user value can be looked up by name. The object returned has an ILxUIserValueDef interface. This includes all config, temporary and momentary user values. These methods are implemented as of nexus 801. User values can only be created with user.defNew, edited with user.def, the value set with user.value. None of these functions or those commands are thread-safe, and care should be taken to not call these from a thread.

LxResult UserValueByIndex(LXtObjectID self, int index, void **ppvObj)

LxResult UserValueLookup(LXtObjectID self, const char *name, void **ppvObj)

LxResult ResolveAlias(LXtObjectID self, const char *alias, const char **path)

To simplify the use of scripts in kits, we support script aliases. This allows a script hash (aka the path to a script on disk) to be aliased to an arbitrary string. Script aliases are defined solely from within configs, usually by the script’s developer. The alias may include path aliases, and may included any ASCII characters, although it is important to note that it is not a translatable string. When used in kits, the simple form can be used when the script is in the kit’s directory: <hash type=”ScriptAlias” key=”aliasedScriptName”>myScript.pl

When defined outside of a kit, the full path to the script must be used. <hash type=”ScriptAlias” key=”aliasedScriptName”>pathAlias:dir/myScript.pl

<hash type=”ScriptAlias” key=”aliasedScriptName”>c:\dir\myScript.pl

Once defined, the script alias can be used in place of the script’s path at any time to lookup and/or execute the script, including in commands like script.run, script.implicit, and the @ syntax. This utility can be used by clients to resolve a script alias to its full path. The path returned will always be a valid string, returning a the resolved path if possible, and returning the alias otherwise. This allows you to just pass in any script path or a known alias and get back a usable path, even though the function will fail if the alias cannot be resolved. This returns LXe_NOTFOUND if the alias does not exist, in which case the alias passed in is returned. This returns LXe_FAILED if the alias exists, but could not be resolved into an absolute path. In this case, the aliased path will be returned instead of the alias name or the resolved path. Just to clarify:

• LXe_FAILED returns the alias: aliasedScriptName

• LXe_NOTFOUND returns the alias path: pathAlias:dir/myScript.pl

• LXE_OK returns the resolved absolute path: <path that ‘pathAlias:’ points to>/dir/myScript.pl

LxResult LookupScript(LXtObjectID self, const char *hash, int write, int tryAsUsername, void **service, void **script)

This provides a high-level way to look up a scriopt by path. It loops though all of the script servers and returns the ILxScriptManager that found the script, and an ILxScript representing the script itself. The write and tryAsUsername arguments work identically to those on the ILxScriptManager::Lookup() method. This also provides a caching mechanism based on the script’s path, making it efficient to look up a script without having to hit the disk each time for disk-based scripts.

bool UserValueByIndex(int index, CLxUser_UserValue &val)

User Class Only:

bool UserValueLookup(const char *name, CLxUser_UserValue &val)

ILxUserValue

class ILxUserValue

This interface provides read-only information about a user value. The type, type name and value are available from the ILxScriptSysService::UserValues(). If the user value has been deleted, all of these methods will fail.

Public Functions

LxResult Name(LXtObjectID self, const char **name)

These methods get the value’s name and username. If the username is not set, this just returns the name. The Name() method will always succeed as long as the underlying user value exists. This can be used as a way to test if the object is still valid, or if the user value itself has been deleted out from under the object.

LxResult UserName(LXtObjectID self, const char **username)

LxResult Type(LXtObjectID self, int *type)

These return the type (as an LXi_TYPE_ define) and type name of the user value.

LxResult TypeName(LXtObjectID self, const char **tname)

LxResult IsTransient(LXtObjectID self, int *isTransient)

For config user values, this returns LXe_TRUE if a user value is transient, and LXe_FAILS if not. Transient values have a default that is loaded from the config, but the new value is never written to the config it is only stored in memory.

LxResult GetInt(LXtObjectID self, int *val)

These return the value of the user value. GetString() will work on anything, and will return the “raw” string version of the value.

LxResult GetFlt(LXtObjectID self, double *val)

LxResult GetString(LXtObjectID self, char *buf, unsigned len)

LxResult Lifespan(LXtObjectID self, int *life)

LxResult FloatRange(LXtObjectID self, int *hasMin, double *min, int *hasMax, double *max)

Get the min/max values. There are separate functions for float and int types, as well as flags indiciating if min/max is set.

LxResult IntRange(LXtObjectID self, int *hasMin, int *min, int *hasMax, int *max)

LxResult List(LXtObjectID self, const char **list)

Get the list and their names as string, similar to the one passed to user.def. The ArgumentType used to get usernames from the config is also available. These methods fail with NOTAVAILABLE for non-integer types, and fail with NOTFOUND if they are not set.

LxResult ListNames(LXtObjectID self, const char **listNames)

LxResult ArgType(LXtObjectID self, const char **argType)

LxResult Action(LXtObjectID self, const char **action)

Get the action (command string) executed when the user value changes. Returns NOTFOUND if no action is set.

LxResult DeferAction(LXtObjectID self)

This returns LXe_TRUE if an action is to be deferred after refiring has completed, and LXe_FALSE if not. It returns NOTFOUND if no action is set.

LxResult DialogUserName(LXtObjectID self, const char **username)

Get the dialog username string for the user value. Returns NOTFOUND if none is set.

LxResult ValuePresetCookie(LXtObjectID self, const char **cookie)

Get the value preset cookie string for the user value. Returns NOTFOUND if no action is set.

LxResult EnableCommand(LXtObjectID self, const char **command)

Get the command whose enable state is also applied to this user value. Returns NOTFOUND if none is set.

LxResult Notifier(LXtObjectID self, const char **notifier)

Get the notifier that causes the user value’s control to be updated in the interface. Returns NOTFOUND if none is set.

LxResult DefaultValue(LXtObjectID self, void **ppvObj)

Get the default value as an ILxValue. This fails with NOTFOUND if none is set.

LxResult AsUI(LXtObjectID self)

Get if changing the user value via user.value be treated as an undoable UI command instead of an undoable model command. UI commands exist in the undo stack only until a model command is executed, while model commands persist in the stack. UI mode is useful when creating preferences, while model mode is useful when the user value is used to directly affect the scene itself, usually by performing an assocated action when the value changes. This returns LXe_TRUE for UI style behavior, and LXe_FALSE for model style behaviors.

LxResult InvertEnableCommandTest(LXtObjectID self)

Get if the enable command test is inverted or not. Normally, when the enable command is disabled, or it is enabled but queries to false, then the user value is also disabled. This simply flips the test.

LxResult UIMode(LXtObjectID self, int *uiMode)

std::string Name()

User Class Only:

std::string UserName()

std::string TypeName()

User Class Only:

std::string List()

User Class Only:

std::string ListNames()

std::string ArgType()

std::string Action()

User Class Only:

std::string DialogUserName()

User Class Only:

std::string ValuePresetCookie()

User Class Only:

std::string EnableCommand()

User Class Only:

std::string Notifier()

User Class Only:

---

LXiUSERVALUELIFE_CONFIG

This returns the lifespan of the user value.

• LXiUSERVALUELIFE_TEMPORARY

• LXiUSERVALUELIFE_MOMENTARY

• LXiUSERVALUELIFE_COUNT

---

LXiUSERVALUE_UIMODE_UNDO_MODEL

12.2 adds support for pure UI commands that are not undoable. AsUI() will only return true if the user values is undoable UI, and false if it’s undoable model. With this new functionality, it will also return true for pure UI user values. This method returns which of the three states the user values is defined.

• LXiUSERVALUE_UIMODE_UNDO_UI

• LXiUSERVALUE_UIMODE_PURE_UI

ILxSessionListener

class ILxSessionListener

The session listener provides information about application startup and shutdown. A “session” is defined as the time the app is running, from when it starts to when it exits.

Public Functions

LxResult FirstWindowOpening(LXtObjectID self)

This is called just before the first window (usually the main window) is opened, which generally means that the app is nearing final readiness. This is not sent in headless mode for obvious reasons.

LxResult BeforeStartupCommands(LXtObjectID self)

This is called just before the startup commands are executed. This can be used to execute other startup commands from code, for example, or to query commands.

LxResult SystemReady(LXtObjectID self)

This is called after any startup comamnds have executed, and just before the application main loop starts, and indicates that the application is fully initialized and ready.

LxResult CheckQuitUI(LXtObjectID self, int quitWasAborted)

This is called when the app’s UI is told to quit, usually because the user tried to close the main window or chose Quit from the system menu. Most importantly, the main window is still open at this time, and the listener can open dialogs and is able to abort the quit by returning LXe_FALSE. Remember that you may not be the only session listener, that all listeners will get this event, and that the abort state won’t be read until all listeners have returned (this is jsut how listeners work). Before opening a dialog or doing any other quit tests, you should check the value of quitWasAborted; if ture, you may simply want to exit early because another listeener has decided that we’re not going to quit after all. As the name implies, this method is only sent from the UI, and never from headless. If you need to save critical state, yous hould do so from ShuttingDown().

LxResult QuittingUI(LXtObjectID self)

If no listeners have aborted the quit, this method is called to indicate that we really are going to exit the app. At this point the main window is still open, so if you want to save something with a progress bar or the possibility of opening an error dialog, you can. However, you will not be able to keep the app from quitting. Once again, this is not sent from headless mode.

LxResult LastWindowClosed(LXtObjectID self)

This is called just after the last window (usually the main window) has closed, indicating that the application is about to shut down. This is not sent in headless mode for obvious reasons.

LxResult ShuttingDown(LXtObjectID self)

After all windows have been closed (or in headless, if we’re about to quit), this is called to indicate that we’re going to start shutting down the remaining systems and exit the app. This is a good time to store any other state you may want to persist between sessions.

ILxUserValueListener

class ILxUserValueListener

The user value listener alerts clients when a user value has changed. It also has methods that are called at various points in the startup sequence so that user values can be cached after startup or actions can be taken during the startup process.

Public Functions

LxResult Added(LXtObjectID self, LXtObjectID userValue)

This is called after a new user value is added. The object provided has an ILxUserValue interface. Since the value was just added, the obejct is only immediately useful for getting its name, as everything else will be defaults.

LxResult Deleted(LXtObjectID self, const char *name)

This is called just after an existing user value is deleted. Since the object was just deleted, only the name is provided.

LxResult DefChanged(LXtObjectID self, LXtObjectID userValue)

This is called when the definition (one of the properties) of a user value has changed. The object provided has an ILxUserValue interface.

LxResult ValueChanged(LXtObjectID self, LXtObjectID userValue)

This is called when the user value’s value changes. It is also called for all user values on startup, thus ensuring that clients that only listen for this event can get useful default values. The object provided has an ILxUserValue interface.

ILxScriptManager

class ILxScriptManager

The script manager is provided as a global. It is used to obtain information about a particular scripting subsystem. Each type of script has a matching script manager, although one manager can handle multiple script types. As well as providing a list of available scripts known to the manager, they also include the interpreter used to execute said scripts.

Public Functions

LxResult Name(LXtObjectID self, const char **name)

This returns the name of the script manager, which should be the name of the plug-in itself, or else the system will get very confused. Script manager names should have the format “name.scriptservice”, as the .scriptservice part is automatically skipped during lookup for convenience.

LxResult Flags(LXtObjectID self, int *flags)

• CREATE

• REMOVE These should be set if the Script Editor can create or delete scripts.

• LINE_ACTION This is set if an operation is defined for single lines in a script. For example, double-clicking on a macro line to execute that command.

LxResult Count(LXtObjectID self, unsigned int *count)

These functions allow the list of available scripts to be walked. When getting a script from the manager, the write flag determines if the script is read-only or read/write. This is just a hint; if the script cannot be modified and the write flag is set, the function should fail with LXe_SCRIPT_READONLY.

LxResult ByIndex(LXtObjectID self, unsigned int index, void **ppvObj, int write)

LxResult Lookup(LXtObjectID self, const char *hash, void **ppvObj, int write, int tryAsUserName)

This looks up a script by its hash. Note the lookup may succeed even if it is not in the script list, as the manager may try to load the script off disk, for example. If tryAsUserName is true, the hash will be looked up as a username if it cannot be found as a hash. It is important to note that the hash may not be what you expect. For example, if you normally expect a path to a file, you should be able to handle arbitrary cases like config hashes (say, “872345659345:macro”) and not try to pass them to file system functions that might hit the network and create long delays. Similarly, if you recognize the hash as your own but cannot find the contents, you should return LXe_SCRIPT_RECOGNIZED_INVALID. This keeps other servers from having to scan servers that only you recognize.

LxResult ReadWrite(LXtObjectID self, const char *hash, int index)

Scripts can be read-only (for example, if the perl script is read-only on disk, or the config the macro is in is imported). This function tells if the script can be instanced as read/write or just read-only. Since the intention is to see if the script can be instanced as read/write before you have a script ID, this takes a hash or index as its args; the index is checked if the hash is NULL.

LxResult New(LXtObjectID self, const char *name, void **ppvObj)

A new script for this manager can be created and filled in by the client.

LxResult Remove(LXtObjectID self, LXtObjectID script)

An existing script can be removed from the system. This only removes the script; it does not necessarily delete it from disk.

LxResult Validate(LXtObjectID self, LXtObjectID script, LXtObjectID msg)

Scripts can be validated to ensure that they are supported by the interpreter and to check that they are free of errors before execution. The interpreter should return SCRIPT_UNKNOWN if the script is not supported by the interpreter, and SCRIPT_ERROR if there is a problem parsing the script. SCRIPT_WARNING can be returned if there are only warnings, but since this is an OK code, the script can still be considered mostly valid and thus executable.

LxResult Run(LXtObjectID self, LXtObjectID script, int execFlags, const char *args, LXtObjectID msg)

A script can be executed with this function. The command services global can be used to query and execute commands as needed. Commend execution flags are also provided, which can be used to decide how to interact with the user for warnings, etc. A list of optional arguments can also be provided as a string, or be NULL.

---

LXfSCRIPTSRV_CREATE

Script managers can return a number of flags describing how the manager operates.

• LXfSCRIPTSRV_REMOVE

• LXfSCRIPTSRV_LINE_ACTION

ILxTextScriptInterpreter

class ILxTextScriptInterpreter

Many scripts simply involve parsing text files and interpreting the lines in turn. Rather than forcing the creating of a completely new manager each time, a simple text script interpreter can be created. The script system automatically handles loading of text files from disc, and provides search paths for scripts and so on. All the interpreter needs to do is confirm that it actually can deal with this kind of script and execute it.

Public Functions

LxResult ValidateFileType(LXtObjectID self, LXtObjectID script, const char *firstLine)

An initial validation of the file is performed to figure out what interpreters support which files. The interpreter is provided with an ILxScriptID and the first line of the script, which allows for a common first-line check or a more complete check of the script’s contents via GetBuffer(). The hash of the script is the path of the file on disk, and can be used to check the extension if desired. The interpreter should return LXe_OK if it can deal with this script, and LXe_SCRIPT_UNKNOWN if it cannot. This method should be quick, since it may be called often. Simply check the file type here; don’t test the script for errors or anything like that.

LxResult Validate(LXtObjectID self, LXtObjectID script, LXtObjectID msg)

Before execution of a script, this function is called to ensure that the script is properly formatted for execution by this interpreter. SCRIPT_ERROR can be returned on failer, and SCRIPT_WARNING if the script can be executed, but there may be problems with it. The ILxMessageID can be used to report specific errors.

LxResult Run(LXtObjectID self, LXtObjectID script, int execFlags, const char *args, LXtObjectID msg)

A script can be executed with this function. The command services global can be used to query and execute commands as needed. Commend execution flags are also provided, which can be used to decide how to interact with the user for warnings, etc. A list of optional arguments can also be provided as a string, or be NULL. The ILxMessageID can be used to report specific errors.

ILxScript

class ILxScript

The script system service provides a list of available script managers, rather than having clients browse the plug-in database themselves. Managers are sorted by their internal name (i.e., the name of the plug-in itself), which can also be obtained. Managers must be released when no longer needed. The objects returned by ByIndex(), NameByIndex() and Lookup() must be released by the caller.

Public Functions

LxResult Hash(LXtObjectID self, const char **hash)

Scripts have a hash used for lookup. For macros, it’s just the hash in the config; for scripts in files, it might be the filename.

LxResult UserName(LXtObjectID self, const char **userName)

Scripts may have a username and description.

LxResult SetUserName(LXtObjectID self, const char *userName)

LxResult Desc(LXtObjectID self, const char **desc)

LxResult SetDesc(LXtObjectID self, const char *desc)

LxResult Icon(LXtObjectID self, const char **icon)

This returns a semicolon-delimited list of icon resources. If not implemented, the hash of the script is used.

LxResult HelpKey(LXtObjectID self, const char *args, const char **key)

The script manager can also return a help key, which will be looked up in the HelpURLs config entries. An argument string can also be provided for more specific lookups.

LxResult Manager(LXtObjectID self, void **ppvObj)

The script’s type is obtained by asking for its manager.

LxResult GetBuffer(LXtObjectID self, const char **buffer, unsigned int *bufferLength)

This gets the full text of the script as one large buffer, read-only NUL-terminated text buffer. The length of the buffer is also returned.

LxResult SetBuffer(LXtObjectID self, const char *buffer, unsigned int bufferLength)

This replaces the existing script’s contents with a new one. The buffer should be NUL-terminated, and the buffer length should include the NUL.

ILxPlatformService

class ILxPlatformService

The platform service provides information about the application and OS.

Public Functions

LxResult ScriptQuery(LXtObjectID self, void **ppvObj)

LxResult LicensedTo(LXtObjectID self, const char **licensee)

Get the user the app is licensed to. If not licensed, this fails.

LxResult ExpiresIn(LXtObjectID self, int *daysLeft)

Get the number of days left until the key expires, or -1 if the key is permanent.

LxResult SerialNumber(LXtObjectID self, const char **serial)

Get the serial number of this key.

LxResult NumLicenses(LXtObjectID self, int *licenses)

Get the number of licenses this key works with.

LxResult AppName(LXtObjectID self, const char **name)

Get the application name.

LxResult AppVersion(LXtObjectID self, int *version)

Get the version and build numbers of the application.

LxResult AppBuild(LXtObjectID self, int *build)

LxResult IsHeadless(LXtObjectID self)

This returns LXe_TRUE if the app is running in headless mode, and LXe_FALSE if not.

LxResult OSType(LXtObjectID self, int *type)

LxResult OSName(LXtObjectID self, const char **name)

LxResult OSVersion(LXtObjectID self, const char **version)

LxResult PathCount(LXtObjectID self, int *count)

Walk the list of paths.

LxResult PathByIndex(LXtObjectID self, int index, const char **path)

LxResult PathNameByIndex(LXtObjectID self, int index, const char **name)

This returns the internal name of the path, or NULL if the path doesn’t have one.

LxResult ImportPathCount(LXtObjectID self, int *index)

Walk the list of imported resource paths.

LxResult ImportPathByIndex(LXtObjectID self, int index, const char **path)

LxResult IsApp64Bit(LXtObjectID self)

This returns true if the application (but not necessarily the platform) is 64 bit, and false if it’s 32 bit.

LxResult DoWhenUserIsIdle(LXtObjectID self, LXtObjectID visitor, int flags)

This arms a user idle action, preferably only once until it has been fired, after which you can arm it again if necessary.

LxResult CancelDoWhenUserIsIdle(LXtObjectID self, LXtObjectID visitor, int flags)

This can be used to remove a pending user idle action. It will do nothing if the idle action isn’t armed. Note that flags and the vistor pointer must be exactly the same as the one passed to DoWhenUserIsIdle(), or else it will not be found and the action will remain armed. Note that when doing this from Python, you must pass the exact same visitor COM object (not Python object). This is also necessary when removing listeners and canceling timers, as discussed here: http://modo.sdk.thefoundry.co.uk/wiki/FAQ#Q:_How_do_I_remove_a_listener_object_in_Python.3F

LxResult IsUserIdle(LXtObjectID self)

This simply returns if the user is currently idle. It can be useful at times, but generally you always want to perform your idle actions from DoWhenUserIsIdle().

LxResult IsAppActive(LXtObjectID self)

Another useful feature is to be able to know when the app has become active or inactive. This returns LXe_TRUE if the app is currently active.

LxResult SessionStage(LXtObjectID self, int *stage)

The current session stage can be read with this method, indicating the status of the application.

LxResult AppUsername(LXtObjectID self, const char **name)

• NOT_READY The system is in the very early startup phase, and is not yet ready to be accessed.

• STARTUP_COMMANDS Startup commands are or have just executed, and the system is almost completely up and running.

• SYSTEM_READY The main event loop is running, and the application is fully started.

• SHUTTING_DOWN The main event loop has stopped, and the applicatin is shutting down. You can register an ILxSessionListener to be notified when the stage changes. The application username may be different from the internal name returned by AppName(). Usually this is farily minor, such as the case of the name.

LxResult TimerStart(LXtObjectID self, LXtObjectID visitor, int milliseconds, int idleFlags)

Timers execute after a pre-determiend number of milliseconds. A timer executes only once, but you can re-arm it when it expires if you want. The most common use of timers is to check files for changes or trigger periodic refreshes of part of the UI. Note that timers can trigger at arbitrary and unsafe times, such as in the middle of rendering or while saving a file. You should never execute a command from a timer, for exmaple, but rather arm a user idle action (and even then executing commands is a bit iffy, since now you’re adding something to the command history or undo list that the user didn’t do directly, but sometimes it is necessary).

If idleFlags are LXiUSERIDLE_ALWAYS, then the timer’s visitor is called as soon as the timer expires. Otherwise, the action is deferred until user idle state matches the flags.

LxResult TimerCancel(LXtObjectID self, LXtObjectID visitor, int idleFlags)

A currently-running timer can be canceled with this function. The visitor and flags must match what the timer was armed with. Note that when doing this from Python, you must pass the exact same visitor COM object (not Python object). This is also necessary when removing listeners and canceling user idle actions, as discussed here: http://modo.sdk.thefoundry.co.uk/wiki/FAQ#Q:_How_do_I_remove_a_listener_object_in_Python.3F

LxResult IsSafeMode(LXtObjectID self)

This will return true if the app was started in safe mode.

LxResult AppVersionMinor(LXtObjectID self, int *version)

Get the minor and service back version numbers.

LxResult AppVersionSP(LXtObjectID self, int *version)

LxResult AppVersionMajor(LXtObjectID self, int *version)

std::string LicensedTo()

User Class Only:

std::string SerialNumber()

User Class Only:

std::string AppName()

User Class Only:

bool IsHeadless()

User Class Only:

std::string OSName()

User Class Only:

std::string OSVersion()

User Class Only:

const char *GetPath(int index)

User Class Only:

const char *GetPathName(int index)

User Class Only:

const char *GetImportPath(int index)

User Class Only:

bool IsApp64Bit()

User Class Only:

std::string AppUsername()

User Class Only:

---

LXiOSTYPE_UNKNOWN

Get the OS type, OS name and OS version string.

• LXiOSTYPE_WIN32

• LXiOSTYPE_MACOSX

• LXiOSTYPE_LINUX

---

LXiUSERIDLE_ALWAYS

There are cases where plug-ins have out-of-band actions they need to execute from the main thread when it is safe to do so. An example might be modo’s own telnet service, which can receive commands at any time but can only execute them when it is safe to do so, a time that we refer to as “user idle”. This method can be used to perform an action a visitor when the user is idle. It is always performed from the main thread. There are a number of criteria that can be used to define “idle”. You can set whatever combination of flags you want, except for ALWAYS, which is a special case that is executed immediately.

Generally speaking, you’ll want to use ALL_IDLE, combined with APP_MUST_BE_ACTIVE when applicable and just leave it at that. It should be rare to need to remove specific flags.

• ALWAYS A special-case value; if passed, the user idle action is executed as soon as possible. This is rarely used, as it does not make sure it is safe to perform such an action the user may be in the middle of a file dialog or rendering or something like that. Extreme care should be taken when using his functionality.

• APP_MUST_BE_ACTIVE The application must be active, meaning that it currently has the focus in the OS.

• KEYS_UP No keys on the keyboard can be pressed.

• MODIFIER_KEYS_UP No keys defined as modifiers can be pressed.

• NO_DIALOGS_OPEN All dialogs (system dialogs, modal dialogs, etc) must be closed.

• CMD_STACK_EMPTY No commands can be currently be executing.

• NO_SUB_INPUT_LOOP Somewhat escoteric, this ensures that we’re in the main application input loop. In some cases there are secondary input loops used for special things, like modal dialogs.

• EDIT_FIELDS_UNFOCUSED No edit fields have focus.

• ALL_IDLE This mask is what is usually set, and contains all of the above flags except for APP_MUST_BE_ACTIVE.

NOTE: These defines MUST match the USERIDLEf_ defines in awin.

• LXfUSERIDLE_APP_MUST_BE_ACTIVE

• LXfUSERIDLE_MOUSE_BUTTONS_UP

• LXfUSERIDLE_KEYS_UP

• LXfUSERIDLE_MODIFIER_KEYS_UP

• LXfUSERIDLE_NO_DIALOGS_OPEN

• LXfUSERIDLE_NO_POPS_OPEN

• LXfUSERIDLE_CMD_STACK_EMPTY

• LXfUSERIDLE_NO_SUB_INPUT_LOOP

• LXfUSERIDLE_EDIT_FIELDS_UNFOCUSED

• LXfUSERIDLE_SCENE_STABLE

• USERIDLEf_ALL_IDLE

---

LXfSESSIONSTAGE_STARTUP

The stage can be one of the following:

• LXfSESSIONSTAGE_READY

• LXfSESSIONSTAGE_SHUTDOWN

• LXiSESSIONSTAGE_NOT_READY

• LXiSESSIONSTAGE_STARTUP_COMMANDS

• LXiSESSIONSTAGE_SYSTEM_READY

• LXiSESSIONSTAGE_SHUTTING_DOWN

ILxAppActiveListener

class ILxAppActiveListener

Clients can be notified when the application gets or loses focus by listening to the ILxAppActiveListener port. A common use of this is to check to see if any files have changed since the user last left the app, or to pause some networking or other interprocess communication until the app gains/loses focus again.

Public Functions

LxResult IsNowActive(LXtObjectID self, int isActive)

This is called with true when the app becomes active, and false when it becomes inactive. User idle actions can be armed from this method to execute commands as needed.

ILxLineInterpreter

class ILxLineInterpreter

A line interpreter is a persistent server that interprets lines of text as interactive commands. The simplest (built-in) interpreter is one that treats each line of input as a command or query and generates output. More complex interpreters could process input using a scripting language.

Public Functions

unsigned Flags(LXtObjectID self)

LxResult Prompt(LXtObjectID self, const char **prompt, unsigned type)

• NOPROMPT The user-provided or default prompt is used, and the server does not define its own.

• NORESULT Determines if the “ok” text is output in headless mode after successfully executing a line.

• NOCOOKING Dunno.

• NOUNDOS The server does not create undos, and will not appear in the Command Histroy’s unod list or history. This used for the special-case of the built-in command line interpreter, since commands implicitly have undos and are directly handled by the undo systme. It is extremely dangerous to perform undos (intentionally or not) with this flag set. Get the prompt string. CURRENT returns the active prompt based on the state of the interpreter. ALTERNATE gives the other possible prompt, if any.

LxResult Execute(LXtObjectID self, const char *line, int execFlags, LXtObjectID execution)

Execute a line. The flags are used for executing commands, and the execution object receives the results. Errors can be returned as the return value or through the message object, although return values take precedence. The special value LINEISCOMMENT can also be returned.

• LXfLINT_NOPROMPT

• LXfLINT_NORESULT

• LXfLINT_NOCOOKING

• LXfLINT_NOUNDOS

• LXiLINT_CURRENT

• LXiLINT_ALTERNATE

ILxLineExecution

class ILxLineExecution

The execution object is just a way for the interpreter to pass results back to the caller.

Public Functions

LxResult CookedLine(LXtObjectID self, const char *text)

All of these methods are optional and hold the results of ececuting the interpreted line.

• CookedLine the line string echoed back after processing. For the command interpreter this includes normalizing arguments.

• Message a Message object holding the result code and success/failure statement.

• Results a ValueArray object holding a list of query results.

• ResultHints hints for decoding integer results into strings.

• Info text lines to report status back to the user. This may be called multiple times.

LxResult Message(LXtObjectID self, LXtObjectID message)

LxResult Results(LXtObjectID self, LXtObjectID valArray)

LxResult ResultHints(LXtObjectID self, const LXtTextValueHint *hints)

LxResult Info(LXtObjectID self, const char *text)

ILxScriptLineEvent

class ILxScriptLineEvent

This interface provides the line number edited and the script it was edited in.

Public Functions

LxResult Index(LXtObjectID self, unsigned int *index)

LxResult Script(LXtObjectID self, void **ppvObj)