XLua2 API Ref XPLMUtilities Latest - 4.4.0-d4

X-Plane Command Management

The command management APIs let plugins interact with the command-system in X-Plane, the abstraction behind keyboard presses and joystick buttons. This API lets you create new commands and modify the behavior (or get notification) of existing ones.

X-Plane Command Phases

X-Plane commands are not instantaneous; they operate over a duration. (Think of a joystick button press - you can press, hold down, and then release the joystick button; X-Plane commands model this entire process.)

An X-Plane command consists of three phases: a beginning, continuous repetition, and an ending. The command may be repeated zero times in its duration, followed by one command ending. Command begin and end messges are balanced, but a command may be bound to more than one event source (e.g. a keyboard key and a joystick button), in which case you may receive a second begin during before any end).

When you issue commands in the plugin system, you must balance every call to XPLMCommandBegin with a call to XPLMCommandEnd with the same command reference.

Command Behavior Modification

You can register a callback to handle a command either before or after X-Plane does; if you receive the command before X-Plane you have the option to either let X-Plane handle the command or hide the command from X-Plane. This lets plugins both augment commands and replace them.

If you register for an existing command, be sure that you are consistent in letting X-Plane handle or not handle the command; you are responsible for passing a balanced number of begin and end messages to X-Plane. (E.g. it is not legal to pass all the begin messages to X-Plane but hide all the end messages).

XPLMCommandPhase

enum

The phases of a command.

Name Value Description
xplm_CommandBegin 0 The command is being started.
xplm_CommandContinue 1 The command is continuing to execute.
xplm_CommandEnd 2 The command has ended.

Used by:

XPLMCommandRef

typedef

A command ref is an opaque identifier for an X-Plane command. Command references stay the same for the life of your plugin but not between executions of X-Plane. Command refs are used to execute commands, create commands, and create callbacks for particular commands.

Note that a command is not "owned" by a particular plugin. Since many plugins may participate in a command's execution, the command does not go away if the plugin that created it is unloaded.

local my_commandRef = nil  -- XPLMCommandRef

Used by:

XPLMCommandCallback_f

callback

A command callback is a function in your plugin that is called when a command is pressed. Your callback receives the command reference for the particular command, the phase of the command that is executing, and a reference pointer that you specify when registering the callback.

Your command handler should return true to let processing of the command continue to other plugins and X-Plane, or false to halt processing, potentially bypassing X-Plane code.

function my_CommandCallback_callback(
    inCommand,    -- XPLMCommandRef
    inPhase,      -- XPLMCommandPhase
    inRefcon      -- any Lua var/table
)
    -- your code here
    return true  -- boolean
end

See associated types:

XPLMFindCommand

function

XPLMFindCommand looks up a command by name, and returns its command reference or NULL if the command does not exist.

-- returns XPLMCommandRef -> assign to local/var
local my_commandRef = XPLMFindCommand(
    inName     -- string
)

XPLMCommandBegin

function

XPLMCommandBegin starts the execution of a command, specified by its command reference. The command is "held down" until XPLMCommandEnd is called. You must balance each XPLMCommandBegin call with an XPLMCommandEnd call.

XPLMCommandBegin(
    inCommand     -- XPLMCommandRef
)

See associated types:

XPLMCommandEnd

function

XPLMCommandEnd ends the execution of a given command that was started with XPLMCommandBegin. You must not issue XPLMCommandEnd for a command you did not begin.

XPLMCommandEnd(
    inCommand     -- XPLMCommandRef
)

See associated types:

XPLMCommandOnce

function

This executes a given command momentarily, that is, the command begins and ends immediately. This is the equivalent of calling XPLMCommandBegin() and XPLMCommandEnd() back to back.

XPLMCommandOnce(
    inCommand     -- XPLMCommandRef
)

See associated types:

XPLMCreateCommand

function

XPLMCreateCommand creates a new command for a given string. If the command already exists, the existing command reference is returned. The description may appear in user interface contexts, such as the joystick configuration screen.

-- returns XPLMCommandRef -> assign to local/var
local my_commandRef = XPLMCreateCommand(
    inName,           -- string
    inDescription     -- string
)

XPLMRegisterCommandHandler

function

XPLMRegisterCommandHandler registers a callback to be called when a command is executed. You provide a callback with a reference pointer.

If inBefore is true, your command handler callback will be executed before X-Plane executes the command, and returning 0 from your callback will disable X-Plane's processing of the command. If inBefore is false, your callback will run after X-Plane. (You can register a single callback both before and after a command.)

XPLMRegisterCommandHandler(
    inComand,     -- XPLMCommandRef
    inHandler,    -- see XPLMCommandCallback_f
    inBefore,     -- boolean
    inRefcon      -- any Lua var/table
)

See associated types:

XPLMUnregisterCommandHandler

function

XPLMUnregisterCommandHandler removes a command callback registered with XPLMRegisterCommandHandler.

XPLMUnregisterCommandHandler(
    inComand,     -- XPLMCommandRef
    inHandler,    -- see XPLMCommandCallback_f
    inBefore,     -- boolean
    inRefcon      -- any Lua var/table
)

See associated types: