Developing for the Icon and Braille +

1. What is app.App – App is the class that all applications derive from. In the example of Hangman we are going to derive from app.App. In our __init__ function we will initialize our main menu, create our game widget, set a key handler and status function. We will also overload our onActivate Function to activate our game widget.

class Hangman(app.App):
  def __init__(self):
    app.App.__init__(self,title='Hang man',id='hangman')

    # Create Menus
    self.__initMenus__()

    # Create the game widget
    self.hm=HangmanWidget()
    self.addChild(self.hm)

    # Exit application when cancel is pressed
    self.setKeySetHandler("cancel",self.quit)

    # Set Status Function
    self.addStatusFunc(self.GetStatus,None,None)

  def onActivate(self):
    self.app.say("Hang man")
    self.hm.activate()

2. Launching an Application – Create an instance of our application and call it’s Start function.

if __name__ == "__main__":
  Hangman().start('Hang man')	

3. Widgets – Widgets are the building blocks of applications. Some of the available widgets are List, Form, Container, Menu, Text, Tree, MediaPlayer, FileBrowser, DateText and OptionList.
Create a widget:

 self.name=Text(title=“Name:”)
 self.addChild(self.name)

Activate a widget:

 self.myForm.activate()

4. Creating your own widget – You can all create your own widget by deriving from the Widget class. Just derive from widget and add Key Handlers, an onActivate function and any other needed functionality.

class HangmanWidget(widget.Widget):
  def __init__(self,id=None,title=None, brailleTitle=None):
    widget.Widget.__init__(self,id=id,title=title,brailleTitle=brailleTitle)
   # Create Widgets Menus

   # Add Key Handlers

   # Any other Widget Initilization

  def onActivate(self):
    self.app.say(‘Hangman Widget’)

5. Creating Main Menus – Inside of our Application class we call setAppMenuTitle to create our main menu. Then we can append or prepend menu items to our main menu and add a function handler for each menu item.

def __initMenus__(self):
    self.setAppMenuTitle('Hang man')
    self.appendAppMenuItem('New Game',self.NewGame)

  def NewGame(self):
    self.app.say("Start New Game")
    self.hm.NewGame()
    self.hm.activate()

6. Context Menus – Each widget can add its own menus to the menu list. Starting with the widget that has focus a menu is built from the menu items for that widget and each parent of that widget until it returns to the application.

self.prependAppMenuItem(“Menu Item”, self.menuItem1)
self.appendAppMenuItem(“Menu Item 2”, self.menuItem2)

7. How do I make it talk?
To speak a string:

  self.app.say(“Hello”)

To Say a character:

  self.app.sayCharacter(‘a’)

8. Handling Keyboard (Keypad) – To add a keypad handler call the setKeySetHandler function with the identifier for the key and its function handler.

def __init__(self):
   self.setKeySetHandler("cancel",self.quit)

 def quit(self):
   self.stop()
   return True

Common Keypad indetifiers: ok, cancel, up, down, left, right, select, selectOrOK, selectOrOKOrRight, selectOrOK_keyUp, selectOrOK_keyDown, home, end, nextWord, prevWord, nextParagraph, prevParagraph, menu, help, delete, backspace, 0, 1. . . 9, *, #

9. Handling Keys Part 2 – If you want to handle generic key presses you need to override the onKeyEvent. After passing the key event to the Widget onKeyEvent handler and making sure it is a key press, then you handle the event.

def onKeyEvent (self, event):
      # Give key event handlers first dibs
      if widget.Widget.onKeyEvent (self, event) is True:
          self.clearOnType = False
          return True

      # If it's not a key press, we don't want it
      if event.type != kbd.key_event_key_press:
          return False

      # Handle Letters
      if str(event.character).isalpha():
        self.HandleChar(str(event.character).lower())
        return True

      return False

10. Sounds – The playSound function allows you to access both system sounds or to pass a path to a sound you would like to play. It accepts wave, ogg and mp3 sounds.
System Sounds:

 self.app.playSound(‘top’)

Available Sounds: top, bottom, link, complete, error, error2, LowBattery, select, progress, start, alarm and browser_new_tab

Any Sound:

 self.app.playSound(‘/usr/share/icon/hangman/buzz1.ogg’)

11. Resources

• http://tech.aph.org/mm/wiki/Development
• http://www.python.org
• Mailing List: icon-tech@mulcahy.ws