Base class for OpenCPN plugins. More...

#include <ocpn_plugin.h>

Inheritance diagram for opencpn_plugin:

Public Member Functions
	opencpn_plugin (void *pmgr)

virtual int	Init (void)
	Initialize the plugin and declare its capabilities.

virtual bool	DeInit (void)
	Clean up plugin resources.

virtual int	GetAPIVersionMajor ()
	Returns the major version number of the plugin API that this plugin supports.

virtual int	GetAPIVersionMinor ()
	Returns the minor version number of the plugin API that this plugin supports.

virtual int	GetPlugInVersionMajor ()
	Returns the major version number of the plugin itself.

virtual int	GetPlugInVersionMinor ()
	Returns the minor version number of the plugin itself.

virtual wxBitmap *	GetPlugInBitmap ()
	Get the plugin's icon bitmap.

virtual wxString	GetCommonName ()
	Get the plugin's common (short) name.

virtual wxString	GetShortDescription ()
	Get a brief description of the plugin.

virtual wxString	GetLongDescription ()
	Get detailed plugin information.

virtual void	SetDefaults (void)
	Sets plugin default options.

virtual int	GetToolbarToolCount (void)
	Returns the number of toolbar tools this plugin provides.

virtual int	GetToolboxPanelCount (void)
	Returns the number of preference pages this plugin provides.

virtual void	SetupToolboxPanel (int page_sel, wxNotebook *pnotebook)
	Creates a plugin preferences page.

virtual void	OnCloseToolboxPanel (int page_sel, int ok_apply_cancel)
	Handles preference page closure.

virtual void	ShowPreferencesDialog (wxWindow *parent)
	Shows the plugin preferences dialog.

virtual bool	RenderOverlay (wxMemoryDC pmdc, PlugIn_ViewPort vp)
	Render plugin overlay graphics using standard device context.

virtual void	SetCursorLatLon (double lat, double lon)
	Receives cursor lat/lon position updates.

virtual void	SetCurrentViewPort (PlugIn_ViewPort &vp)
	Notifies plugin of viewport changes.

virtual void	SetPositionFix (PlugIn_Position_Fix &pfix)
	Updates plugin with current position fix data.

virtual void	SetNMEASentence (wxString &sentence)
	Receive all NMEA 0183 sentences from OpenCPN.

virtual void	SetAISSentence (wxString &sentence)
	Receive all AIS sentences from OpenCPN.

virtual void	ProcessParentResize (int x, int y)
	Handles parent window resize events.

virtual void	SetColorScheme (PI_ColorScheme cs)
	Updates plugin color scheme.

virtual void	OnToolbarToolCallback (int id)
	Handles toolbar tool clicks.

virtual void	OnContextMenuItemCallback (int id)
	Handles context menu item selection.

virtual void	UpdateAuiStatus (void)
	Updates AUI manager status.

virtual wxArrayString	GetDynamicChartClassNameArray (void)
	Returns array of dynamically loaded chart class names.

Detailed Description

Base class for OpenCPN plugins.

All plugins must inherit from this class and implement the required virtual methods. The class provides the interface between plugins and the OpenCPN core application.

Two types of methods exist:

Required methods that must be implemented by all plugins
Optional methods that may be implemented based on plugin capabilities

PlugIns must implement optional method overrides consistent with their declared capabilities flag as returned by Init().

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 1197 of file ocpn_plugin.h.

Constructor & Destructor Documentation

◆ opencpn_plugin()

opencpn_plugin::opencpn_plugin ( void * pmgr )

inline

Definition at line 1199 of file ocpn_plugin.h.

◆ ~opencpn_plugin()

opencpn_plugin::~opencpn_plugin ( )

virtual

Definition at line 82 of file ocpn_plugin.cpp.

Member Function Documentation

◆ DeInit()

bool opencpn_plugin::DeInit ( void )

virtual

Clean up plugin resources.

This required method is called by OpenCPN during plugin unloading or program shutdown. It should release any resources allocated by the plugin.

Returns: True if cleanup successful, False if error

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 86 of file ocpn_plugin.cpp.

◆ GetAPIVersionMajor()

int opencpn_plugin::GetAPIVersionMajor ( )

virtual

