xp

This module doesn’t actually add any new functions, but it does provide the simplified mapping of SDK functions and enumerations. I strongly suggest you use this interface as it provides a more pythonic was of doing things.

To use:

from XPPython3 import xp

To use, add from XPPython3 import xp at the top of you file, and all of the SDK API, from all modules will be available to you, with these benefits:

  • Simplified Mapping: To further reduce typing, function names and constants have been renamed (shortened) in a consistent manner.

  • Optional Arguments: Some function arguments are optional as documented in this API. This further simplifies the interface, for example:

    xp.createFlightLoop(MyCallback)

    equates to:

    xp.createFlightLoop(MyCallback, 0, None)

  • Keyword Arguments: In typical python fashion, function arguments can be specified using keywords (which makes options arguments even more useful). For example:

    xp.createFlightLoop(callback=MyCallback, refCon=None)

Simplified Mapping

This module provides simplified mappings to the original C / C++ named functions and constants. The resulting API is the same – same parameters, same return values, but you won’t be typing XPLM over-and-over.

Rules:

  • Functions are camelCase. Leading XPLM, XP, XPUI are dropped

Laminar SDK

import xp

XPLMCamera.XPLMReadCameraPosition()

xp.readCameraPosition()

XPUIGraphics.XPDrawWindow()

xp.drawWindow()

  • Constants start with Capital letter. Leading xp_, xplm_, etc. are dropped

Laminar SDK

import xp

XPLMCamera.xplm_ControlCameraForever

xp.ControlCameraForever

XPLMDisplay.xplm_MouseUp

xp.MouseUp

XPStandardWidgets.xpProperty_ButtonState

xp.Property_ButtonState

XPWidgetDefs.xpMsg_Paint

xp.Msg_Paint

XPStandardWidgets.xpMsg_TextFieldChanged

xp.Msg_TextFieldChanged

Compare:

import XPLMDataAccess
import XPLMInstance

x = XPLMDataAccess.XPLMGetDatad(XPLMDataAccess.XPLMFindDataRef('sim/flightmodel/position/local_x'))
y = XPLMDataAccess.XPLMGetDatad(XPLMDataAccess.XPLMFindDataRef('sim/flightmodel/position/local_y'))
z = XPLMDataAccess.XPLMGetDatad(XPLMDataAccess.XPLMFindDataRef('sim/flightmodel/position/local_z'))
pitch, heading, roll = (1, 2, 3)
position = (x, y, z, pitch, heading, roll)
XPLMInstance.XPLMInstanceSetPosition(self.g_instance,
                                    position,
                                    [self.g_tire, 0.0])

with:

from XPPython3 import xp
x = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_x'))
y = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_y'))
z = xp.getDatad(xp.findDataRef('sim/flightmodel/position/local_z'))
pitch, heading, roll = (1, 2, 3)
position = (x, y, z, pitch, heading, roll)
xp.instanceSetPosition(self.g_instance, position, [self.g_tire, 0.0])

Because we’re not introducing a new API, you can intermix the two calling styles. xp.py is located in Resources/plugins/XPPython3/ directory, which will be in your python path for install plugins.

Optional Arguments

Where the XPPython3 documentation specifies default parameters values, you can leave out those parameters and the function will still work.

For example, registerKeySniffer() normally takes three parameters: the callback function, a before indicator, and a reference constant. The XPPython3 specification says:

registerKeySniffer(sniffer, before=0, refCon=None)

This means if you do not specify the final two parameters, your call will get the indicated defaults:

xp.registerKeySniffer(MyCallback)

Is identical to:

xp.registerKeySniffer(MyCallback, 0, None)

Keyword Arguments

Keyword arguments free you from a particular order of parameters, and increases the readability of code:

myRefCon = {'data': 'xxx'}
xp.registerKeySniffer(MyCallback, refCon=myRefCon)

Is identical to:

myRefCon = {'data': 'xxx'}
xp.registerKeySniffer(MyCallback, 0, myRefCon)

This is especially useful for functions such as createWindowEx(), where we provide a lot of default parameters, so you can create a window with just:

xp.createWindowEx(draw=MyDraw)

instead of:

xp.createWindowEx(100, 200, 200, 100, 0,
    xp.WindowDecorationRoundRectangle, xp.WindowLayerFloatingWindows,
    MyDraw,
    DummyClickCallback,
    DummyKeyCallback,
    DummyCursorCallback,
    DummyWheelCallback,
    DummyRightClickCallback,
    None)