Demo Plugin

This is a basic plugin, that demonstrates the mandatory API’s that a plugin MUST support.

Note that the class that implements the plugin, derives from an OpenCPN plugin base class. Over successive versions of OpenCPN new functions and members have been added to the base classes. The plugin need only inherit from a base class that provides the API’s required for the plugin’s desired capabilites.

For example, a plugin that is derived from the OpenCPN Plugin API version 1.17 base class uses the following constructor.

The mandatory API’s that all plugins must implement

These two API’s indicate what version of the OpenCPN API’s are supported

Eg. if the plugin is derived from OpenCPN Plugin API 1.17, the major version number is 1 and the minor version number is 17

These three API’s indicate the version number of the plugin

Eg. If the plugin version is 1.2.3, the major version is 1, the minor version is 2 and the patch version is 3.

This returns the name of the plugin and is displayed in the Plugin Manager

The following two API’s return a long and short description, both of which are displayed in the Plugin Manager

This API returns the icon for the plugin which is displayed in the Plugin Manager. It should be a 32 x 32 pixel bitmap.

In addition the plugin dumps some of the OpenCPN standard folder paths and user’s measurement units into the OpenCPN log file using wxLogMessage. This OpenCPN log is the preferred mechanism for plugins to log messages. Eg.

To log important error messages, you can also us wxLogError.

In addition the plugin dumps some of the OpenCPN standard folder paths and user’s measurement units into the OpenCPN log file using wxLogMessage. This OpenCPN log is the preferred mechanism for plugins to log messages. To log important error messages, you can also use wxLogError.

OpenCPN and plugins persist configuration settings using the wxWidgets file based configuration class. This allows settings to be persisted in a standard ini file format.

Settings can saved using code similar to:

Upon plugin installation and enabling, an OpenCPN Callback API SetDefaults can be implemented to allow the plugin to perform its initial configuration. In this example, a wxWizard dialog is displayed to allow the users to configure the plugin’s settings. However developers are free to implement any UI they wish, or in fact not display any UI, rather just adopt some default values.

There are two mechanisms that may be used to display an interface to allow users to configure the plugin. The first mechanism adds a notebook page to any of the notebook tabs (Display, Charts, Ship, User) in the OpenCPN Toolbox. This requires the INSTALL_TOOLBOX_PAGE value to be returned in the Init function and the OnSetupOptions function to be overridden

The second mechanism is for the plugin to provide its own dialog which is displayed from the plugin’s preference option. This requires the WANTS_PREFERENCES value to be returned in the Init function and the ShowPreferencesDialog function to be overridden.

One method that a plugin may solicit input from a user is via context menu items. The plugin may add its own context menu items to the root context menu which will be displayed when the user right clicks on the OpenCPN Canvas.

Context Menu items are added using code similar to:

When the context menu item is selected, the plugin handles the callback, checking that the context menu item id matches and performs whatever functions the plugin requires. In this example just a message box is displayed.

Context Menu Items may also be added to the Sub Menus for AIS, Routes, Waypoints and Tracks. This is only supported when using OpenCPN API level 1.20 or higher. An example of adding a context menu item to the AIS sub menu is shown below.

Again plugins may perform any function that is required, in this case just displaying a message box with some details about the selected AIS target. Also note that some OpenCPN helper API’s are used to format the latitude and longitude which are stored internally by OpenCPN as doubles, into human readable strings.

Plugins may install a toolbar button to allow different tasks to be performed. Firstly create your toolbar button icons as Scaled Vector Graphics (.SVG) files. Create three icons to represent the normal (untoggled) state, toggled state and rollover state (although for some reason OpenCPN does not process a rollover event).

The following code is used to create the toolbar button:

Note to also add the value INSTALLS_TOOLBAR_BUTTON to the return value of the Init function The toolbar button will then be displayed.

To handle the toolbar button press, code similar to the following is invoked by the callback.

In this example the plugin only displays a message box. Note that the state of the button is toggled while the message box is displayed using the SetToolbarItemState function.

OpenCPN provides plugins with navigation data; Speed Over Ground (SOG), Course Over Ground (COG), Heading (True and Magnetic), Latitude and Longitude once per second.

There are two mechanisms for receiving this data.