Returns the major version number of the plugin API that this plugin supports.

This method must be implemented by all plugins to declare compatibility with a specific major version of the OpenCPN plugin API.

Returns: Integer value representing the major API version (e.g., 1)

Note: Major version changes indicate incompatible API changes; Current API major version is defined by API_VERSION_MAJOR

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 88 of file ocpn_plugin.cpp.

◆ GetAPIVersionMinor()

int opencpn_plugin::GetAPIVersionMinor ( )

virtual

Returns the minor version number of the plugin API that this plugin supports.

This method must be implemented by all plugins to declare compatibility with a specific minor version of the OpenCPN plugin API.

Returns: Integer value representing the minor API version (e.g., 19)

Note: Minor version changes indicate backward-compatible API additions; Current API minor version is defined by API_VERSION_MINOR

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 90 of file ocpn_plugin.cpp.

◆ GetCommonName()

wxString opencpn_plugin::GetCommonName ( )

virtual

Get the plugin's common (short) name.

This required method should return a short name used to identify the plugin in lists and menus.

Returns: wxString containing plugin name (e.g., "Dashboard")

Note: Should be valid and meaningful even before Init() is called; Used by the plugin manager GUI

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 96 of file ocpn_plugin.cpp.

◆ GetDynamicChartClassNameArray()

wxArrayString opencpn_plugin::GetDynamicChartClassNameArray ( void )

virtual

Returns array of dynamically loaded chart class names.

Called by OpenCPN to get list of chart classes provided by this plugin. Must be implemented if plugin provides custom chart types.

Returns: Array of strings containing chart class names

Note: For plugins that implement INSTALLS_PLUGIN_CHART capability; Custom chart types must also implement PlugInChartBase interface

Definition at line 143 of file ocpn_plugin.cpp.

◆ GetLongDescription()

wxString opencpn_plugin::GetLongDescription ( )

virtual

Get detailed plugin information.

This required method should return a longer description including:

Detailed feature list
Version information
Author/copyright details

Returns: wxString containing detailed plugin information

Note: Should be valid before Init() is called; Used in plugin manager details view

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 102 of file ocpn_plugin.cpp.

◆ GetPlugInBitmap()

wxBitmap * opencpn_plugin::GetPlugInBitmap ( )

virtual

Get the plugin's icon bitmap.

