Building Plugins:MythNotes

From MythTV Official Wiki
Jump to: navigation, search

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.

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 git. When you configure it, it provides necessarily files and creates symlinks to your MythTV's files.

git clone git://github.com/MythTV/mythtv.git
git checkout fixes/31         # optional a clean checkout will use master but you can choose any branch you want
cd mythplugins
./configure --prefix=/usr/    # you might want to change the prefix and other settings

Plug-in file structure

As the MythTV is written in c++ and uses 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 git 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)

MythTV menu

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 directory containing the other plug-ins mytharchive, mythbrowser, mythnews etc
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:


Script.png /mythnotes.pro

TEMPLATE = subdirs

# Directories

SUBDIRS = mythnotes theme

This file only tells qmake to search the mythnotes and theme subdirectories for *.pro files


Script.png /theme/theme.pro

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.


Script.png /mythnotes/mythnotes.pro

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
INCLUDEPATH += $${PREFIX}/include/mythtv/libmythui
INCLUDEPATH += $${PREFIX}/include/mythtv/libmythbase

# Input
HEADERS += 
SOURCES += main.cpp

QT += sql xml opengl network

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)

MythTV menu

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 (if you are using the "default" menu theme - configured in "Utilities / Setup / Setup / Appearance / Menu theme") "mainmenu.xml". Similarly you can find another menus too.


Script.png /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.


Script.png /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

Building_Plugins:MythNotes00

It says Hello World.

  • Use XML to define layout
  • Write simple text

Basic UI

Building_Plugins:MythNotes01

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

Building_Plugins:MythNotes02

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

Building_Plugins:MythNotes03

Stores full-text notes in one big textarea.

  • Internal storage gContext
  • Basic SQL storage

Advanced UI

Building_Plugins:MythNotes04

Shows list structure of objects stored in DB.

  • ButtonList
  • Popup window

Advanced SQL storage

Building_Plugins:MythNotes05

Stores full-text notes separately

  • SQL layout initialization
  • SQL layout update
  • Using SQL commands