Plugins register their subscribers during initialization and implement an appropriate handler.

Remember to ensure the plugin class inherits from the wxWidgets wxEvtHandler class.

When the handler is invoked, plugins retrieve the event payload and parse as appropriate.

OpenCPN messaging is a mechanism that allows both OpenCPN to communicate with Plugins and for plugins to communicate with one another. Messages are identified with a message id and the data is usually formatted using Java Script Object Notation (JSON).

Some of the well known OpenCPN Messages include:

Similar to NMEA 0183, there are two ways to receive and to generate an OpenCPN message; the old mechanism using a Callback API SetPluginMessage to receive messages and the API SendPluginMessage transmit a message. The second mechanism uses the Observer/Listener model where plugin register to receive specific message id’s and use the API WriteCommDriver to send a message.

As messages in general are formatted using JSON, plugins can use the included wxJSON library to parse or encode messages.

There are two mechanism that can be used to receive SignalK data; the "old" method using OpenCPN Plugin Messaging and the "new" method usingthe observer/listener model. Note that connections to SignalK are read only, you cannot send SignalK updates from OpenCPN.

OpenCPN provides a rich set of API’s for retrieving, creating, deleting and modifying routes, waypoints and tracks. Routes, waypoints and tracks are all identified using a Globally Unique Identifier (GUID) and this serves as the mechanism for all operations.

OpenCPN allows plugins to draw on the canvas to supplement information that is ordinariliy drawn on the chart. As OpenCPN has evolved over time, supporting single and dual canvas layouts and graphics acceleration using OpenGL so too have the plugin API’s. For simplicity sake this demo will concentrate on the multi canvas rendering API’s for both OpenGL and non OpenGL.

Note that WANTS_OVERLAY_CALLBACK must be returned in the Init function for OpenCPN to register the plugin’s callback routine.

To draw on the canvas when OpenCPN has been launched without OpenGL support, the plugin may use the following Callback API:

The rendering API’s that were available for earlier versions of OpenCPN will draw on both canvases if OpenCPN is configured in multi-canvas mode, whereas the newer API’s allow plugins to select which canvas upon which to render.

Plugins can select which layer on which to render, meaning that they can draw below all OpenCPN drawn object (OVERLAY_LEGACY), above ships (OVERLAY_OVER_SHIPS) or for important information, over all UI elements (OVERLAY_OVER_UI)

The OpenCPN view port (VP) provides the plugin with the chart extents, scale factors etc. to allow the plugin to accurately position any drawing on screen.

The helper function GetCanvasPixLL allows the plugin to convert geographic co-ordimates (latitude & longitude) to screen pixels. The reverse, converting pixels to geographic co-ordinates is performed with the GetCanvasLLPix function.

Using the wxWidgets Device Context (DC) provides a plugin with ability to use any of the wxWidgets drawing API’s.

Instead of using the wxWidgets Device Context (wxDC) to render on the canvas, plugins may opt to use a Graphics Context (wxGC) as it provides a richer set of graphics functions. For example anti-aliased drawing, transparency (alpha blending), rotation and more complex transformations.

For example, plugins can create transparent brushes so that other chart objects can be "seen through" objects drawn by the plugin. Below, the fourth parameter of SetBrush is the alpha channel and defines the level of transparency.

There are also opportunities to simplify the code by using the translation, rotation and transform functions available with the wxWidgets Graphics Context. For example in this demo plugin, instead of calculating the positions of the wind arrow using trigonometric functions, it can be simplified to the following which has the benefit of reducing the risk of programming errors and reducing the burden of code maintainance.

Most modern computers incorporate Graphics Processors (GPU) to improve the performance of graphics intensive applications. GPU’s offload graphics operations onto specialised hardware reducing the load on the CPU. Modern operating systems provide their own API’s to support graphics hardware acceleration such as DirectX on Windows, Metal on OSX and Vulkan on Linux.

There are also cross platform graphics API’s such as OpenGL which is supported on most major platforms. In the case of OpenCPN, OpenGL support is provided by wxWidgets.

Note, while Vulkan is an Open Source, Cross Platform Graphics library and the above is a bit of a generalization, at the moment OpenCPN relies on OpenGL to improve its graphics performance.