FIXME static wxBitmap* LoadSVG(const wxString filename, unsigned int width, unsigned int height) { if (!gFrame) return new wxBitmap(width, height); // We are headless.

This method should return a wxBitmap containing the plugin's icon for display in the plugin manager and other UI elements.

Returns: Pointer to wxBitmap containing icon, NULL for default icon

Note: The bitmap should be square, typically 32x32 pixels; Ownership of the bitmap remains with the plugin; Icon should be visible on both light and dark backgrounds

#ifdef ANDROID return loadAndroidSVG(filename, width, height); #elif defined(ocpnUSE_SVG) wxSVGDocument svgDoc; if (svgDoc.Load(filename)) return new wxBitmap(svgDoc.Render(width, height, NULL, true, true)); else return new wxBitmap(width, height); #else return new wxBitmap(width, height); #endif }

wxBitmap* opencpn_plugin::GetPlugInBitmap() { auto bitmap = PluginLoader::GetInstance()->GetPluginDefaultIcon(); return const_cast<wxBitmap*>(bitmap); }

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 76 of file ocpn_plugin.cpp.

◆ GetPlugInVersionMajor()

int opencpn_plugin::GetPlugInVersionMajor ( )

virtual

Returns the major version number of the plugin itself.

This method should return the plugin's own major version number, which is used by OpenCPN for plugin version management and display.

Returns: Integer value representing the plugin's major version

Note: Part of semantic version (major.minor.patch); Major version changes indicate incompatible API changes

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 92 of file ocpn_plugin.cpp.

◆ GetPlugInVersionMinor()

int opencpn_plugin::GetPlugInVersionMinor ( )

virtual

Returns the minor version number of the plugin itself.

This method should return the plugin's own minor version number, which is used by OpenCPN for plugin version management and display.

Returns: Integer value representing the plugin's minor version

Note: Part of semantic version (major.minor.patch); Minor version changes indicate backward-compatible feature additions

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 94 of file ocpn_plugin.cpp.

◆ GetShortDescription()

wxString opencpn_plugin::GetShortDescription ( )

virtual

Get a brief description of the plugin.

This required method should return a short description (1-2 sentences) explaining the plugin's basic functionality.

Returns: wxString containing brief description

Note: Should be valid before Init() is called; Used in plugin manager list view

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 98 of file ocpn_plugin.cpp.

◆ GetToolbarToolCount()

int opencpn_plugin::GetToolbarToolCount ( void )

virtual

Returns the number of toolbar tools this plugin provides.

This method should return how many toolbar buttons/tools the plugin will add. Must be implemented if plugin sets INSTALLS_TOOLBAR_TOOL capability flag.

Returns: Number of toolbar items to be added

Note: Return 0 if no toolbar items; Each tool needs unique ID for callbacks; Called during plugin initialization

Reimplemented in dashboard_pi, and wmm_pi.

Definition at line 113 of file ocpn_plugin.cpp.

◆ GetToolboxPanelCount()

int opencpn_plugin::GetToolboxPanelCount ( void )

virtual

Returns the number of preference pages this plugin provides.

This method should return how many pages the plugin will add to the toolbox (preferences) dialog. Must be implemented if plugin sets INSTALLS_TOOLBOX_PAGE flag.

Returns: Number of preference pages to add

Note: Return 0 if no preference pages; Called during preferences dialog creation

Definition at line 115 of file ocpn_plugin.cpp.

◆ Init()

int opencpn_plugin::Init ( void )

virtual

Initialize the plugin and declare its capabilities.

This required method is called by OpenCPN during plugin loading. It should:

Set up any required plugin resources
Register capabilities by returning a bitwise OR of WANTS_ and INSTALLS_ flags

Returns

Integer capability flags indicating plugin features:

WANTS_OVERLAY_CALLBACK
WANTS_CURSOR_LATLON
WANTS_TOOLBAR_CALLBACK
etc. (see enum definitions)

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 84 of file ocpn_plugin.cpp.

◆ OnCloseToolboxPanel()

void opencpn_plugin::OnCloseToolboxPanel	(	int	page_sel,
		int	ok_apply_cancel
	)

virtual

Handles preference page closure.

This method is called when plugin preference pages are closed. Use it to save settings changes or cleanup resources.

Parameters

page_sel	Index of page being closed
ok_apply_cancel	Result: 0 = OK (apply changes) 1 = APPLY (apply but don't close) 2 = CANCEL (discard changes)

Note: Only called if plugin implements SetupToolboxPanel(); Good place to save settings to config

Reimplemented in chartdldr_pi.

Definition at line 119 of file ocpn_plugin.cpp.

◆ OnContextMenuItemCallback()

void opencpn_plugin::OnContextMenuItemCallback ( int id )

virtual

Handles context menu item selection.

Called when user selects a plugin's context menu item. Must be implemented if plugin adds items via AddCanvasContextMenuItem().

Parameters

id	The menu item ID assigned when item was added

Reimplemented in grib_pi.

Definition at line 125 of file ocpn_plugin.cpp.

◆ OnToolbarToolCallback()

void opencpn_plugin::OnToolbarToolCallback ( int id )

virtual

Handles toolbar tool clicks.

Called when the user clicks a plugin's toolbar button. Must be implemented if plugin declares WANTS_TOOLBAR_CALLBACK capability.

Parameters

id	The tool ID assigned when tool was added via InsertPlugInTool()

Reimplemented in dashboard_pi, grib_pi, and wmm_pi.

Definition at line 123 of file ocpn_plugin.cpp.

◆ ProcessParentResize()

void opencpn_plugin::ProcessParentResize	(	int	x,
		int	y
	)

virtual

Handles parent window resize events.

Called when OpenCPN's main window is resized to allow plugins to adjust their UI elements accordingly.

Parameters

x	New window width in pixels
y	New window height in pixels

Definition at line 137 of file ocpn_plugin.cpp.

◆ RenderOverlay()

bool opencpn_plugin::RenderOverlay	(	wxMemoryDC *	pmdc,
		PlugIn_ViewPort *	vp
	)

virtual

Render plugin overlay graphics using standard device context.

Called by OpenCPN during chart redraw to allow plugins to render custom visualization overlays on top of charts. Drawing is done through a device context abstraction (piDC) that handles both standard and OpenGL contexts.

Examples include:

Weather routing course lines and markers
GRIB weather data visualization
Custom chart layers
Route tracking and navigation data

Rendering order is determined by plugin load order in array for same priority level.

Parameters

dc	Reference to wxDC device context for drawing
vp	Pointer to current viewport settings (scale, position, rotation)

Returns: True if overlay was rendered, false if no overlay

Note: Only called if plugin declares WANTS_OVERLAY_CALLBACK capability; Drawing should respect current viewport parameters; Performance critical - keep drawing efficient; Companion to RenderGLOverlay() for OpenGL-specific rendering

Reimplemented in opencpn_plugin_16, opencpn_plugin_17, and opencpn_plugin_18.

Examples: /home/runner/work/main/main/opencpn/include/ocpn_plugin.h.

Definition at line 127 of file ocpn_plugin.cpp.

◆ SetAISSentence()

void opencpn_plugin::SetAISSentence ( wxString & sentence )

virtual

Receive all AIS sentences from OpenCPN.

Plugins can implement this method to receive all AIS sentences. They must set the WANTS_AIS_SENTENCES capability flag to receive updates.

Parameters

sentence The AIS sentence in standard NMEA 0183 VDM/VDO format (e.g., "!AIVDM,1,1,,B,15MwkRUOidG?GElEa<iQk1JV06Jd,0*1D") These sentences contain binary encoded AIS messages that follow the ITU-R M.1371 standard.

Note: For handling NMEA/SignalK messages, a newer recommended message API is available: Plugin Message API Documentation

Definition at line 111 of file ocpn_plugin.cpp.

◆ SetColorScheme()

void opencpn_plugin::SetColorScheme ( PI_ColorScheme cs )

virtual

Updates plugin color scheme.

Called when OpenCPN's color scheme changes between day, dusk and night modes. Plugins should update their UI colors to match the new scheme.

Parameters

cs	New color scheme to use: PI_GLOBAL_COLOR_SCHEME_DAY PI_GLOBAL_COLOR_SCHEME_DUSK PI_GLOBAL_COLOR_SCHEME_NIGHT

Reimplemented in dashboard_pi, grib_pi, and wmm_pi.

Definition at line 139 of file ocpn_plugin.cpp.

◆ SetCurrentViewPort()

void opencpn_plugin::SetCurrentViewPort ( PlugIn_ViewPort & vp )

virtual

Notifies plugin of viewport changes.

This method is called whenever the chart viewport changes on any canvas due to:

User pan/zoom operations
Periodic canvas updates
Course/heading changes affecting chart orientation

For multi-canvas configurations (e.g. split screen), this is called separately for each canvas's viewport changes, regardless of which canvas has focus or mouse interaction.

Parameters

vp	New viewport parameters

Note: Called frequently during chart navigation; Use for maintaining overlay alignment

Reimplemented in grib_pi.

Definition at line 133 of file ocpn_plugin.cpp.

◆ SetCursorLatLon()

void opencpn_plugin::SetCursorLatLon	(	double	lat,
		double	lon
	)

virtual

Receives cursor lat/lon position updates.

This method is called when the cursor moves over the chart. Must be implemented if plugin sets WANTS_CURSOR_LATLON flag.

Parameters

lat	Cursor latitude in decimal degrees
lon	Cursor longitude in decimal degrees

Note: High frequency updates - keep processing quick; Only called when cursor over chart window

Reimplemented in dashboard_pi, grib_pi, and wmm_pi.

Definition at line 131 of file ocpn_plugin.cpp.

◆ SetDefaults()

void opencpn_plugin::SetDefaults ( void )

virtual

Sets plugin default options.

This method is called when a plugin is enabled via the user preferences dialog. It provides an opportunity to set up any default options and behaviors.

Note: Optional override - implement if plugin has configurable options; Called before plugin is activated in GUI; Good place to load saved settings from config file

Reimplemented in grib_pi.

Definition at line 135 of file ocpn_plugin.cpp.

◆ SetNMEASentence()

void opencpn_plugin::SetNMEASentence ( wxString & sentence )

virtual

Receive all NMEA 0183 sentences from OpenCPN.

Plugins can implement this method to receive all NMEA 0183 sentences. They must set the WANTS_NMEA_SENTENCES capability flag to receive updates.

Parameters

sentence The NMEA 0183 sentence

Note: For handling NMEA/SignalK messages, a newer recommended message API is available: Plugin Message API Documentation

Reimplemented in dashboard_pi.

Definition at line 109 of file ocpn_plugin.cpp.

◆ SetPositionFix()

void opencpn_plugin::SetPositionFix ( PlugIn_Position_Fix & pfix )

virtual

Updates plugin with current position fix data.

Called by OpenCPN when a new position fix is received. Plugins can use this to track vessel position, course and speed.

Parameters

pfix	Position fix data containing: Lat: Latitude in decimal degrees Lon: Longitude in decimal degrees Cog: Course over ground in degrees Sog: Speed over ground in knots Var: Magnetic variation in degrees FixTime: UTC timestamp of fix nSats: Number of satellites used in fix

Note: Only called if plugin declares WANTS_NMEA_EVENTS capability; For extended data including heading, use SetPositionFixEx()

Reimplemented in wmm_pi.

Definition at line 107 of file ocpn_plugin.cpp.

◆ SetupToolboxPanel()

void opencpn_plugin::SetupToolboxPanel	(	int	page_sel,
		wxNotebook *	pnotebook
	)

virtual

Creates a plugin preferences page.

This method is called to create each preferences page the plugin provides. Must be implemented if plugin sets INSTALLS_TOOLBOX_PAGE flag.

Parameters

page_sel	Index of page to create (0 to GetToolboxPanelCount()-1)
pnotebook	Parent notebook to add page to

Note: Called once for each page index; Use standard wxWidgets controls for consistent look; Parent notebook uses wxAUI manager

Definition at line 117 of file ocpn_plugin.cpp.

◆ ShowPreferencesDialog()

void opencpn_plugin::ShowPreferencesDialog ( wxWindow * parent )

virtual

Shows the plugin preferences dialog.

This method is called when the user requests the plugin preferences through the OpenCPN options dialog. Must be implemented if plugin sets WANTS_PREFERENCES flag.

Parameters

parent Parent window to use for dialog

Note: Different from toolbox panel preferences; Use for simple plugin-specific settings; Modal dialog recommended

Reimplemented in chartdldr_pi, dashboard_pi, grib_pi, and wmm_pi.

Definition at line 121 of file ocpn_plugin.cpp.

◆ UpdateAuiStatus()

void opencpn_plugin::UpdateAuiStatus ( void )

virtual

Updates AUI manager status.

Called to notify plugins using wxAUI interface that they should update their AUI managed windows and panes. Must be implemented if plugin declares USES_AUI_MANAGER capability.

Reimplemented in dashboard_pi.

Definition at line 141 of file ocpn_plugin.cpp.

The documentation for this class was generated from the following files:

/home/runner/work/main/main/opencpn/include/ocpn_plugin.h
/home/runner/work/main/main/opencpn/model/src/ocpn_plugin.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ opencpn_plugin()

◆ ~opencpn_plugin()

Member Function Documentation

◆ DeInit()

◆ GetAPIVersionMajor()

◆ GetAPIVersionMinor()

◆ GetCommonName()

◆ GetDynamicChartClassNameArray()

◆ GetLongDescription()

◆ GetPlugInBitmap()

◆ GetPlugInVersionMajor()

◆ GetPlugInVersionMinor()

◆ GetShortDescription()

◆ GetToolbarToolCount()

◆ GetToolboxPanelCount()

◆ Init()

◆ OnCloseToolboxPanel()

◆ OnContextMenuItemCallback()

◆ OnToolbarToolCallback()

◆ ProcessParentResize()

◆ RenderOverlay()

◆ SetAISSentence()

◆ SetColorScheme()

◆ SetCurrentViewPort()

◆ SetCursorLatLon()

◆ SetDefaults()

◆ SetNMEASentence()

◆ SetPositionFix()

◆ SetupToolboxPanel()

◆ ShowPreferencesDialog()

◆ UpdateAuiStatus()