The Menu System

Freevo Plugin Writing HOWTO: Writing your own plugins for Freevo
Prev | Chapter 2. Internal Structure | Next

# 2.3. The Menu System

Menu's in freevo are done using the classes described below. But in general they are essential lists of items which have their names displayed in the list. Each item then has actions associated with them. The first action is the one used when selected and you can use enter to see the others. Menu's also have actions that can be associated with them to perform actions or updates.

## 2.3.1. Menu

Menu is essentially a class wrapped around an array of choices. It has several methods but the constructor is the most commonly used. It takes a title, then an array of options, and then some optional parameters. The reload_func is the most commonly used. The reload_func is used when you come back from executing an item. It's only used when you want to show something other than the menu you started with when you come back.

    # make the command menu using the command_items array and when we call refresh with the reload arg we go back to the main menu.
    command_menu = menu.Menu(_('Commands'), command_items, reload_func=menuwidget.goto_main_menu)

    #make a basic menu with the string variable name for its name and items the array of choices.
    mymenu = menu.Menu(name, items)

## 2.3.2. Item

Item is the base class for anything that appears in the Menu. Generally you create a subclass of Item and then create an actions method to tell the menu what to do when the item is clicked. The name property is what the Menu object uses to display on the screen. You can then create other variables to hold important data points in.

    class CoolItem(Item):
        def __init__(self, command):
            Item.__init__(self)
            self.name = command
            self.image = util.getimage(self.cmd)

        def actions(self):
            """
            return a list of actions for this item
            """
            items = [ ( self.runMyCommand , _('Run Command') ) ]
            return items

        def runMyCommand(self, arg=None, menuw=None):
            # do some real cool stuff..

## 2.3.3. MenuItem

This is a convenience class it is useful in two different situations. The first and most common is for creating Menus to display error conditions. The second use is for when you only need a very simple item with a single easy action.

To use MenuItem in the error condition case you call the constructor with three parameters. The first parameter is what to display in the menu, the second is the action to take when the item to select and the third is put the arg to the action function. In this case you typically wrap the constructor call into an append to your list of items to be given to menu.

To use MenuItem as a simple Item and not bother with creating your own sub item class, you again call the constructor with the set of three parameters. The first parameter is what to display in the menu, the second is the action to take when the item to select and the third is put the arg to the action function. But typically you save a reference to this item and set a few additional parameters manually.

    # you would then create a menu like normal and then push it onto the stack
    command_items += [menu.MenuItem(_('No Commands found'), menuwidget.goto_prev_page, 0)]

    # generic item use for things that are simple
    # you would then create a menu like normal and then push it onto the stack
    if item.info.has_key('audio'):
        items.append(menu.MenuItem(_('Audio selection'), audio_selection_menu, item))
    if item.info.has_key('subtitles'):
        items.append(menu.MenuItem(_('Subtitle selection'), subtitle_selection_menu, item))
    if item.info.has_key('chapters'):
        items.append(menu.MenuItem(_('Chapter selection'), chapter_selection_menu, item))

## 2.3.4. MenuWidget

MenuWidget or menuw as it is often labelled in the code. Is a handy utility class where most of the menu magic happens. It has most of the default utility actions for menus as well as the methods to manage the menu stack.

Common Menu Actions:

back_one_menu -- goes to the previous menu. Typically used after deleteing the current menu. see cdbackup.py for an example.

goto_main_menu -- jumps all the way back to the main menu.

List of menu stack actions:

pushmenu -- used after constructing a menu, then typically a call to refresh to display the menu.

refresh -- redraw the top item on the menu stack. It is usually called after a pushmenu call.

delete_menu -- remove the currently displayed menu.

## 2.3.5. A full example to bring it all together

    # list of items to go in the menu
    mylistofitems = []

    # a call to a function that returns an array of objects you would create
    # your menu from. for example a call to os.listdir to return a list of strings
    # containing filenames
    mylistofobjects = some_func_that_returns_you_list()

    # loop through our object list and add each item to the list for the menu
    for myobject in mylistofobjects:
        img_item = ImageItem(myobject, self)
        mylistofitems += [ img_item ]

    # handle the no objects found case if we get an empty list
    # this uses a single menu item
    if (len(mylistofitems) == 0):
        mylistofitems += [menu.MenuItem(_('No Objects found'),
                          menuw.back_one_menu, 0)]

    # create the menu using your menu list
    myobjectmenu = menu.Menu(_('My Image Objects'), mylistofitems,
                             reload_func=menuw.back_one_menu )

    # tells freevo to give rc control to the menu
    rc.app(None)

    # now we push our menu on the top of the stack and tell it to display
    menuw.pushmenu(myobjectmenu)
    menuw.refresh()

Prev | Home | Next
Events | Up | GUI Objects