XPLMDisplay

This constant indicates the device we want to override or enhance. We can get a callback before or after each item.

XPLMWindowLayer describes where in the ordering of windows X-Plane should place a particular window. Windows in higher layers cover windows in lower layers. So, a given window might be at the top of its particular layer, but it might still be obscured by a window in a higher layer. (This happens frequently when floating windows, like X-Plane's map, are covered by a modal alert.) Your window's layer can only be specified when you create the window (in the XPLMCreateWindow_t you pass to XPLMCreateWindowEx()). For this reason, layering only applies to windows created with new X-Plane 11 GUI features. (Windows created using the older XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK will simply be placed in the flight overlay window layer.)

XPLMWindowDecoration describes how "modern" windows will be displayed. This impacts both how X-Plane draws your window as well as certain mouse handlers. Your window's decoration can only be specified when you create the window (in the XPLMCreateWindow_t you pass to XPLMCreateWindowEx()).

XPLMWindowContentType describes how content for this window is provided.

XPLMWindowPositionMode describes how X-Plane will position your window on the user's screen. X-Plane will maintain this positioning mode even as the user resizes their window or adds/removes full-screen monitors. Positioning mode can only be set for "modern" windows (that is, windows created using XPLMCreateWindowEx() and compiled against the XPLM300 SDK). Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK will simply get the "free" positioning mode.

Returns: XPLMAvionicsID

This routine registers your callbacks for a built-in device. This returns a handle. If the returned handle is NULL, there was a problem interpreting your input, most likely the struct size was wrong for your SDK version. If the returned handle is not NULL, your callbacks will be called according to schedule as long as your plugin is not deactivated, or unloaded, or you call XPLMUnregisterAvionicsCallbacks(). Note that you cannot register new callbacks for a device that is not a built-in one (for example a device that you have created, or a device another plugin has created).

Returns: XPLMAvionicsID

This routine registers no callbacks for a built-in cockpit device, but returns a handle which allows you to interact with it using the Avionics Device API. Use this if you do not wish to intercept drawing, clicks and touchscreen calls to a device, but want to interact with its popup programmatically. This is equivalent to calling XPLMRegisterAvionicsCallbackEx() with NULL for all callbacks.

Returns: (returns nothing)

This routine unregisters your callbacks for a built-in device. You should only call this for handles you acquired from XPLMRegisterAvionicsCallbacksEx(). They will no longer be called.

Returns: XPLMAvionicsID

Creates a new cockpit device to be used in the 3D cockpit. You can call this at any time: if an aircraft referencing your device is loaded before your plugin, the simulator will make sure to retroactively map your display into it. When you are done with the device, and at least before your plugin is unloaded, you should destroy the device using XPLMDestroyAvionics().

Returns: (returns nothing)

Destroys the cockpit device and deallocates its screen's memory. You should only ever call this for devices that you created using XPLMCreateAvionicsEx(), not X-Plane' built-ine devices you have customised.

Returns: boolean

Returns true (1) if the cockpit device with the given handle is used by the current aircraft.

Returns: (returns nothing)

Sets the brightness setting's value, between 0 and 1, for the screen of the cockpit device with the given handle. If the device is bound to the current aircraft, this is a shortcut to setting the brightness rheostat value using the sim/cockpit2/switches/instrument_brightness_ratio[] dataref; this sets the slot in the instrument_brightness_ratio array to which the device is bound. If the device is not currently bound, the device keeps track of its own screen brightness rheostat, allowing you to control the brightness even though it isn't connected to the instrument_brightness_ratio dataref.

Returns: number

Returns the brightness setting value, between 0 and 1, for the screen of the cockpit device with the given handle. If the device is bound to the current aircraft, this is a shortcut to getting the brightness rheostat value from the sim/cockpit2/switches/instrument_brightness_ratio[] dataref; this gets the slot in the instrument_brightness_ratio array to which the device is bound. If the device is not currently bound, this returns the device's own brightness rheostat value.

Returns: number

Returns the ratio of the nominal voltage (1.0 means full nominal voltage) of the electrical bus to which the given avionics device is bound, or -1 if the device is not bound to the current aircraft.

Returns: boolean, {k} with keys: x, y

Returns true (1) if the mouse is currently over the screen of cockpit device with the given handle. If they are not NULL, the optional x and y arguments are filled with the co-ordinates of the mouse cursor in device co-ordinates.

Output table keys:

Returns: (returns nothing)

Tells X-Plane that your device's screen needs to be re-drawn. If your device is marked for on-demand drawing, X-Plane will call your screen drawing callback before drawing the next simulator frame. If your device is already drawn every frame, this has no effect.

Returns: (returns nothing)

Shows or hides the popup window for a cockpit device. Visibility is independent of where the popup is drawn (in the X-Plane window, popped out as an OS window, or mapped to a VR floating window): the popup always remains in whichever target mode you most recently selected, and toggling visibility just shows or hides it there.

Returns: boolean

Returns true (1) if the popup window for a cockpit device is visible.

Returns: (returns nothing)

Pops out the window for a cockpit device, making it a first-class window in the operating system, separate from the X-Plane window. Popping out and being mapped to VR are mutually exclusive: if the device is currently mapped to VR (XPLMIsAvionicsMappedToVR() is true), calling this routine clears its VR mapping before popping out.

Returns: boolean

Returns true (1) if the popup window for a cockpit device is popped out as a first-class OS window. This is true if and only if you have most recently asked the popup to be popped out (via XPLMPopOutAvionics()) and it has not since been mapped to VR (via XPLMSetAvionicsMappedToVR()).

Returns: (returns nothing)

Maps a custom cockpit device's popup window to a VR floating window in the headset, or returns it from VR back to the X-Plane window. Pass 1 to map to VR, 0 to unmap. The VR window shows the device's bezel and screen at their intrinsic size, as supplied via XPLMCreateAvionicsEx(). Avionics in VR are not user-resizable. Mapping to VR and being popped out as an OS window are mutually exclusive: calling this with inMapped=1 on a popped-out device clears its pop-out state, and calling XPLMPopOutAvionics() on a VR-mapped device clears its VR mapping. This mirrors the relationship between xplm_WindowPopOut and xplm_WindowVR for XPLMWindow. VR mapping is independent of popup visibility (XPLMSetAvionicsPopupVisible). Mapping a hidden popup to VR leaves it hidden until you make it visible. Has no effect (and logs a warning) if VR is not currently running on the headset, or if the device was not created via XPLMCreateAvionicsEx() (built-in avionics cannot be VR-mapped).

Returns: boolean

Returns true (1) if the popup window for a cockpit device is currently mapped to a VR floating window. This is true if and only if you have most recently asked the device to be mapped to VR (via XPLMSetAvionicsMappedToVR()) and it has not since been unmapped, popped out, or had VR shut down beneath it.

Returns: (returns nothing)

This routine gives keyboard focus to the popup window of a custom cockpit device, if it is visible.

Returns: boolean

Returns true (1) if the popup window for a cockpit device has keyboard focus.

Returns: {k} with keys: left, top, right, bottom

Returns the bounds of a cockpit device's popup window in the X-Plane coordinate system.

Output table keys:

Returns: (returns nothing)

Sets the size and position of a cockpit device's popup window in the X-Plane coordinate system.

Returns: {k} with keys: left, top, right, bottom

Returns the bounds of a cockpit device's popped-out window.

Output table keys:

Returns: (returns nothing)

Sets the size and position of a cockpit device's popped-out window.

Returns: XPLMWindowID

This routine creates a new "modern" window. You pass in an XPLMCreateWindow_t structure with all of the fields set in. You must set the structSize of the structure to the size of the actual structure you used. Also, you must provide functions for every callback---you may not leave them null! (If you do not support the cursor or mouse wheel, use functions that return the default values.)

Returns: (returns nothing)

This routine destroys a window. The window's callbacks are not called after this call. Keyboard focus is removed from the window before destroying it.

Returns: (returns nothing)

Loads a URL into a browser-content-type window. Safe to call before the underlying webview has finished initialising; the load is queued and applied as soon as the browser is ready, so plugins may call this immediately after XPLMCreateWindowEx. Subsequent calls replace the pending or current page.

Returns: (returns nothing)

Reloads the current URL in a browser-content-type window. Pass true for inIgnoreCache to bypass the HTTP cache (the equivalent of a shift-reload).

Returns: (returns nothing)

Executes a JavaScript snippet in the browser window's main frame. The script is run once; it has access to the same xplane.* namespace exposed to the page itself (so it can call functions registered via XPLMWindowAddBrowserFunction). If injected before the page has finished loading, the script may run against an empty document.

Returns: (returns nothing)

Registers a callback that the page running in this browser window can invoke as xplane.<inName>(arg). The JS call returns a Promise that resolves to the value your XPLMBrowserCallback_f returns (parsed as JSON -- see that callback's desc for the contract). Multiple registrations against the same name on the same window overwrite each other. Each window has its own independent xplane.* namespace; functions registered on window A are not callable from window B.

Returns: {k} with keys: width, height

This routine returns the size of the main X-Plane OpenGL window in pixels. This number can be used to get a rough idea of the amount of detail the user will be able to see when drawing in 3-d.

Output table keys:

Returns: {k} with keys: left, top, right, bottom

This routine returns the bounds of the "global" X-Plane desktop, in boxels. Unlike the non-global version XPLMGetScreenSize(), this is multi-monitor aware. There are three primary consequences of multimonitor awareness. First, if the user is running X-Plane in full-screen on two or more monitors (typically configured using one full-screen window per monitor), the global desktop will be sized to include all X-Plane windows. Second, the origin of the screen coordinates is not guaranteed to be (0, 0). Suppose the user has two displays side-by-side, both running at 1080p. Suppose further that they've configured their OS to make the left display their "primary" monitor, and that X-Plane is running in full-screen on their right monitor only. In this case, the global desktop bounds would be the rectangle from (1920, 0) to (3840, 1080). If the user later asked X-Plane to draw on their primary monitor as well, the bounds would change to (0, 0) to (3840, 1080). Finally, if the usable area of the virtual desktop is not a perfect rectangle (for instance, because the monitors have different resolutions or because one monitor is configured in the operating system to be above and to the right of the other), the global desktop will include any wasted space. Thus, if you have two 1080p monitors, and monitor 2 is configured to have its bottom left touch monitor 1's upper right, your global desktop area would be the rectangle from (0, 0) to (3840, 2160). Note that popped-out windows (windows drawn in their own operating system windows, rather than "floating" within X-Plane) are not included in these bounds.

Output table keys:

Returns: (returns nothing)

This routine immediately calls you back with the bounds (in boxels) of each full-screen X-Plane window within the X-Plane global desktop space. Note that if a monitor is not covered by an X-Plane window, you cannot get its bounds this way. Likewise, monitors with only an X-Plane window (not in full-screen mode) will not be included. If X-Plane is running in full-screen and your monitors are of the same size and configured contiguously in the OS, then the combined global bounds of all full-screen monitors will match the total global desktop bounds, as returned by XPLMGetScreenBoundsGlobal(). (Of course, if X-Plane is running in windowed mode, this will not be the case. Likewise, if you have differently sized monitors, the global desktop space will include wasted space.) Note that this function's monitor indices match those provided by XPLMGetAllMonitorBoundsOS(), but the coordinates are different (since the X-Plane global desktop may not match the operating system's global desktop, and one X-Plane boxel may be larger than one pixel due to 150% or 200% scaling).

Returns: (returns nothing)

This routine immediately calls you back with the bounds (in pixels) of each monitor within the operating system's global desktop space. Note that unlike XPLMGetAllMonitorBoundsGlobal(), this may include monitors that have no X-Plane window on them. Note that this function's monitor indices match those provided by XPLMGetAllMonitorBoundsGlobal(), but the coordinates are different (since the X-Plane global desktop may not match the operating system's global desktop, and one X-Plane boxel may be larger than one pixel).

Returns: {k} with keys: x, y

Returns the current mouse location in global desktop boxels. Unlike XPLMGetMouseLocation(), the bottom left of the main X-Plane window is not guaranteed to be (0, 0)---instead, the origin is the lower left of the entire global desktop space. In addition, this routine gives the real mouse location when the mouse goes to X-Plane windows other than the primary display. Thus, it can be used with both pop-out windows and secondary monitors. This is the mouse location function to use with modern windows (i.e., those created by XPLMCreateWindowEx()). Pass NULL to not receive info about either parameter.

Output table keys:

Returns: {k} with keys: left, top, right, bottom

This routine returns the position and size of a window. The units and coordinate system vary depending on the type of window you have. If this is a legacy window (one compiled against a pre-XPLM300 version of the SDK, or an XPLM300 window that was not created using XPLMCreateWindowEx()), the units are pixels relative to the main X-Plane display. If, on the other hand, this is a new X-Plane 11-style window (compiled against the XPLM300 SDK and created using XPLMCreateWindowEx()), the units are global desktop boxels. Pass NULL to not receive any paramter.

Output table keys:

Returns: (returns nothing)

This routine allows you to set the position and size of a window. The units and coordinate system match those of XPLMGetWindowGeometry(). That is, modern windows use global desktop boxel coordinates, while legacy windows use pixels relative to the main X-Plane display. Note that this only applies to "floating" windows (that is, windows that are drawn within the X-Plane simulation windows, rather than being "popped out" into their own first-class operating system windows). To set the position of windows whose positioning mode is xplm_WindowPopOut, you'll need to instead use XPLMSetWindowGeometryOS().

Returns: {k} with keys: left, top, right, bottom

This routine returns the position and size of a "popped out" window (i.e., a window whose positioning mode is xplm_WindowPopOut), in operating system pixels. Pass NULL to not receive any parameter.

Output table keys:

Returns: (returns nothing)

This routine allows you to set the position and size, in operating system pixel coordinates, of a popped out window (that is, a window whose positioning mode is xplm_WindowPopOut, which exists outside the X-Plane simulation window, in its own first-class operating system window). Note that you are responsible for ensuring both that your window is popped out (using XPLMWindowIsPoppedOut()) and that a monitor really exists at the OS coordinates you provide (using XPLMGetAllMonitorBoundsOS()).

Returns: {k} with keys: widthBoxels, heightBoxels

Returns the width and height, in boxels, of a window in VR. Note that you are responsible for ensuring your window is in VR (using XPLMWindowIsInVR()).

Output table keys:

Returns: (returns nothing)

This routine allows you to set the size, in boxels, of a window in VR (that is, a window whose positioning mode is xplm_WindowVR). Note that you are responsible for ensuring your window is in VR (using XPLMWindowIsInVR()).

Returns: boolean

Returns true (1) if the specified window is visible.

Returns: (returns nothing)

This routine shows or hides a window.

Returns: boolean

True if this window has been popped out (making it a first-class window in the operating system), which in turn is true if and only if you have set the window's positioning mode to xplm_WindowPopOut. Only applies to modern windows. (Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK cannot be popped out.)

Returns: boolean

True if this window has been moved to the virtual reality (VR) headset, which in turn is true if and only if you have set the window's positioning mode to xplm_WindowVR. Only applies to modern windows. (Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM301 version of the SDK cannot be moved to VR.)

Returns: (returns nothing)

A window's "gravity" controls how the window shifts as the whole X-Plane window resizes. A gravity of 1 means the window maintains its positioning relative to the right or top edges, 0 the left/bottom, and 0.5 keeps it centered. Default gravity is (0, 1, 0, 1), meaning your window will maintain its position relative to the top left and will not change size as its containing window grows. If you wanted, say, a window that sticks to the top of the screen (with a constant height), but which grows to take the full width of the window, you would pass (0, 1, 1, 1). Because your left and right edges would maintain their positioning relative to their respective edges of the screen, the whole width of your window would change with the X-Plane window. Only applies to modern windows. (Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK will simply get the default gravity.)

Returns: (returns nothing)

Sets the minimum and maximum size of the client rectangle of the given window. (That is, it does not include any window styling that you might have asked X-Plane to apply on your behalf.) All resizing operations are constrained to these sizes. Only applies to modern windows. (Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK will have no minimum or maximum size.)

Returns: (returns nothing)

Sets the policy for how X-Plane will position your window. Some positioning modes apply to a particular monitor. For those modes, you can pass a negative monitor index to position the window on the main X-Plane monitor (the screen with the X-Plane menu bar at the top). Or, if you have a specific monitor you want to position your window on, you can pass a real monitor index as received from, e.g., XPLMGetAllMonitorBoundsOS(). Only applies to modern windows. (Windows created using the deprecated XPLMCreateWindow(), or windows compiled against a pre-XPLM300 version of the SDK will always use xplm_WindowPositionFree.)

Returns: (returns nothing)

Sets the name for a window. This only applies to windows that opted-in to styling as an X-Plane 11 floating window (i.e., with styling mode xplm_WindowDecorationRoundRectangle) when they were created using XPLMCreateWindowEx().

Returns: userdata

Returns a window's reference constant, the unique value you can use for your own purposes.

Returns: (returns nothing)

Sets a window's reference constant. Use this to pass data to yourself in the callbacks.

Returns: (returns nothing)

This routine gives a specific window keyboard focus. Keystrokes will be sent to that window. Pass a window ID of 0 to remove keyboard focus from any plugin-created windows and instead pass keyboard strokes directly to X-Plane.

Returns: boolean

Returns true (1) if the indicated window has keyboard focus. Pass a window ID of 0 to see if no plugin window has focus, and all keystrokes will go directly to X-Plane.

Returns: (returns nothing)

This routine brings the window to the front of the Z-order for its layer. Windows are brought to the front automatically when they are created. Beyond that, you should make sure you are front before handling mouse clicks. Note that this only brings your window to the front of its layer (XPLMWindowLayer). Thus, if you have a window in the floating window layer (xplm_WindowLayerFloatingWindows), but there is a modal window (in layer xplm_WindowLayerModal) above you, you would still not be the true frontmost window after calling this. (After all, the window layers are strictly ordered, and no window in a lower layer can ever be above any window in a higher one.)

Returns: boolean

This routine returns true if the window you passed in is the frontmost visible window in its layer (XPLMWindowLayer). Thus, if you have a window at the front of the floating window layer (xplm_WindowLayerFloatingWindows), this will return true even if there is a modal window (in layer xplm_WindowLayerModal) above you. (Not to worry, though: in such a case, X-Plane will not pass clicks or keyboard input down to your layer until the window above stops "eating" the input.) Note that legacy windows are always placed in layer xplm_WindowLayerFlightOverlay, while modern-style windows default to xplm_WindowLayerFloatingWindows. This means it's perfectly consistent to have two different plugin-created windows (one legacy, one modern) both be in the front (of their different layers!) at the same time.