Building Plugins:MythNotes
This page tells you about basic functionalites available in MythTV for simpler plug-in development. It's based on a series of examples which shows the basic usage of those features.
Contents
Introduction
Following section tells you some basic prerequisites for MythTV plug-in development
Plug-in interface
Every plug-in has four functions, which interface with MythTV.
- int mythplugin_init(const char *libversion) - executed during the MythTV start-up
- int mythplugin_run() - executed whenever the plug-in is selected from menu
- void mythplugin_destory() - executed during MythTV exit
- int mythplugin_config() - executed whenever the plug-in configuration button is selected from menu
Before we start
The easiest way to start developing is by checking out the svn. When you configure it, it provides necessarily files and creates symlinks to your MythTV's files.
git clone git://github.com/MythTV/mythtv.git cd mythpluginis ./configure --prefix=/usr/ # you might want to change the prefix and other settings
Plug-in file structure
As the MythTV is written in QT the '*.pro' files are used to create Makefile files. For UI layout the XML files are used and individual elements are then assigned in C++ code.
Most plug-ins follows this file structure (root directory '/' is the mythplugins svn folder):
$plugin_name/ # Master project folder $plugin_name/$plugin_name/ # Plug-in C++ code $plugin_name/theme/ # Theme dummy files $plugin_name/theme/default/ # Place for UI XML files in 4:3 aspect $plugin_name/theme/default-wide/ # Place for UI XML files in 16:9 aspect $plugin_name/theme/menus/ # Place for additional menus (also in XML format)
To insert your plug-in into MythTV menu you need to modify the menu file. You need to do it manually as the menu themes are statically defined. The themes are located in "$prefix/share/mythtv/themes" folder, and the default menu theme can be found in the 'defaultmenu' folder. If you use a different menu theme, be sure to select the proper one. For inserting the plug-in into the main menu you need to edit the "mainmenu.xml". More on this topic is further on this page.
Example plug-in
MythNotes is ONLY a TRAINING plug-in which increasingly leads you from simple Hello World to a complex plug-in including SQL storage and other features.
Default files
Create the mythnotes file structure:
cd $mythplugins_root # the svn folder with another plug-ins mkdir mythnotes mkdir mythnotes/mythnotes mkdir mythnotes/theme mkdir mythnotes/theme/default mkdir mythnotes/theme/default-wide mkdir mythnotes/theme/menus
From now on the root directory ('/' at the beginning) means the $mythplugins_root/mythnotes folder.
Couple of files are always the same/similar. Let's start with them. You can copy them from another example and modify them:
TEMPLATE = subdirs # Directories SUBDIRS = mythnotes theme
This file only tells qmake to search the mythnotes and theme subdirectories for *.pro files
include ( ../../mythconfig.mak ) include ( ../../settings.pro ) QMAKE_STRIP = echo TARGET = themenop TEMPLATE = app CONFIG -= qt moc QMAKE_COPY_DIR = sh ../../cpsvndir defaultfiles.path = $${PREFIX}/share/mythtv/themes/default defaultfiles.files = default/*.xml default/images/*.png widefiles.path = $${PREFIX}/share/mythtv/themes/default-wide widefiles.files = default-wide/*.xml default-wide/images/*.png menufiles.path = $${PREFIX}/share/mythtv/ menufiles.files = menus/*.xml INSTALLS += defaultfiles widefiles menufiles # Input SOURCES += ../../themedummy.c
Dummy project used by "make install" to copy all the XML files into right locations.
include ( ../../mythconfig.mak ) include ( ../../settings.pro ) include ( ../../programs-libs.pro ) TEMPLATE = lib CONFIG += plugin \ thread TARGET = mythnotes target.path = $${LIBDIR}/mythtv/plugins INSTALLS += target INCLUDEPATH += $${PREFIX}/include/mythtv/libmythui # Input HEADERS += SOURCES += main.cpp QT += sql \ xml \ opengl include ( ../../libs-targetfix.pro )
This file is the actual project file for our C++ code. Most of it stays but there have to be some adjustments:
- TARGET - our plug-in name
- HEADERS - all the header files
- SOURCES - all the source files (Otherwise it might compile right but you'll get "unknown symbol" error messages during execution)
The plug-in has two executable parts (mythplugin_run and mythplugin_config) which needs to be selected from the MythTV menu. The "make install" command won't create the menu item as it can't know where to put it. You need to do this manually by changing the menu files. The are located in "$prefix/share/mythtv/themes/defaultmenu/" folder. For inserting the plug-in into the main menu you need to edit the "mainmenu.xml". Similarly you can find another menus too.
/usr/share/mythtv/themes/defaultmenu/mainmenu.xml
<button> <type>MYTHNOTES</type> <text>MythNotes</text> <description>MythNotes demonstration plug-in</description> <action>PLUGIN mythnotes</action> <depends>mythnotes</depends> </button>
Insert this to somewhere in mainmenu.xml to create a button in MythTV's main menu. The buttons are created in the same order as in XML file. The important parts are "<action>" which says: run mythplugin_run() in library libmythnotes and "<depends>" which says don't show this button if libmythnotes doesn't exists.
/usr/share/mythtv/themes/defaultmenu/main_settings.xml
<button> <type>MYTHNOTES</type> <text>MythNotes Settings</text> <description>MythNotes demonstration plug-in setting</description> <action>CONFIGPLUGIN mythnotes</action> <depends>mythnotes</depends> </button>
The main difference between this and the previous button is in "<action>" which says: run mythplugin_config() in library libmythnotes.
MythNotes
After going through previous parts you are prepared to create your very first Hello World application and even more...
Hello world
It says Hello World.
- Use XML to define layout
- Write simple text
Basic UI
Demonstrates some of available UIs.
- Use XML to define a page with multiple UI widgets
- Create basic signals and slots to handle the UI communication
Complete plugin
Displays how many times was the plug-in executed since mythfrontend start.
- "Invisible" initialization and clean-up parts
- Second window for plug-in configuration
Storing the information
Stores full-text notes in one big textarea.
- Internal storage gContext
- Basic SQL storage
Advanced UI
Shows list structure of objects stored in DB.
- ButtonList
- Popup window
Advanced SQL storage
Stores full-text notes separately
- SQL layout initialization
- SQL layout update
- Using SQL commands