952 lines
35 KiB
ObjectPascal
952 lines
35 KiB
ObjectPascal
{
|
|
Copyright 2005-2012 Sandy Barbour and Ben Supnik All rights reserved. See
|
|
license.txt for usage. X-Plane SDK Version: 2.1.1
|
|
}
|
|
|
|
UNIT XPLMUtilities;
|
|
INTERFACE
|
|
|
|
USES
|
|
XPLMDefs;
|
|
{$A4}
|
|
{___________________________________________________________________________
|
|
* FILE UTILITIES
|
|
___________________________________________________________________________}
|
|
{
|
|
The XPLMUtilities file APIs provide some basic file and path functions for
|
|
use with X-Plane.
|
|
|
|
Directory Separators
|
|
--------------------
|
|
|
|
The XPLM has two modes it can work in:
|
|
|
|
* X-Plane native paths: all paths are UTF8 strings, using the unix forward
|
|
slash (/) as the directory separating character. In native path mode,
|
|
you use the same path format for all three operating systems.
|
|
|
|
* Legacy OS paths: the directroy separator is \ for Windows, : for OS X,
|
|
and / for Linux; OS paths are encoded in MacRoman for OS X using legacy
|
|
HFS conventions, use the application code page for multi-byte encoding
|
|
on Unix using DOS path conventions, and use UTF-8 for Linux.
|
|
|
|
While legacy OS paths are the default, we strongly encourage you to opt in
|
|
to native paths using the XPLMEnableFeature API.
|
|
|
|
* All OS X plugins should enable native paths all of the time; if you do
|
|
not do this, you will have to convert all paths back from HFS to Unix
|
|
(and deal with MacRoman) - code written using native paths and the C
|
|
file APIs "just works" on OS X.
|
|
|
|
* For Linux plugins, there is no difference between the two encodings.
|
|
|
|
* Windows plugins will need to convert the UTF8 file paths to UTF16 for
|
|
use with the "wide" APIs. While it might seem tempting to stick with
|
|
legacy OS paths (and just use the "ANSI" Windows APIs), X-Plane is fully
|
|
unicode-capable, and will often be installed in paths where the user's
|
|
directories have no ACP encoding.
|
|
|
|
Full and Relative Paths
|
|
-----------------------
|
|
|
|
Some of these APIs use full paths, but others use paths relative to the
|
|
user's X-Plane installation. This is documented on a per-API basis.
|
|
}
|
|
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMDataFileType
|
|
|
|
These enums define types of data files you can load or unload using the
|
|
SDK.
|
|
}
|
|
TYPE
|
|
XPLMDataFileType = (
|
|
{ A situation (.sit) file, which starts off a flight in a given }
|
|
{ configuration. }
|
|
xplm_DataFile_Situation = 1
|
|
|
|
{ A situation movie (.smo) file, which replays a past flight. }
|
|
,xplm_DataFile_ReplayMovie = 2
|
|
|
|
);
|
|
PXPLMDataFileType = ^XPLMDataFileType;
|
|
{$ENDIF XPLM200}
|
|
|
|
{
|
|
XPLMGetSystemPath
|
|
|
|
This function returns the full path to the X-System folder. Note that this
|
|
is a directory path, so it ends in a trailing : or /.
|
|
|
|
The buffer you pass should be at least 512 characters long. The path is
|
|
returned using the current native or OS path conventions.
|
|
}
|
|
PROCEDURE XPLMGetSystemPath(
|
|
outSystemPath : XPLMString);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMGetPrefsPath
|
|
|
|
This routine returns a full path to a file that is within X-Plane's
|
|
preferences directory. (You should remove the file name back to the last
|
|
directory separator to get the preferences directory using
|
|
XPLMExtractFileAndPath.)
|
|
|
|
The buffer you pass should be at least 512 characters long. The path is
|
|
returned using the current native or OS path conventions.
|
|
}
|
|
PROCEDURE XPLMGetPrefsPath(
|
|
outPrefsPath : XPLMString);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMGetDirectorySeparator
|
|
|
|
This routine returns a string with one char and a null terminator that is
|
|
the directory separator for the current platform. This allows you to write
|
|
code that concatinates directory paths without having to #ifdef for
|
|
platform. The character returned will reflect the current file path mode.
|
|
}
|
|
FUNCTION XPLMGetDirectorySeparator: XPLMString;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMExtractFileAndPath
|
|
|
|
Given a full path to a file, this routine separates the path from the file.
|
|
If the path is a partial directory (e.g. ends in : or \) the trailing
|
|
directory separator is removed. This routine works in-place; a pointer to
|
|
the file part of the buffer is returned; the original buffer still starts
|
|
with the path and is null terminated with no trailing separator.
|
|
}
|
|
FUNCTION XPLMExtractFileAndPath(
|
|
inFullPath : XPLMString) : XPLMString;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMGetDirectoryContents
|
|
|
|
This routine returns a list of files in a directory (specified by a full
|
|
path, no trailing : or \). The output is returned as a list of NULL
|
|
terminated strings. An index array (if specified) is filled with pointers
|
|
into the strings. The last file is indicated by a zero-length string (and
|
|
NULL in the indices). This routine will return 1 if you had capacity for
|
|
all files or 0 if you did not. You can also skip a given number of files.
|
|
|
|
* inDirectoryPath - a null terminated C string containing the full path to
|
|
the directory with no trailing directory char.
|
|
|
|
* inFirstReturn - the zero-based index of the first file in the directory
|
|
to return. (Usually zero to fetch all in one pass.)
|
|
|
|
* outFileNames - a buffer to receive a series of sequential null
|
|
terminated C-string file names. A zero-length C string will be appended
|
|
to the very end.
|
|
|
|
* inFileNameBufSize - the size of the file name buffer in bytes.
|
|
|
|
* outIndices - a pointer to an array of character pointers that will
|
|
become an index into the directory. The last file will be followed by a
|
|
NULL value. Pass NULL if you do not want indexing information.
|
|
|
|
* inIndexCount - the max size of the index in entries.
|
|
|
|
* outTotalFiles - if not NULL, this is filled in with the number of files
|
|
in the directory.
|
|
|
|
* outReturnedFiles - if not NULL, the number of files returned by this
|
|
iteration.
|
|
|
|
Return value: 1 if all info could be returned, 0 if there was a buffer
|
|
overrun.
|
|
|
|
WARNING: Before X-Plane 7 this routine did not properly iterate through
|
|
directories. If X-Plane
|
|
6 compatibility is needed, use your own code to iterate directories.
|
|
}
|
|
FUNCTION XPLMGetDirectoryContents(
|
|
inDirectoryPath : XPLMString;
|
|
inFirstReturn : Integer;
|
|
outFileNames : XPLMString;
|
|
inFileNameBufSize : Integer;
|
|
outIndices : PXPLMString; { Can be nil }
|
|
inIndexCount : Integer;
|
|
outTotalFiles : PInteger; { Can be nil }
|
|
outReturnedFiles : PInteger) : Integer; { Can be nil }
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMLoadDataFile
|
|
|
|
Loads a data file of a given type. Paths must be relative to the X-System
|
|
folder. To clear the replay, pass a NULL file name (this is only valid with
|
|
replay movies, not sit files).
|
|
}
|
|
FUNCTION XPLMLoadDataFile(
|
|
inFileType : XPLMDataFileType;
|
|
inFilePath : XPLMString) : Integer; { Can be nil }
|
|
cdecl; external XPLM_DLL;
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMSaveDataFile
|
|
|
|
Saves the current situation or replay; paths are relative to the X-System
|
|
folder.
|
|
}
|
|
FUNCTION XPLMSaveDataFile(
|
|
inFileType : XPLMDataFileType;
|
|
inFilePath : XPLMString) : Integer;
|
|
cdecl; external XPLM_DLL;
|
|
{$ENDIF XPLM200}
|
|
|
|
{___________________________________________________________________________
|
|
* X-PLANE MISC
|
|
___________________________________________________________________________}
|
|
|
|
{
|
|
XPLMHostApplicationID
|
|
|
|
While the plug-in SDK is only accessible to plugins running inside X-Plane,
|
|
the original authors considered extending the API to other applications
|
|
that shared basic infrastructure with X-Plane. These enumerations are
|
|
hold-overs from that original roadmap; all values other than X-Plane are
|
|
deprecated. Your plugin should never need this enumeration.
|
|
}
|
|
TYPE
|
|
XPLMHostApplicationID = (
|
|
xplm_Host_Unknown = 0
|
|
|
|
,xplm_Host_XPlane = 1
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_PlaneMaker = 2
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_WorldMaker = 3
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_Briefer = 4
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_PartMaker = 5
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_YoungsMod = 6
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
,xplm_Host_XAuto = 7
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
);
|
|
PXPLMHostApplicationID = ^XPLMHostApplicationID;
|
|
|
|
{
|
|
XPLMLanguageCode
|
|
|
|
These enums define what language the sim is running in. These enumerations
|
|
do not imply that the sim can or does run in all of these languages; they
|
|
simply provide a known encoding in the event that a given sim version is
|
|
localized to a certain language.
|
|
}
|
|
XPLMLanguageCode = (
|
|
xplm_Language_Unknown = 0
|
|
|
|
,xplm_Language_English = 1
|
|
|
|
,xplm_Language_French = 2
|
|
|
|
,xplm_Language_German = 3
|
|
|
|
,xplm_Language_Italian = 4
|
|
|
|
,xplm_Language_Spanish = 5
|
|
|
|
,xplm_Language_Korean = 6
|
|
|
|
{$IFDEF XPLM200}
|
|
,xplm_Language_Russian = 7
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM200}
|
|
,xplm_Language_Greek = 8
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM200}
|
|
,xplm_Language_Japanese = 9
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM300}
|
|
,xplm_Language_Chinese = 10
|
|
{$ENDIF XPLM300}
|
|
|
|
);
|
|
PXPLMLanguageCode = ^XPLMLanguageCode;
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMError_f
|
|
|
|
An XPLM error callback is a function that you provide to receive debugging
|
|
information from the plugin SDK. See XPLMSetErrorCallback for more
|
|
information. NOTE: for the sake of debugging, your error callback will be
|
|
called even if your plugin is not enabled, allowing you to receive debug
|
|
info in your XPluginStart and XPluginStop callbacks. To avoid causing logic
|
|
errors in the management code, do not call any other plugin routines from
|
|
your error callback - it is only meant for catching errors in the
|
|
debugging.
|
|
}
|
|
TYPE
|
|
XPLMError_f = PROCEDURE(
|
|
inMessage : XPLMString); cdecl;
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
{
|
|
XPLMInitialized
|
|
|
|
Deprecated: This function returns 1 if X-Plane has properly initialized the
|
|
plug-in system. If this routine returns 0, many XPLM functions will not
|
|
work.
|
|
|
|
NOTE: because plugins are always called from within the XPLM, there is no
|
|
need to check for initialization; it will always return 1. This routine is
|
|
deprecated - you do not need to check it before continuing within your
|
|
plugin.
|
|
}
|
|
FUNCTION XPLMInitialized: Integer;
|
|
cdecl; external XPLM_DLL;
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
{
|
|
XPLMGetVersions
|
|
|
|
This routine returns the revision of both X-Plane and the XPLM DLL. All
|
|
versions are three-digit decimal numbers (e.g. 606 for version 6.06 of
|
|
X-Plane); the current revision of the XPLM is 200 (2.00). This routine also
|
|
returns the host ID of the app running us.
|
|
|
|
The most common use of this routine is to special-case around X-Plane
|
|
version-specific behavior.
|
|
}
|
|
PROCEDURE XPLMGetVersions(
|
|
outXPlaneVersion : PInteger;
|
|
outXPLMVersion : PInteger;
|
|
outHostID : PXPLMHostApplicationID);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMGetLanguage
|
|
|
|
This routine returns the langauge the sim is running in.
|
|
}
|
|
FUNCTION XPLMGetLanguage: XPLMLanguageCode;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMFindSymbol
|
|
|
|
This routine will attempt to find the symbol passed in the inString
|
|
parameter. If the symbol is found a pointer the function is returned,
|
|
othewise the function will return NULL.
|
|
|
|
You can use XPLMFindSymbol to utilize newer SDK API features without
|
|
requiring newer versions of the SDK (and X-Plane) as your minimum X-Plane
|
|
version as follows:
|
|
|
|
* Define the XPLMnnn macro to the minimum required XPLM version you will
|
|
ship with (e.g. XPLM210 for X-Plane 10 compatibility).
|
|
|
|
* Use XPLMGetVersions and XPLMFindSymbol to detect that the host sim is
|
|
new enough to use new functions and resolve function pointers.
|
|
|
|
* Conditionally use the new functions if and only if XPLMFindSymbol only
|
|
returns a non- NULL pointer.
|
|
|
|
Warning: you should always check the XPLM API version as well as the
|
|
results of XPLMFindSymbol to determine if funtionality is safe to use.
|
|
|
|
To use functionality via XPLMFindSymbol you will need to copy your own
|
|
definitions of the X-Plane API prototypes and cast the returned pointer to
|
|
the correct type.
|
|
}
|
|
FUNCTION XPLMFindSymbol(
|
|
inString : XPLMString) : pointer;
|
|
cdecl; external XPLM_DLL;
|
|
{$ENDIF XPLM200}
|
|
|
|
{$IFDEF XPLM200}
|
|
{
|
|
XPLMSetErrorCallback
|
|
|
|
XPLMSetErrorCallback installs an error-reporting callback for your plugin.
|
|
Normally the plugin system performs minimum diagnostics to maximize
|
|
performance. When you install an error callback, you will receive calls due
|
|
to certain plugin errors, such as passing bad parameters or incorrect data.
|
|
|
|
Important: the error callback determines *programming* errors, e.g. bad API
|
|
parameters. Every error that is returned by the error callback represents a
|
|
mistake in your plugin that you should fix. Error callbacks are not used to
|
|
report expected run-time problems (e.g. disk I/O errors).
|
|
|
|
The intention is for you to install the error callback during debug
|
|
sections and put a break-point inside your callback. This will cause you to
|
|
break into the debugger from within the SDK at the point in your plugin
|
|
where you made an illegal call.
|
|
|
|
Installing an error callback may activate error checking code that would
|
|
not normally run, and this may adversely affect performance, so do not
|
|
leave error callbacks installed in shipping plugins. Since the only useful
|
|
response to an error is to change code, error callbacks are not useful "in
|
|
the field".
|
|
}
|
|
PROCEDURE XPLMSetErrorCallback(
|
|
inCallback : XPLMError_f);
|
|
cdecl; external XPLM_DLL;
|
|
{$ENDIF XPLM200}
|
|
|
|
{
|
|
XPLMDebugString
|
|
|
|
This routine outputs a C-style string to the Log.txt file. The file is
|
|
immediately flushed so you will not lose data. (This does cause a
|
|
performance penalty.)
|
|
|
|
Please do *not* leave routine diagnostic logging enabled in your shipping
|
|
plugin. The X-Plane Log file is shared by X-Plane and every plugin in the
|
|
system, and plugins that (when functioning normally) print verbose log
|
|
output make it difficult for developers to find error conditions from other
|
|
parts of the system.
|
|
}
|
|
PROCEDURE XPLMDebugString(
|
|
inString : XPLMString);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMSpeakString
|
|
|
|
This function displays the string in a translucent overlay over the current
|
|
display and also speaks the string if text-to-speech is enabled. The string
|
|
is spoken asynchronously, this function returns immediately. This function
|
|
may not speak or print depending on user preferences.
|
|
}
|
|
PROCEDURE XPLMSpeakString(
|
|
inString : XPLMString);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMGetVirtualKeyDescription
|
|
|
|
Given a virtual key code (as defined in XPLMDefs.h) this routine returns a
|
|
human-readable string describing the character. This routine is provided
|
|
for showing users what keyboard mappings they have set up. The string may
|
|
read 'unknown' or be a blank or NULL string if the virtual key is unknown.
|
|
}
|
|
FUNCTION XPLMGetVirtualKeyDescription(
|
|
inVirtualKey : XPLMChar) : XPLMString;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMReloadScenery
|
|
|
|
XPLMReloadScenery reloads the current set of scenery. You can use this
|
|
function in two typical ways: simply call it to reload the scenery, picking
|
|
up any new installed scenery, .env files, etc. from disk. Or, change the
|
|
lat/ref and lon/ref data refs and then call this function to shift the
|
|
scenery environment. This routine is equivalent to picking "reload
|
|
scenery" from the developer menu.
|
|
}
|
|
PROCEDURE XPLMReloadScenery;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{$IFDEF XPLM200}
|
|
{___________________________________________________________________________
|
|
* 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
|
|
|
|
The phases of a command.
|
|
}
|
|
TYPE
|
|
XPLMCommandPhase = (
|
|
{ The command is being started. }
|
|
xplm_CommandBegin = 0
|
|
|
|
{ The command is continuing to execute. }
|
|
,xplm_CommandContinue = 1
|
|
|
|
{ The command has ended. }
|
|
,xplm_CommandEnd = 2
|
|
|
|
);
|
|
PXPLMCommandPhase = ^XPLMCommandPhase;
|
|
|
|
{
|
|
XPLMCommandRef
|
|
|
|
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.
|
|
}
|
|
XPLMCommandRef = pointer;
|
|
PXPLMCommandRef = ^XPLMCommandRef;
|
|
|
|
{
|
|
XPLMCommandCallback_f
|
|
|
|
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 1 to let processing of the command
|
|
continue to other plugins and X-Plane, or 0 to halt processing, potentially
|
|
bypassing X-Plane code.
|
|
}
|
|
XPLMCommandCallback_f = FUNCTION(
|
|
inCommand : XPLMCommandRef;
|
|
inPhase : XPLMCommandPhase;
|
|
inRefcon : pointer) : Integer; cdecl;
|
|
|
|
{
|
|
XPLMFindCommand
|
|
|
|
XPLMFindCommand looks up a command by name, and returns its command
|
|
reference or NULL if the command does not exist.
|
|
}
|
|
FUNCTION XPLMFindCommand(
|
|
inName : XPLMString) : XPLMCommandRef;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandBegin
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPLMCommandBegin(
|
|
inCommand : XPLMCommandRef);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandEnd
|
|
|
|
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.
|
|
}
|
|
PROCEDURE XPLMCommandEnd(
|
|
inCommand : XPLMCommandRef);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandOnce
|
|
|
|
This executes a given command momentarily, that is, the command begins and
|
|
ends immediately. This is the equivalent of calling XPLMCommandBegin() and
|
|
XPLMCommandEnd() back ot back.
|
|
}
|
|
PROCEDURE XPLMCommandOnce(
|
|
inCommand : XPLMCommandRef);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCreateCommand
|
|
|
|
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.
|
|
}
|
|
FUNCTION XPLMCreateCommand(
|
|
inName : XPLMString;
|
|
inDescription : XPLMString) : XPLMCommandRef;
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMRegisterCommandHandler
|
|
|
|
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.)
|
|
}
|
|
PROCEDURE XPLMRegisterCommandHandler(
|
|
inComand : XPLMCommandRef;
|
|
inHandler : XPLMCommandCallback_f;
|
|
inBefore : Integer;
|
|
inRefcon : pointer);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMUnregisterCommandHandler
|
|
|
|
XPLMUnregisterCommandHandler removes a command callback registered with
|
|
XPLMRegisterCommandHandler.
|
|
}
|
|
PROCEDURE XPLMUnregisterCommandHandler(
|
|
inComand : XPLMCommandRef;
|
|
inHandler : XPLMCommandCallback_f;
|
|
inBefore : Integer;
|
|
inRefcon : pointer);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{$ENDIF XPLM200}
|
|
{$IFDEF XPLM_DEPRECATED}
|
|
{___________________________________________________________________________
|
|
* X-PLANE USER INTERACTION
|
|
___________________________________________________________________________}
|
|
{
|
|
WARNING: The legacy user interaction API is deprecated; while it was the
|
|
only way to run commands in X-Plane 6,7 and 8, it is obsolete, and was
|
|
replaced by the command system API in X-Plane 9. You should not use this
|
|
API; replace any of the calls below with XPLMCommand invocations based on
|
|
persistent command strings. The documentation that follows is for historic
|
|
reference only.
|
|
|
|
The legacy user interaction APIs let you simulate commands the user can do
|
|
with a joystick, keyboard etc. Note that it is generally safer for future
|
|
compatibility to use one of these commands than to manipulate the
|
|
underlying sim data.
|
|
}
|
|
|
|
|
|
{
|
|
XPLMCommandKeyID
|
|
|
|
These enums represent all the keystrokes available within X-Plane. They can
|
|
be sent to X-Plane directly. For example, you can reverse thrust using
|
|
these enumerations.
|
|
}
|
|
TYPE
|
|
XPLMCommandKeyID = (
|
|
xplm_key_pause=0,
|
|
xplm_key_revthrust,
|
|
xplm_key_jettison,
|
|
xplm_key_brakesreg,
|
|
xplm_key_brakesmax,
|
|
xplm_key_gear,
|
|
xplm_key_timedn,
|
|
xplm_key_timeup,
|
|
xplm_key_fadec,
|
|
xplm_key_otto_dis,
|
|
xplm_key_otto_atr,
|
|
xplm_key_otto_asi,
|
|
xplm_key_otto_hdg,
|
|
xplm_key_otto_gps,
|
|
xplm_key_otto_lev,
|
|
xplm_key_otto_hnav,
|
|
xplm_key_otto_alt,
|
|
xplm_key_otto_vvi,
|
|
xplm_key_otto_vnav,
|
|
xplm_key_otto_nav1,
|
|
xplm_key_otto_nav2,
|
|
xplm_key_targ_dn,
|
|
xplm_key_targ_up,
|
|
xplm_key_hdgdn,
|
|
xplm_key_hdgup,
|
|
xplm_key_barodn,
|
|
xplm_key_baroup,
|
|
xplm_key_obs1dn,
|
|
xplm_key_obs1up,
|
|
xplm_key_obs2dn,
|
|
xplm_key_obs2up,
|
|
xplm_key_com1_1,
|
|
xplm_key_com1_2,
|
|
xplm_key_com1_3,
|
|
xplm_key_com1_4,
|
|
xplm_key_nav1_1,
|
|
xplm_key_nav1_2,
|
|
xplm_key_nav1_3,
|
|
xplm_key_nav1_4,
|
|
xplm_key_com2_1,
|
|
xplm_key_com2_2,
|
|
xplm_key_com2_3,
|
|
xplm_key_com2_4,
|
|
xplm_key_nav2_1,
|
|
xplm_key_nav2_2,
|
|
xplm_key_nav2_3,
|
|
xplm_key_nav2_4,
|
|
xplm_key_adf_1,
|
|
xplm_key_adf_2,
|
|
xplm_key_adf_3,
|
|
xplm_key_adf_4,
|
|
xplm_key_adf_5,
|
|
xplm_key_adf_6,
|
|
xplm_key_transpon_1,
|
|
xplm_key_transpon_2,
|
|
xplm_key_transpon_3,
|
|
xplm_key_transpon_4,
|
|
xplm_key_transpon_5,
|
|
xplm_key_transpon_6,
|
|
xplm_key_transpon_7,
|
|
xplm_key_transpon_8,
|
|
xplm_key_flapsup,
|
|
xplm_key_flapsdn,
|
|
xplm_key_cheatoff,
|
|
xplm_key_cheaton,
|
|
xplm_key_sbrkoff,
|
|
xplm_key_sbrkon,
|
|
xplm_key_ailtrimL,
|
|
xplm_key_ailtrimR,
|
|
xplm_key_rudtrimL,
|
|
xplm_key_rudtrimR,
|
|
xplm_key_elvtrimD,
|
|
xplm_key_elvtrimU,
|
|
xplm_key_forward,
|
|
xplm_key_down,
|
|
xplm_key_left,
|
|
xplm_key_right,
|
|
xplm_key_back,
|
|
xplm_key_tower,
|
|
xplm_key_runway,
|
|
xplm_key_chase,
|
|
xplm_key_free1,
|
|
xplm_key_free2,
|
|
xplm_key_spot,
|
|
xplm_key_fullscrn1,
|
|
xplm_key_fullscrn2,
|
|
xplm_key_tanspan,
|
|
xplm_key_smoke,
|
|
xplm_key_map,
|
|
xplm_key_zoomin,
|
|
xplm_key_zoomout,
|
|
xplm_key_cycledump,
|
|
xplm_key_replay,
|
|
xplm_key_tranID,
|
|
xplm_key_max
|
|
);
|
|
PXPLMCommandKeyID = ^XPLMCommandKeyID;
|
|
|
|
{
|
|
XPLMCommandButtonID
|
|
|
|
These are enumerations for all of the things you can do with a joystick
|
|
button in X-Plane. They currently match the buttons menu in the equipment
|
|
setup dialog, but these enums will be stable even if they change in
|
|
X-Plane.
|
|
}
|
|
XPLMCommandButtonID = (
|
|
xplm_joy_nothing=0,
|
|
xplm_joy_start_all,
|
|
xplm_joy_start_0,
|
|
xplm_joy_start_1,
|
|
xplm_joy_start_2,
|
|
xplm_joy_start_3,
|
|
xplm_joy_start_4,
|
|
xplm_joy_start_5,
|
|
xplm_joy_start_6,
|
|
xplm_joy_start_7,
|
|
xplm_joy_throt_up,
|
|
xplm_joy_throt_dn,
|
|
xplm_joy_prop_up,
|
|
xplm_joy_prop_dn,
|
|
xplm_joy_mixt_up,
|
|
xplm_joy_mixt_dn,
|
|
xplm_joy_carb_tog,
|
|
xplm_joy_carb_on,
|
|
xplm_joy_carb_off,
|
|
xplm_joy_trev,
|
|
xplm_joy_trm_up,
|
|
xplm_joy_trm_dn,
|
|
xplm_joy_rot_trm_up,
|
|
xplm_joy_rot_trm_dn,
|
|
xplm_joy_rud_lft,
|
|
xplm_joy_rud_cntr,
|
|
xplm_joy_rud_rgt,
|
|
xplm_joy_ail_lft,
|
|
xplm_joy_ail_cntr,
|
|
xplm_joy_ail_rgt,
|
|
xplm_joy_B_rud_lft,
|
|
xplm_joy_B_rud_rgt,
|
|
xplm_joy_look_up,
|
|
xplm_joy_look_dn,
|
|
xplm_joy_look_lft,
|
|
xplm_joy_look_rgt,
|
|
xplm_joy_glance_l,
|
|
xplm_joy_glance_r,
|
|
xplm_joy_v_fnh,
|
|
xplm_joy_v_fwh,
|
|
xplm_joy_v_tra,
|
|
xplm_joy_v_twr,
|
|
xplm_joy_v_run,
|
|
xplm_joy_v_cha,
|
|
xplm_joy_v_fr1,
|
|
xplm_joy_v_fr2,
|
|
xplm_joy_v_spo,
|
|
xplm_joy_flapsup,
|
|
xplm_joy_flapsdn,
|
|
xplm_joy_vctswpfwd,
|
|
xplm_joy_vctswpaft,
|
|
xplm_joy_gear_tog,
|
|
xplm_joy_gear_up,
|
|
xplm_joy_gear_down,
|
|
xplm_joy_lft_brake,
|
|
xplm_joy_rgt_brake,
|
|
xplm_joy_brakesREG,
|
|
xplm_joy_brakesMAX,
|
|
xplm_joy_speedbrake,
|
|
xplm_joy_ott_dis,
|
|
xplm_joy_ott_atr,
|
|
xplm_joy_ott_asi,
|
|
xplm_joy_ott_hdg,
|
|
xplm_joy_ott_alt,
|
|
xplm_joy_ott_vvi,
|
|
xplm_joy_tim_start,
|
|
xplm_joy_tim_reset,
|
|
xplm_joy_ecam_up,
|
|
xplm_joy_ecam_dn,
|
|
xplm_joy_fadec,
|
|
xplm_joy_yaw_damp,
|
|
xplm_joy_art_stab,
|
|
xplm_joy_chute,
|
|
xplm_joy_JATO,
|
|
xplm_joy_arrest,
|
|
xplm_joy_jettison,
|
|
xplm_joy_fuel_dump,
|
|
xplm_joy_puffsmoke,
|
|
xplm_joy_prerotate,
|
|
xplm_joy_UL_prerot,
|
|
xplm_joy_UL_collec,
|
|
xplm_joy_TOGA,
|
|
xplm_joy_shutdown,
|
|
xplm_joy_con_atc,
|
|
xplm_joy_fail_now,
|
|
xplm_joy_pause,
|
|
xplm_joy_rock_up,
|
|
xplm_joy_rock_dn,
|
|
xplm_joy_rock_lft,
|
|
xplm_joy_rock_rgt,
|
|
xplm_joy_rock_for,
|
|
xplm_joy_rock_aft,
|
|
xplm_joy_idle_hilo,
|
|
xplm_joy_lanlights,
|
|
xplm_joy_max
|
|
);
|
|
PXPLMCommandButtonID = ^XPLMCommandButtonID;
|
|
|
|
{
|
|
XPLMSimulateKeyPress
|
|
|
|
This function simulates a key being pressed for X-Plane. The keystroke goes
|
|
directly to X-Plane; it is never sent to any plug-ins. However, since this
|
|
is a raw key stroke it may be mapped by the keys file or enter text into a
|
|
field.
|
|
|
|
Deprecated: use XPLMCommandOnce
|
|
}
|
|
PROCEDURE XPLMSimulateKeyPress(
|
|
inKeyType : Integer;
|
|
inKey : Integer);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandKeyStroke
|
|
|
|
This routine simulates a command-key stroke. However, the keys are done by
|
|
function, not by actual letter, so this function works even if the user has
|
|
remapped their keyboard. Examples of things you might do with this include
|
|
pausing the simulator.
|
|
|
|
Deprecated: use XPLMCommandOnce
|
|
}
|
|
PROCEDURE XPLMCommandKeyStroke(
|
|
inKey : XPLMCommandKeyID);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandButtonPress
|
|
|
|
This function simulates any of the actions that might be taken by pressing
|
|
a joystick button. However, this lets you call the command directly rather
|
|
than have to know which button is mapped where. Important: you must release
|
|
each button you press. The APIs are separate so that you can 'hold down' a
|
|
button for a fixed amount of time.
|
|
|
|
Deprecated: use XPLMCommandBegin.
|
|
}
|
|
PROCEDURE XPLMCommandButtonPress(
|
|
inButton : XPLMCommandButtonID);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{
|
|
XPLMCommandButtonRelease
|
|
|
|
This function simulates any of the actions that might be taken by pressing
|
|
a joystick button. See XPLMCommandButtonPress.
|
|
|
|
Deprecated: use XPLMCommandEnd.
|
|
}
|
|
PROCEDURE XPLMCommandButtonRelease(
|
|
inButton : XPLMCommandButtonID);
|
|
cdecl; external XPLM_DLL;
|
|
|
|
{$ENDIF XPLM_DEPRECATED}
|
|
|
|
IMPLEMENTATION
|
|
|
|
END.
|