To support OpenGL, plugins must specify the compiler flag -DocpnUSE_GL. This may be added in Plugin.cmake if using the ShipDriver template or in PluginConfigure.cmake if using the TestPlugin template.

In addition the bundled library plugindc should be included as it provides classes and functions that simplify drawing on the canvas using either OpenGL (wxGLCanvas) or non-OpenGL (wxDC).

Essentially it provides a level of abstraction so the plugin developers can use API’s with the same signature as the wxWidgets Device Context API’s for both wxGLCanvas or wxDC. For example it simplifies rendering with OpenGL by allowing the plugin developer to use:

insead of the low level complex wxGLCanvas API’s

The plugin must specify the flag WANTS_OPENGL_OVERLAY_CALLBACK in the Init function to register the plugin’s callback function.

Similar to drawing on the Canvas when not using OpenGL, plugins need to determine the canvas layer upon which they weish to draw and if in multi-canvas mode, which canvas to draw upon.

Plugins can then draw on the canvas using the plugindc class and its methods as needed.

Oops, nearly forgot this important part. Having drawn on the canvas, users may want actually to interact with it!

Firstly, getting information on where the cursor is located on-screen is obtained by the callback API SetCursorLatLon which is registered by returning the value WANTS_CURSOR_LATLON in the Init function.

The previously mentioned API’s; GetCanvasLLPix and GetCanvasPixLL are used to convert screen co-ordinates (pixels) to geographic co-ordinates and vice versa.

To handle mouse interactions, plugins use another callback API, MouseEventHook which is registered by returning WANTS_MOUSE_EVENTS to the Init function.

Note the importance of the return value. Returning false allows the mouse event to be propagated for further processing while returning true will end further propagation.

Similarly for keyboard handling, plugins can use the callback API, KeyboardEventHook which is registered by returning WANTS_KEYBOARD_EVENTS to the Init function.

This is the mechanism that plugins may use to implement Shortcut keys to their specific functions. Again the return value determines whether the key event is propagated.

wxWidgets Advance User Interface (wxAUI) allows plugins to implement a rich user interface allowing multiple elements to be displayed, floated, docked and have their state to be maintained by.OpenCPN. wxAUI offers a richer set of display options than compared to using modal or non-modal dialogs or plugin launched windows, frames or forms.

Plugins need to retrieve the wxAUI Manager from OpenCPN to register, update and display their UI elements with the AUIManager a reference which is obtained through the API GetFrameAuiManager. Plugins also need to register for callbck API’s by returning the value USES_AUI_MANAGER in the Init function.

Plugins then initialize the wxPaneInfo class and update the AUI Manager. In this demo the AUI managed window is a simple dashboard.

In this example, the display of the dashboard is toggled using the OpenCPN toolbar which was previously described in Chapter 5.

Note that as the demo dashboard display is shown or hidden, the toolbar button state is also changed.

During the initialization of the AUI Manager the plugin registered for the AUI_PANE_CLOSE event. Upon receiving these events, the plugin may also determine whether the AUI managed window is shown or hidden and synchronise any other state as required, in this case the toolbar button state.

Another benefit of wxAUI is that OpenCPN saves the state of any AUI managed windows. When OpenCPN starts it will restore the state, simplifying the "plumbing" for plugin developers. The callback API UpdateAUIStatus can be implemented by plugins to detect when the wxAUI status has changed, providing plugins the opportunity to synchronise any associated state, such as in this demo the toolbar button state.

Also worth noting some of other API’s not necessarily required for AUI managed windows but important nonetheless.

When the user changes the colour scheme for OpenCPN (day, dusk, night), plugins receive a notification from the callback API SetColorScheme. This allows plugins to respond to user changes of the colour schema, perhaps by changing the colours of their UI elements, or for plugns that interact with switching systems, turn on/off lights, send commands over a network to change instrument displays or MFD’s.

To apply OpenCPN colour schemes to plugin UI elements, the OpenCPN API DimeWindow will apply the configured colour scheme to the plugin. For example in the Demo Dashboard when the colour scheme is changed, it applies the background colour to all of its child controls. (It does however apply its own colours to the foreground)

For further information about wxAUI, you should refer to the wxWidgets official documentation.