=============== LIBRARY RULES =============== From library maintainers: - Use XPLM prefix for all X-Plane API functions - Include proper error handling for all API calls - Reference official X-Plane documentation for latest updates - Use appropriate data types as defined in XPLM headers - Follow X-Plane SDK naming conventions for plugins - Include function signatures with parameter descriptions - Provide code examples for complex API usage - Document callback function requirements and signatures - Include version compatibility information for API functions - Reference related API functions in cross-references - Use proper C/C++ syntax in code examples - Include error codes and their meanings - Document thread safety considerations for API calls - Provide performance considerations for resource-intensive operations - Include platform-specific implementation notes where applicable ### Get FMOD Studio System Handle Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-sound.md Retrieves a pointer to the FMOD Studio system, allowing direct interaction with FMOD for advanced audio operations like loading banks or processing. It always returns the environment output's FMOD::Studio instance; specific headset output can be targeted via radio-specific channel groups. ```cpp XPLM_API FMOD_STUDIO_SYSTEM* XPLMGetFMODStudio(void); ``` -------------------------------- ### Define X-Plane Joystick Button Commands (XPLMCommandButtonID) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md Defines an enumeration of all possible actions that can be assigned to a joystick button in X-Plane. These IDs are stable and correspond to the equipment setup dialog, providing a consistent way to reference various in-sim commands. ```cpp enum { 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 }; typedef int XPLMCommandButtonID; ``` -------------------------------- ### Get Navaid Information (XPLMGetNavAidInfo) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-navigation.md Retrieves detailed information about a navigation aid (navaid) given its reference. Any non-null output pointers will be populated with available data. Frequencies are provided according to the nav.dat convention. Buffers for IDs and names should be adequately sized (e.g., 32 chars for IDs, 256 for names). The `outReg` parameter indicates if the navaid is within the locally loaded DSF region. ```APIDOC XPLM_API void XPLMGetNavAidInfo( XPLMNavRef inRef, XPLMNavType * outType, /* Can be NULL */ float * outLatitude, /* Can be NULL */ float * outLongitude, /* Can be NULL */ float * outHeight, /* Can be NULL */ int * outFrequency, /* Can be NULL */ float * outHeading, /* Can be NULL */ char * outID, /* Can be NULL */ char * outName, /* Can be NULL */ char * outReg /* Can be NULL */ ) Parameters: inRef: The reference to the navaid. outType: (Optional) Pointer to receive the navaid type. outLatitude: (Optional) Pointer to receive the navaid's latitude. outLongitude: (Optional) Pointer to receive the navaid's longitude. outHeight: (Optional) Pointer to receive the navaid's height. outFrequency: (Optional) Pointer to receive the navaid's frequency (nav.dat convention). outHeading: (Optional) Pointer to receive the navaid's heading. outID: (Optional) Pointer to a char buffer (min 6 chars, recommend 32) to receive the navaid's ID. outName: (Optional) Pointer to a char buffer (min 41 chars, recommend 256) to receive the navaid's name. outReg: (Optional) Pointer to a single byte (1 for true, 0 for false) indicating if the navaid is in the local loaded DSF region. Returns: void ``` -------------------------------- ### X-Plane SDK Widget API Reference Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md Detailed reference for the X-Plane SDK Widget API, including functions for widget creation, manipulation, layout management, and behavior modification. ```APIDOC XPUCreateWidgets: WIDGET_API void XPUCreateWidgets( const XPWidgetCreate_t * inWidgetDefs, int inCount, XPWidgetID inParamParent, XPWidgetID * ioWidgets); - Description: Creates a series of widgets from a table of widget creation structures. - Parameters: - inWidgetDefs: Array of widget creation structures. - inCount: Number of widget definitions. - inParamParent: Optional parent widget ID for PARAM_PARENT references. - ioWidgets: Array to receive the IDs of the created widgets. - Notes: Supports nested widget structures; allows embedding in existing widgets. XPUMoveWidgetBy: WIDGET_API void XPUMoveWidgetBy( XPWidgetID inWidget, int inDeltaX, int inDeltaY); - Description: Moves a specified X-Plane widget by a given delta in X and Y coordinates without resizing it. - Parameters: - inWidget: The ID of the widget to move. - inDeltaX: Horizontal movement offset (+x = right). - inDeltaY: Vertical movement offset (+y = up). XPUFixedLayout: WIDGET_API int XPUFixedLayout( XPWidgetMessage inMessage, XPWidgetID inWidget, intptr_t inParam1, intptr_t inParam2); - Description: Widget behavior function that maintains children's fixed positions relative to the parent during resizing. - Parameters: - inMessage: The widget message. - inWidget: The widget ID. - inParam1: Message-specific parameter 1. - inParam2: Message-specific parameter 2. - Usage: Typically used on top-level 'window' widgets. XPUSelectIfNeeded: WIDGET_API int XPUSelectIfNeeded( XPWidgetMessage inMessage, XPWidgetID inWidget, intptr_t inParam1, intptr_t inParam2, int inEatClick); - Description: Widget behavior function that brings the widget's window to the foreground if not already. - Parameters: - inMessage: The widget message. - inWidget: The widget ID. - inParam1: Message-specific parameter 1. - inParam2: Message-specific parameter 2. - inEatClick: Specifies if background clicks should be consumed. XPUDefocusKeyboard: WIDGET_API int XPUDefocusKeyboard( XPWidgetMessage inMessage, XPWidgetID inWidget, intptr_t inParam1, intptr_t inParam2, int inEatClick); - Description: Widget behavior function that sends keyboard focus back to X-Plane, stopping text field editing. - Parameters: - inMessage: The widget message. - inWidget: The widget ID. - inParam1: Message-specific parameter 1. - inParam2: Message-specific parameter 2. - inEatClick: (Parameter from signature, not explicitly described in text for this function) XPUDragWidget: WIDGET_API int XPUDragWidget( XPWidgetMessage inMessage, XPWidgetID inWidget, intptr_t inParam1, intptr_t inParam2, int inLeft, int inTop, int inRight, int inBottom); - Description: Widget behavior function that enables dragging in response to mouse clicks. - Parameters: - inMessage: The widget message. - inWidget: The widget ID. - inParam1: Message-specific parameter 1. - inParam2: Message-specific parameter 2. - inLeft: Global X coordinate of the drag region's left edge. - inTop: Global Y coordinate of the drag region's top edge. - inRight: Global X coordinate of the drag region's right edge. - inBottom: Global Y coordinate of the drag region's bottom edge. - Usage: Pass event and global coordinates of the drag region (can be a sub-region like a title bar). ``` -------------------------------- ### Get Simulation Cycle Number (C++) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/modules/other-apis.md Returns an integer counter that increments with each simulation cycle computed or video frame rendered by X-Plane. The counter starts from zero and provides a way to track the progression of the simulation. ```cpp XPLM_API int XPLMGetCycleNumber(void); ``` -------------------------------- ### X-Plane SDK Widget API Reference Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md Comprehensive documentation for the X-Plane SDK Widget API, including functions for widget creation, manipulation, and related data structures and type definitions. ```APIDOC XPUCreateWidgets: Signature: WIDGET_API void XPUCreateWidgets(const XPWidgetCreate_t * inWidgetDefs, int inCount, XPWidgetID inParamParent, XPWidgetID * ioWidgets); Description: Creates a series of widgets from an array of XPWidgetCreate_t structures. Allows for nested widget structures by specifying parent indices or a global parent. Widgets are returned in ioWidgets. Parameters: inWidgetDefs: Pointer to an array of XPWidgetCreate_t structures defining the widgets to create. inCount: The number of widget definitions in the inWidgetDefs array. inParamParent: An XPWidgetID that serves as the parent for widgets whose containerIndex is PARAM_PARENT. ioWidgets: Pointer to an array of XPWidgetID where the IDs of the newly created widgets will be stored. Returns: void XPUDragWidget: Signature: WIDGET_API int XPUDragWidget(XPWidgetMessage inMessage, XPWidgetID inWidget, intptr_t inParam1, intptr_t inParam2, int inLeft, int inTop, int inRight, int inBottom); Description: Handles dragging of a widget in response to mouse events. The drag region can be a sub-region of the widget, defined by global coordinates. Parameters: inMessage: The widget message that triggered the drag operation. inWidget: The ID of the widget to be dragged. inParam1: Message-specific parameter 1. inParam2: Message-specific parameter 2. inLeft: Global X coordinate of the left edge of the draggable region. inTop: Global Y coordinate of the top edge of the draggable region. inRight: Global X coordinate of the right edge of the draggable region. inBottom: Global Y coordinate of the bottom edge of the draggable region. Returns: int (non-zero if the message was handled, zero otherwise) XPUMoveWidgetBy: Signature: WIDGET_API void XPUMoveWidgetBy(XPWidgetID inWidget, int inDeltaX, int inDeltaY); Description: Moves a widget by a specified amount relative to its current position without resizing it. Parameters: inWidget: The ID of the widget to move. inDeltaX: The horizontal displacement. Positive moves right. inDeltaY: The vertical displacement. Positive moves up. Returns: void XPWidgetClass: Signature: typedef int XPWidgetClass; Description: Defines predefined widget types. A widget class specifies the underlying library function to be used for the widget. Type: int XPWidgetCreate_t: Signature: typedef struct { int left; int top; int right; int bottom; int visible; const char * descriptor; int isRoot; int containerIndex; XPWidgetClass widgetClass; } XPWidgetCreate_t; Description: Structure containing all parameters needed to create a single widget. Used with XPUCreateWidgets for bulk creation. Fields: left: The left coordinate of the widget's bounding box. top: The top coordinate of the widget's bounding box. right: The right coordinate of the widget's bounding box. bottom: The bottom coordinate of the widget's bounding box. visible: A boolean indicating if the widget is initially visible. descriptor: A C-style string for the widget's descriptive text. isRoot: A boolean indicating if this widget is a root widget in a tree. containerIndex: The index of the parent widget in the XPUCreateWidgets array, or NO_PARENT, or PARAM_PARENT. widgetClass: The XPWidgetClass defining the type of widget to create. XPWidgetID: Signature: typedef void * XPWidgetID; Description: An opaque, unique, non-zero handle identifying a widget. Use 0 to specify "no widget". This type is wide enough to hold a pointer. Type: void * ``` -------------------------------- ### Get Elapsed Simulation Time in X-Plane SDK Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/modules/other-apis.md This function returns the total elapsed time in seconds since the X-Plane simulator started. It's a wall clock timer, meaning it continues counting even if the simulation is paused. Developers should be aware of its precision limitations and avoid using it for time-critical applications. ```cpp XPLM_API float XPLMGetElapsedTime(void); ``` ```APIDOC XPLMGetElapsedTime() - Description: Returns the elapsed time since the sim started up in decimal seconds. This is a wall timer; it keeps counting upward even if the sim is pasued. - Returns: The elapsed time in decimal seconds (float). - Warning: This is not a very good timer! It lacks precision in both its data type and its source. Do not attempt to use it for timing critical applications like network multiplayer. ``` -------------------------------- ### X-Plane Object Loading API Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-instance.md Provides functions for loading X-Plane OBJ files, both synchronously and asynchronously. Synchronous loading returns a handle immediately, while asynchronous loading uses a callback for completion. Proper handling of object references and paths is crucial to avoid leaks and ensure correct loading. ```APIDOC XPLMLoadObject(const char * inPath) -> XPLMObjectRef - Loads an OBJ file and returns a handle to it. - If X-Plane has already loaded the object, the handle to the existing object is returned. - Do not assume you will get the same handle back twice, but do make sure to call unload once for every load to avoid “leaking” objects. - The object will be purged from memory when no plugins and no scenery are using it. - Parameters: - inPath: The path for the object, relative to the X-System base folder. Prepend './' for root folder paths (discouraged). - Returns: An XPLMObjectRef handle, or NULL if the object cannot be loaded (not found or misformatted). - Important: Datarefs an object uses for animation must be registered before loading the object; defer loading until sim fully started if necessary. XPLMLoadObjectAsync(const char * inPath, XPLMObjectLoaded_f inCallback, void * inRefcon) -> void - Loads an object asynchronously; control is returned immediately while X-Plane loads. - The sim will not stop flying while the object loads. - A callback function ('inCallback') is called once the load has completed. - If the object cannot be loaded, the callback function will be called with a NULL object handle. - There is no way to cancel an asynchronous object load; you must wait for the load to complete and then release the object if no longer desired. - Parameters: - inPath: The path for the object, relative to the X-System base folder. - inCallback: A callback function of type XPLMObjectLoaded_f to be called upon load completion. - inRefcon: A user-defined reference context passed to the callback function. ``` -------------------------------- ### Get Global Screen Bounds in X-Plane SDK (C++) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-display.md This routine returns the bounds of the global X-Plane desktop in boxels, accounting for multi-monitor setups. Unlike XPLMGetScreenSize, it is multi-monitor aware, potentially resulting in non-zero origins and including wasted space for non-rectangular virtual desktops. Note that popped-out windows are not included in these bounds. ```cpp XPLM_API void XPLMGetScreenBoundsGlobal( int * outLeft, /* Can be NULL */ int * outTop, /* Can be NULL */ int * outRight, /* Can be NULL */ int * outBottom); /* Can be NULL */ ``` -------------------------------- ### XPLM Instance Management API Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-instance.md This section documents the core functions and types for creating, managing, and destroying X-Plane instances. Instances allow for efficient, instanced drawing of .obj files by centralizing dataref manipulation, improving simulator performance. ```APIDOC XPLMInstanceRef: typedef void * XPLMInstanceRef; - An opaque handle to an instance. XPLMCreateInstance: XPLM_API XPLMInstanceRef XPLMCreateInstance( XPLMObjectRef obj, const char ** datarefs); - Creates a new instance, managed by your plug-in, and returns a handle to the instance. - Requirements: - The object passed in (obj) must be fully loaded and returned from the XPLM before instance creation; cannot pass null obj ref, nor change the ref later. - If custom datarefs are used, they must be registered before the object is loaded, even if their data will be provided via the instance dataref list. - The instance dataref array (datarefs) must be a valid pointer to a null-terminated array. If no datarefs are desired, pass a pointer to a one-element array containing a null item. Cannot pass null for the array itself. XPLMDestroyInstance: XPLM_API void XPLMDestroyInstance( XPLMInstanceRef instance); - Destroys and deallocates your instance. - Note: Once called, you are still responsible for releasing the OBJ ref. - Tip: You can release your OBJ ref after calling XPLMCreateInstance as long as you never use it again; the instance will maintain its own reference to the OBJ, and the object will be deallocated when the instance is destroyed. ``` -------------------------------- ### Install Error Reporting Callback in X-Plane SDK (C++) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-processing.md Installs an error-reporting callback for an X-Plane plugin. This function activates error checking code to identify programming mistakes like bad API parameters. It's intended for debug sections to break into the debugger on illegal calls and should not be used in shipping plugins due to potential performance impact. ```cpp XPLM_API void XPLMSetErrorCallback( XPLMError_f inCallback); ``` -------------------------------- ### X-Plane Camera Control API Reference Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-camera.md Comprehensive documentation for X-Plane SDK functions, structures, and enumerations related to camera control, allowing plugins to manage the simulator's camera position and behavior. ```APIDOC XPLMCameraControlDuration Enumeration: Description: Defines how long a plugin wishes to retain control of the camera. Values: xplm_ControlCameraUntilViewChanges (Value: "1"): Description: Control the camera until the user picks a new view. xplm_ControlCameraForever (Value: "2"): Description: Control the camera until your plugin is disabled or another plugin forcibly takes control. XPLMCameraControl_f Callback Function Type: Signature: typedef int (* XPLMCameraControl_f)(XPLMCameraPosition_t * outCameraPosition, int inIsLosingControl, void * inRefcon); Description: A callback function type used for continuous camera control. It is invoked by X-Plane to allow a plugin to provide updated camera positions or surrender control. Parameters: outCameraPosition: XPLMCameraPosition_t * (Can be NULL). Description: Pointer to a structure to fill with the new camera position. Modify it and return 1 to reposition the camera. inIsLosingControl: int. Description: Set to 1 if X-Plane is taking camera control away from the plugin, in which case outCameraPosition will be NULL. inRefcon: void *. Description: A user-defined reference constant passed during XPLMControlCamera. Returns: int. Description: Returns 1 to reposition the camera, or 0 to surrender control. Notes: If X-Plane takes control away, this function is called with inIsLosingControl set to 1 and outCameraPosition NULL. XPLMCameraPosition_t Structure: Signature: typedef struct { float x; float y; float z; float pitch; float heading; float roll; float zoom; } XPLMCameraPosition_t; Description: A structure containing a full specification of the camera's position and orientation in OpenGL coordinates. Fields: x, y, z: float. Description: Camera’s position in OpenGL coordinates. pitch: float. Description: Rotation in degrees. Positive pitch means nose up. heading: float. Description: Rotation in degrees. Positive yaw (heading) means yaw right. roll: float. Description: Rotation in degrees. Positive roll means roll right. zoom: float. Description: A zoom factor (1.0 for normal, 2.0 for 2x magnification). XPLMControlCamera Function: Signature: XPLM_API void XPLMControlCamera(XPLMCameraControlDuration inHowLong, XPLMCameraControl_f inControlFunc, void * inRefcon); Description: Initiates continuous camera control by a plugin, registering a callback function to update the camera's position on subsequent drawing cycles. Parameters: inHowLong: XPLMCameraControlDuration. Description: Specifies how long the plugin wishes to retain camera control. inControlFunc: XPLMCameraControl_f. Description: A non-null callback function that will be called to update the camera position. inRefcon: void *. Description: A user-defined reference constant passed to inControlFunc. Notes: The camera will be repositioned on the next drawing cycle. A non-null control function must be provided. XPLMDontControlCamera Function: Signature: XPLM_API void XPLMDontControlCamera(void); Description: Relinquishes camera control from the plugin back to X-Plane. The plugin's camera control function will no longer be invoked. Notes: If the plugin had a camera control function, it will not be called with an inIsLosingControl flag. X-Plane will control the camera on the next cycle. This routine should only be used if the plugin currently possesses camera control. XPLMIsCameraBeingControlled Function: Signature: XPLM_API int XPLMIsCameraBeingControlled(XPLMCameraControlDuration * outCameraControlDuration); Description: Checks if the camera is currently under plugin control and optionally retrieves the duration for which it is being controlled. Parameters: outCameraControlDuration: XPLMCameraControlDuration * (Can be NULL). Description: If provided and the camera is controlled, the current control duration will be returned here. Returns: int. Description: Returns 1 if the camera is being controlled by a plugin, 0 otherwise. XPLMReadCameraPosition Function: Signature: XPLM_API void XPLMReadCameraPosition(XPLMCameraPosition_t * outCameraPosition); Description: Reads the current camera's position and orientation into a provided XPLMCameraPosition_t structure. Parameters: outCameraPosition: XPLMCameraPosition_t *. Description: A pointer to an XPLMCameraPosition_t structure where the current camera position will be stored. ``` -------------------------------- ### Enable/Disable Menu Item in X-Plane SDK Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-menus.md Sets whether this menu item is enabled. Items start out enabled. ```cpp XPLM_API void XPLMEnableMenuItem( XPLMMenuID inMenu, int index, int enabled); ``` -------------------------------- ### Get Total Number of Loaded X-Plane Plugins Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-plugin.md This routine returns the total number of plug-ins that are currently loaded in X-Plane, including both disabled and enabled plugins. ```cpp XPLM_API int XPLMCountPlugins(void); ``` -------------------------------- ### X-Plane SDK Widget Management API Reference Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md Comprehensive reference for the X-Plane SDK's C++ widget management functions, detailing their signatures, parameters, return values, and behavior for creating, destroying, sending messages to, positioning, and controlling the visibility of widgets. ```APIDOC XPCreateCustomWidget: WIDGET_API XPWidgetID XPCreateCustomWidget( int inLeft, int inTop, int inRight, int inBottom, int inVisible, const char * inDescriptor, int inIsRoot, XPWidgetID inContainer, XPWidgetFunc_t inCallback); - Creates a custom widget by passing a widget callback function pointer instead of a class ID. - Parameters: - inLeft, inTop, inRight, inBottom: The bounds of the new widget. - inVisible: Initial visibility state (1 for visible, 0 for hidden). - inDescriptor: A descriptive string for the widget. - inIsRoot: Set to 1 if this widget is a root widget, 0 otherwise. - inContainer: The ID of the parent widget, or 0 if it has no parent. - inCallback: A pointer to the custom widget's callback function. - Returns: The ID of the newly created widget. XPDestroyWidget: WIDGET_API void XPDestroyWidget( XPWidgetID inWidget, int inDestroyChildren); - Destroys a specified widget. - Parameters: - inWidget: The ID of the widget to destroy. - inDestroyChildren: If 1, recursively destroys all child widgets before destroying the parent; if 0, child widgets become parentless. - Returns: None. XPSendMessageToWidget: WIDGET_API int XPSendMessageToWidget( XPWidgetID inWidget, XPWidgetMessage inMessage, XPDispatchMode inMode, intptr_t inParam1, intptr_t inParam2); - Sends a message to a widget. Can be used for custom messages. - Parameters: - inWidget: The ID of the target widget. - inMessage: The message to send. - inMode: The dispatching pattern (e.g., XPDispatchMode). - inParam1, inParam2: Generic parameters for the message. - Returns: 1 if the message was handled by a widget, 0 otherwise. XPPlaceWidgetWithin: WIDGET_API void XPPlaceWidgetWithin( XPWidgetID inSubWidget, XPWidgetID inContainer); - Changes the container (parent) of a widget. Cannot be used on root widgets. - Parameters: - inSubWidget: The ID of the widget to move. - inContainer: The ID of the new parent container, or 0 to remove from any container. - Returns: None. - Note: This function does not reposition the sub-widget in global coordinates. XPCountChildWidgets: WIDGET_API int XPCountChildWidgets( XPWidgetID inWidget); - Returns the number of child widgets a given widget contains. - Parameters: - inWidget: The ID of the parent widget. - Returns: The count of child widgets. XPGetNthChildWidget: WIDGET_API XPWidgetID XPGetNthChildWidget( XPWidgetID inWidget, int inIndex); - Returns the ID of a child widget by its zero-based index. - Parameters: - inWidget: The ID of the parent widget. - inIndex: The zero-based index of the child widget. - Returns: The ID of the child widget, or 0 if the index is invalid. XPGetParentWidget: WIDGET_API XPWidgetID XPGetParentWidget( XPWidgetID inWidget); - Returns the parent widget ID of a given widget. - Parameters: - inWidget: The ID of the widget. - Returns: The ID of the parent widget, or 0 if the widget has no parent (e.g., a root widget). XPShowWidget: WIDGET_API void XPShowWidget( XPWidgetID inWidget); - Makes a widget visible if it is not already. - Parameters: - inWidget: The ID of the widget to make visible. - Returns: None. - Note: A widget will only be visible to the user if it is part of a rooted hierarchy and all its parents are also visible. ``` -------------------------------- ### Create Modern X-Plane Window (XPLMCreateWindowEx) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-display.md This function creates a new “modern” X-Plane window, providing access to X-Plane 11 features. It requires a pointer to an `XPLMCreateWindow_t` structure, which must be fully initialized, including its `structSize` and all callback functions (none can be null). ```C++ XPLM_API XPLMWindowID XPLMCreateWindowEx( XPLMCreateWindow_t * inParams); ``` ```APIDOC XPLMCreateWindowEx(inParams) - Creates a new “modern” window. - Parameters: - inParams (XPLMCreateWindow_t *): A pointer to an XPLMCreateWindow_t structure containing all window parameters. - Requirements: - The structSize field of the XPLMCreateWindow_t structure must be set to its actual size. - All callback functions within the XPLMCreateWindow_t structure must be provided (cannot be null). If a feature is not supported (e.g., cursor or mouse wheel), use functions that return default values. - Returns: XPLMWindowID - An ID for the newly created window. ``` -------------------------------- ### Get X-Plane and XPLM Version Information Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-utilities.md Returns the revision numbers for X-Plane and the XPLM DLL, along with the host application ID. Useful for handling version-specific behaviors. ```APIDOC XPLMGetVersions: Signature: XPLM_API void XPLMGetVersions(int * outXPlaneVersion, int * outXPLMVersion, XPLMHostApplicationID * outHostID) Description: This routine returns the revision of both X-Plane and the XPLM DLL. Parameters: outXPlaneVersion: Pointer to an integer that will receive the X-Plane version (e.g., 606 for 6.06). outXPLMVersion: Pointer to an integer that will receive the XPLM DLL version (e.g., 400 for 4.00). outHostID: Pointer to an XPLMHostApplicationID that will receive the host ID of the running application. Notes: All versions are at least three-digit decimal numbers. The most common use is to special-case around X-Plane version-specific behavior. ``` -------------------------------- ### Get Magnetic Variation at Location (XPLMGetMagneticVariation) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-navigation.md Returns X-Plane’s simulated magnetic variation (declination) at the specified latitude and longitude. This value can be used for navigation calculations that require magnetic north. ```APIDOC XPLM_API float XPLMGetMagneticVariation( double latitude, double longitude ) Parameters: latitude: The latitude (in degrees) for which to get the magnetic variation. longitude: The longitude (in degrees) for which to get the magnetic variation. Returns: float (simulated magnetic variation/declination in degrees) ``` -------------------------------- ### X-Plane Widget Utility Functions and Structures Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md The XPWidgetUtils library provides functions and structures to simplify widget creation and management in the X-Plane SDK. It includes utilities for adding behaviors to widgets and defining widget creation parameters. Behavior functions can be added as callbacks or called internally within custom widget functions. ```APIDOC XPWidgetCreate_t: - Description: Structure containing parameters for bulk widget creation using XPUCreateWidgets. All parameters correspond to XPCreateWidget, except for containerIndex. - Fields: - left (int) - top (int) - right (int) - bottom (int) - visible (int) - descriptor (const char *) - isRoot (int): Whether this widget is a root widget. - containerIndex (int): The index of the widget to be contained within, or a constant (NO_PARENT, PARAM_PARENT). - widgetClass (XPWidgetClass) - Usage Notes: - If containerIndex equals a widget's index in the array passed to XPUCreateWidgets, that widget becomes the parent. - If containerIndex is NO_PARENT, the parent is NULL. - If containerIndex is PARAM_PARENT, the widget passed into XPUCreateWidgets is used as the parent. NO_PARENT: -1 - Description: Constant used for containerIndex in XPWidgetCreate_t to specify no parent widget (NULL). PARAM_PARENT: -2 - Description: Constant used for containerIndex in XPWidgetCreate_t to specify the widget passed into XPUCreateWidgets as the parent. ``` ```C typedef struct { int left; int top; int right; int bottom; int visible; const char * descriptor; // Whether this widget is a root widget int isRoot; // The index of the widget to be contained within, or a constant int containerIndex; XPWidgetClass widgetClass; } XPWidgetCreate_t; ``` ```C #define NO_PARENT -1 ``` ```C #define PARAM_PARENT -2 ``` -------------------------------- ### Get Widget Bounding Box: XPGetWidgetGeometry Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md This routine retrieves the bounding box of a widget in global coordinates. You can pass NULL for any output parameter if you are not interested in that specific coordinate. ```C++ WIDGET_API void XPGetWidgetGeometry( XPWidgetID inWidget, int * outLeft, /* Can be NULL */ int * outTop, /* Can be NULL */ int * outRight, /* Can be NULL */ int * outBottom); /* Can be NULL */ ``` -------------------------------- ### Load FMS Flight Plan from Buffer (XPLMLoadFMSFlightPlan) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-navigation.md Loads an X-Plane 11 and later formatted flight plan, including instrument procedures, from a provided buffer into the Flight Management System (FMS) or GPS. The `inDevice` parameter specifies whether to load it into the pilot-side (0) or co-pilot side (1) unit. ```APIDOC XPLM_API void XPLMLoadFMSFlightPlan( int inDevice, const char * inBuffer, unsigned int inBufferLen ) Parameters: inDevice: The device index (0 for pilot-side FMS/GPS, 1 for co-pilot side). inBuffer: A pointer to the buffer containing the X-Plane 11+ formatted flight plan. inBufferLen: The length of the flight plan buffer. Returns: void ``` -------------------------------- ### XPLM Command Execution Functions Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/modules/other-apis.md Functions for controlling the execution of X-Plane commands. XPLMCommandBegin starts a command, holding it down until XPLMCommandEnd is called. These calls must be balanced to ensure proper command lifecycle management. ```APIDOC XPLMCommandBegin(inCommand: XPLMCommandRef) Description: 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. Parameters: inCommand: XPLMCommandRef - The command reference. Returns: void XPLMCommandEnd(inCommand: XPLMCommandRef) Description: Ends the execution of a given command that was started with XPLMCommandBegin. You must not issue XPLMCommandEnd for a command you did not begin. Parameters: inCommand: XPLMCommandRef - The command reference. Returns: void ``` -------------------------------- ### Get FMOD Channel Group Reference Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-sound.md Obtains a reference to a specific FMOD channel group, representing an output channel. The `audioType` parameter specifies which audio bus to retrieve, as defined in the XPLMAudioBus enumeration. ```cpp XPLM_API FMOD_CHANNELGROUP* XPLMGetFMODChannelGroup( XPLMAudioBus audioType); ``` -------------------------------- ### Create Multiple X-Plane Widgets Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md This function creates a series of widgets from an array of widget creation structures (`XPWidgetCreate_t`). It allows for the creation of nested widget structures by specifying parent widgets by index, and can embed new widgets within pre-existing ones using a `PARAM_PARENT` reference. ```C++ WIDGET_API void XPUCreateWidgets( const XPWidgetCreate_t * inWidgetDefs, int inCount, XPWidgetID inParamParent, XPWidgetID * ioWidgets); ``` -------------------------------- ### Define X-Plane SDK Window Creation Parameters (XPLMCreateWindow_t) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-display.md This C structure defines all parameters for creating a modern X-Plane window using `XPLMCreateWindowEx()`. It supports X-Plane 11 GUI features, including high-DPI scaling via 'boxels' and global desktop coordinates. The `structSize` member must always be set to the size of the structure in bytes for SDK versioning. ```cpp typedef struct { // Used to inform XPLMCreateWindowEx() of the SDK version you compiled against; should always be set to sizeof(XPLMCreateWindow_t) int structSize; // Left bound, in global desktop boxels int left; // Top bound, in global desktop boxels int top; // Right bound, in global desktop boxels int right; // Bottom bound, in global desktop boxels int bottom; int visible; XPLMDrawWindow_f drawWindowFunc; // A callback to handle the user left-clicking within your window (or NULL to ignore left clicks) XPLMHandleMouseClick_f handleMouseClickFunc; XPLMHandleKey_f handleKeyFunc; XPLMHandleCursor_f handleCursorFunc; XPLMHandleMouseWheel_f handleMouseWheelFunc; // A reference which will be passed into each of your window callbacks. Use this to pass information to yourself as needed. void * refcon; // Specifies the type of X-Plane 11-style "wrapper" you want around your window, if any XPLMWindowDecoration decorateAsFloatingWindow; XPLMWindowLayer layer; // A callback to handle the user right-clicking within your window (or NULL to ignore right clicks) XPLMHandleMouseClick_f handleRightClickFunc; } XPLMCreateWindow_t; ``` -------------------------------- ### XPLM Plugin Discovery APIs Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-plugin.md APIs for finding and iterating through loaded X-Plane plugins. These are useful for plugins that need to locate and interact with other specific plugins, for example, an FMS plugin talking to an autopilot plugin. ```APIDOC XPLMGetMyID() - Returns the plugin ID of the calling plug-in. - Parameters: None - Returns: XPLMPluginID (The ID of the calling plugin) XPLMCountPlugins() - Returns the total number of plug-ins that are loaded, both disabled and enabled. - Parameters: None - Returns: int (Total count of loaded plugins) XPLMGetNthPlugin(int inIndex) - Returns the ID of a plug-in by index. Plugins may be returned in any arbitrary order. - Parameters: - inIndex: The 0-based index of the plugin (from 0 to XPLMCountPlugins()-1, inclusive). - Returns: XPLMPluginID (The ID of the plugin at the specified index) XPLMFindPluginByPath(const char * inPath) - Returns the plug-in ID of the plug-in whose file exists at the passed in absolute file system path. - Parameters: - inPath: The absolute file system path to the plugin. - Returns: XPLMPluginID (The ID of the plugin, or XPLM_NO_PLUGIN_ID if the path does not point to a currently loaded plug-in) XPLMFindPluginBySignature(const char * inSignature) - Returns the plug-in ID of the plug-in whose signature matches what is passed in. - Parameters: - inSignature: The unique signature string that identifies the plugin. Signatures are the best way to identify another plug-in as they are independent of file system path or human-readable name, and should be unique. - Returns: XPLMPluginID (The ID of the plugin, or XPLM_NO_PLUGIN_ID if no running plug-in has this signature) ``` -------------------------------- ### Get Main X-Plane OpenGL Window Size (C++) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-display.md This routine returns the size of the main X-Plane OpenGL window in pixels. This value provides a rough estimate of the detail the user will perceive when drawing in 3D. ```cpp XPLM_API void XPLMGetScreenSize( int * outWidth, /* Can be NULL */ int * outHeight); /* Can be NULL */ ``` -------------------------------- ### X-Plane Flight Loop Phase Definitions Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/api/xplm-instance.md Defines various phases within the X-Plane simulation flight loop where plugin callbacks can be executed. These constants specify the timing relative to the flight model integration and other simulation events. ```APIDOC xplm_FlightLoop_Phase_BeforeFlightModel - Value: "0" - Description: Your callback runs before X-Plane integrates the flight model. xplm_FlightLoop_Phase_AfterFlightModel - Value: "1" - Description: Your callback runs after X-Plane integrates the flight model. xplm_Phase_Objects - Value: "20" - Description: Deprecated as of XPLM302. Refers to 3-d objects (houses, smokestacks, etc.). ``` -------------------------------- ### Get Font Dimensions in X-Plane SDK Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/modules/other-apis.md This routine retrieves the width and height of a character for a specified font ID. It also indicates if the font is restricted to numeric digits. For proportional fonts, the width returned is an arbitrary average. ```cpp XPLM_API void XPLMGetFontDimensions( XPLMFontID inFontID, int * outCharWidth, /* Can be NULL */ int * outCharHeight, /* Can be NULL */ int * outDigitsOnly); /* Can be NULL */ ``` ```APIDOC XPLMGetFontDimensions(inFontID, outCharWidth, outCharHeight, outDigitsOnly) - Description: Returns the width and height of a character in a given font. It also tells you if the font only supports numeric digits. Pass NULL if you don’t need a given field. Note that for a proportional font the width will be an arbitrary, hopefully average width. - Parameters: - inFontID: The ID of the font. - outCharWidth: (Can be NULL) Pointer to an integer to receive the character width. - outCharHeight: (Can be NULL) Pointer to an integer to receive the character height. - outDigitsOnly: (Can be NULL) Pointer to an integer to receive 1 if the font only supports numeric digits, 0 otherwise. - Returns: void ``` -------------------------------- ### Create Custom X-Plane SDK Widget (C++) Source: https://github.com/justinwol/x-plane-sdk-documentation/blob/main/docs/widgets/widget-system.md Instantiates a new custom widget in the X-Plane SDK by providing a callback function instead of a predefined class ID. This allows for highly customized widget behavior and rendering, similar to XPCreateWidget but with a custom callback. ```cpp WIDGET_API XPWidgetID XPCreateCustomWidget( int inLeft, int inTop, int inRight, int inBottom, int inVisible, const char * inDescriptor, int inIsRoot, XPWidgetID inContainer, XPWidgetFunc_t inCallback); ```