Adding Menu Commands

But I don't know C++!
No problem... MythTV's menus aren't created in code - they're built from XML documents, and if you're familiar with XML, then you can edit your menus, create new ones, etc. I'll briefly discuss how I was able to 'hack' my menus to add a couple commands that I needed. This isn't textbook, it's just the way I've found to do this through looking through some of the code, and tinkering. Cause, isn't that what this project is all about?


How Do Menus Work?
If you'd like to check out the menu-building XML documents, browse through /usr/share/mythtv/*.xml. Start with mainmenu.xml, and branch out from there. Here's a snippet from mainmenu.xml:

----------------* snippet

<button>
<type>MENU_MEDIA_LIBRARY</type>
<text>Media Library</text>
<action>MENU library.xml</action>
</button>

----------------* /snippet

This example is pretty straight forward. Each button/menu item gets a "button" entry.

Menu Themes
Inside, you'll need to include the "type" of button - in this case, it's "MENU_MEDIA_LIBRARY." This is used to determine how to render the page - what image to use and where to put it. In this case, if you look in /usr/share/mythtv/themes, you'll see how each theme implements this button type. For example, in the "blue" theme, in /usr/share/mythtv/themes/blue/theme.xml, this button type is described as:

----------------* snippet

<buttondef name="MENU_MEDIA_LIBRARY">
<image>cd.png</image>
<offset>15,10</offset>
</buttondef>

----------------* /snippet

In that directory you'll find cd.png. I haven't spent any time with the themes, so this is as far as I'll go into themes.

Menu Entry Text
The "text" element describes the text to display on the page. I've found that there is a maxium number of characters you can use, but haven't checked what that number is. You'll notice that the menu supports different languages. I haven't bothered with translations.


Menu Actions
And last and most important, you'll notice the "action" element. This tells MythTV what to do when you select this menu entry. I've found the following to be valid:
* Menu Command
- usage: MENU [some menu xml file]
- purpose: To tell redirect MythTV to another menu. This is useful for subdividing your actions into different, specific pages.
- example (omit the quotes): "MENU library.xml"

* Plugin Command
- usage: PLUGIN [plugin name]
- purpose: I haven't used this yet, but it apparently launches a MythTV plugin
- example (omit the quotes): "PLUGIN mythgame"

* Built-In Actions:
- usage: [SOME ACTION NAME]
- purpose: to launch an action built into MythTV
- example (omit the quotes): "TV_WATCH_RECORDING"

* Execute a Command:
- usage: EXEC [some command path]
- purpose: to launch an external command
- example (omit the quotes): "EXEC /usr/local/bin/mythtv_rip_cd"

I've only really worked with the "EXEC" action. For example, I'm finding it useful to write Perl scripts to handle stuff in the background that normally occupies MythTV's display, such as ripping/encoding CDs to mp3/ogg. I wrote a simple Perl script that rips & encodes a CD off in another process, letting me continue to use MythTV while the CD is being worked on. As I find the time, I'll write several more of these commands, and eventually post them all here on the blog to share.


Menu Dependencies
There's one more element inside a "button" group - "depends." I haven't looked into this, but it seems that this refers to a module. I would imagine if the specified MythTV module isn't loaded, the menu item will not appear, but I'm not yet sure.


Customizing Your Menus
I need to hand it to the MythTV crew - the menuing system seems to have been done really well. I'm impressed that the menus are rendered from XML rather than compiled (you'd be surprised how often that's the case), and this next bit of information impresses me even further... Each user can keep their own copy of the menu XML files.

Rather than edit the files in /usr/share/mythtv/, you can (and I would strongly encourage you to) copy the XML documents that you want to edit into your MythTV user's "~/.mythtv/" directory. If MythTV finds an XML file here, it uses it rather than the ones found in /usr/share/mythtv/.

So, for a little fun, try editing one of the menus:

1. Copy the mainmenu.xml file from /usr/share/mythtv/mainmenu.xml to ~mythuser/.mythtv/
(assumes that "mythuser" is your MythTV user)
2. Edit ~mythuser/.mythtv/mainmenu.xml
3. Replace "Watch TV" with "MythTV Rocks!"
4. Restart MythTV and get a chuckle...
5. When you're all done, remove the overriding XML file to go back to the normal menus

Conclusion
Kudos to the MythTV developers, they've done a great job with the menus! They've given us a way to really make this system our own. It's easy to add and remove commands and menus - we can add anything we need without any worry of screwing up the system, thanks to the home directory menu overriding. Spend a little time playing with this, and you'll think of all sorts of interesting ways to use it. When you do, please let me know what you've come up with!