MythPlugin Architecture

From MythTV Official Wiki
Jump to: navigation, search

Page Purpose

The purpose of this page is to provide general information and tips for someone interested in developing a plugin for myth. This page aims to answer questions a new MythTV Plugins developer may have that are not addressed elsewhere.

Suggested Reading

Before beginning work on your first plugin, you should look over this page as well as the following pages in order to become familiar with important aspects of MythTV development.

Coding Standards

Database Schema

Development Information

MythUI Theme Development

Architecture Overview

MythPlugins are written in C++ and are compiled as shared object files. Myth looks for plugins in a specific location relative to its own installation location and invokes them via three methods.

mythplugin_init is called whenever mythfrontend is started. This method typically handles upgrading gracefully as it will be the first method called after a new version of the plugin has been installed.

mythplugin_run is invoked when the action attribute of a menu item requests it via the PLUGIN directive. This is the method that should be run when the user chooses to enter the plugin from the main menu or the appropriate submenu.

mythplugin_config is invoked when the action attribute of a menu item requests it via the CONFIGPLUGIN directive. This is the method that should be run when the users wishes to configure the plugin.

Development Strategy

The best way to understand the MythTV Plugin Architecture and how to use it is simply to start examining the source code of existing plugins. The MythGame plugin is fairly simple from a user interface standpoint as is the MythMovies plugin currently only available via #2482.

Plugin User Interface

MythTV has an internal user interface system that plugins generally use to establish their graphical user interfaces. The user interface parameters are stored in an XML file with a filename ending in "-ui.xml." This file is referenced by the MythThemedDialog class by supplying the portion of the filename prior to "-ui.xml" to its constructor. For example, a plugin which stored its GUI info in helloworld-ui.xml would pass "helloworld" to MythThemedDialog.

A plugin's UI code can then obtain handles to the graphical elements established by MythThemedDialog by executing the appropriate getUI[object type]Type function, passing in the name of the object to get. For example, to obtain a reference to a textbox named "hellobox", the following code could be used:

UITextType *helloBox = getUITextType("hellobox");

One can then interact with the helloBox object using various methods for the purpose of providing the user interface functionality.

[todo: add information about intercepting/processing keypresses]

Saving/Retrieving Settings

Settings handling is provided by the gContext object, which should generally be available within any MythTV plugin.

Due to MythTV's client/server design, there can be any number of clients using the same mysql database to store settings. For this reason, settings may be stored per-host or globally for all hosts. To save settings for the front-end that is currently running, use MythContext::SaveSetting and MythContext::GetSetting respectively. For example:

//Get a setting named MySetting
QString mySetting = gContext->GetSetting("MySetting");

//Save a setting named MyOtherSetting
gContext->SaveSetting("MyOtherSetting", "Some Value");

In some instances, it may be desirable to specify the host to use in managing a particular setting. In these cases, use MythContext::GetSettingOnHost and MythContext::SaveSettingOnHost as follows:

//Get a setting named MySetting
QString mySetting = gContext->GetSetting("MySetting", "Hostname");

//Save a setting named MyOtherSetting
gContext->SaveSetting("MyOtherSetting", "Some Value", "Hostname");

If it is necessary to retrieve a setting as a particular datatype, MythContext also exposes GetNumSetting which returns an integer and GetFloatSetting which returns a double.

See MythContext.h and MythContext.cpp for more information.

Menu Integration

[todo: add a basic overview of the mythmenu system. perhaps this should be a separate page and cover more than just plugin menu directives?]