summaryrefslogtreecommitdiff
path: root/lib
diff options
context:
space:
mode:
authorTobias Grimm <tobias@e-tobi.loc>2009-02-15 21:15:49 +0100
committerTobias Grimm <tobias@e-tobi.loc>2009-02-15 21:15:49 +0100
commitb869fa2e2d4a2537d95787405c3654caf2c2d84d (patch)
treee45409678e62e5c91b7fdc8644e4220290cbd6a0 /lib
parent2bae6457006474655f971891a92341b1ae34840e (diff)
downloadvdr-plugin-scripting-master.tar.gz
vdr-plugin-scripting-master.tar.bz2
- Added RDoc documentation (Closes: #90)HEADmaster
- Added on_keypress event to menu (Closes: #96)
Diffstat (limited to 'lib')
-rw-r--r--lib/README3
-rw-r--r--lib/vdr/osd/item.rb48
-rw-r--r--lib/vdr/osd/menu.rb119
-rw-r--r--lib/vdr/osd/osdmessage.rb2
-rw-r--r--lib/vdr/osd/textview.rb2
5 files changed, 158 insertions, 16 deletions
diff --git a/lib/README b/lib/README
new file mode 100644
index 0000000..43be820
--- /dev/null
+++ b/lib/README
@@ -0,0 +1,3 @@
+Here goes some gerneral notes and get-going examples for the Ruby API...
+
+TODO
diff --git a/lib/vdr/osd/item.rb b/lib/vdr/osd/item.rb
index 4c78040..ce4a18a 100644
--- a/lib/vdr/osd/item.rb
+++ b/lib/vdr/osd/item.rb
@@ -20,20 +20,60 @@
module Vdr
module Osd
+ #
+ # An #Item represents an entry in an OSD #Menu.
+ # Each item has a #text that will be shown on the menu and a
+ # #context which can be used to store any kind of object
+ # associated with this menu item.
+ #
+ # == Example
+ #
+ # new_menu = Menu.new('A simple menu') do |menu|
+ # menu.add_item(Item.new('First Item').on_select { puts 'Item 1 selected' })
+ # new_item = Item.new('Second Item') do |item|
+ # item.context = { :first_name => 'James Tiberius', :last_name => 'Kirk' }
+ # item.on_select do |selected_item|
+ # name = selected_item.context
+ # puts "Selected #{name[:last_name]}, #{name[:first_name]}"
+ # end
+ # end
+ # menu.add_item(new_item)
+ # end
+ #
class Item < Vdr::Swig::COsdItem
+
+ # The text of the item which will be shown on its parent #Menu
attr_reader :text
+
+ # A free assignable context associated with an #Item
attr_accessor :context
- def initialize(text = nil)
+ #
+ # Creates a new item. If _text_ is given, it will become the text displayed on the
+ # parent menu for this item.
+ #
+ # Item.new('my item') #=> Creates a new item shown with 'my item'
+ # Item.new {|i| i.title = 'another item'} #=> Creates a new item and sets its title to 'another item'
+ #
+ def initialize(text = nil) # :yields: item
@text = text
super(text)
+ yield self if block_given?
+ end
+
+ # Change the item text
+ def text=(text)
+ @text = text
+ set_text(text)
end
- def on_select(&block)
- @select = block
+ # The block assigned to on_select will be executed, when
+ # the item is selected from the menu
+ def on_select(&block) # :yields: item
+ @select = block
end
- def process_key(key)
+ def process_key(key) # :nodoc:
state = super(key)
if key == Vdr::Swig::KOk
if @select
diff --git a/lib/vdr/osd/menu.rb b/lib/vdr/osd/menu.rb
index 5284726..f266923 100644
--- a/lib/vdr/osd/menu.rb
+++ b/lib/vdr/osd/menu.rb
@@ -20,57 +20,152 @@
module Vdr
module Osd
+ #
+ # The Menu class represents a basic OSD menu with a title
+ # and a bunch of items.
+ #
class Menu < Vdr::Swig::COsdMenu
+ # The title of the menu
attr_reader :title
- def initialize(title=nil)
+
+ # Creates a new menu, optionally with the given _title_
+ def initialize(title=nil) # :yields: menu
@title = title
super(@title)
@items = []
+ @red_help = @green_help = @yellow_help = @blue_help = nil
+ @keypress_event_handler = {}
yield(self) if block_given?
end
+ # Sets the _title_ of the menu
def title=(title)
@title = title
set_title(@title)
end
+ # Adds the Item _item_ to the menu
def add_item(item)
@items << item
add(item)
end
+ # Item reference returning an Item by index
def [](index)
return @items[index]
end
+ # Opens the given _menu_ as a sub menu
def open_sub_menu(menu)
add_sub_menu(menu)
end
- def process_key(key)
- state = super(key)
- case @close_request
- when :close
- return Vdr::Swig::OsBack
- when :close_all
- return Vdr::Swig::OsEnd
- end
- return state
- end
-
+ # Request to close the menu
def close
@close_request = :close
end
+ # Request to close all menus
def close_all
@close_request = :close_all
end
+ # Create and add a new item with the given _title_ and returns the added
+ # Item
def add_new_item(title)
item = Item.new(title)
add_item(item)
return item
end
+
+ # Sets the help text for the red button
+ def red_help=(text)
+ @red_help = text
+ update_help_texts
+ end
+
+ # Sets the help text for the green button
+ def green_help=(text)
+ @green_help = text
+ update_help_texts
+ end
+
+ # Sets the help text for the yellow button
+ def yellow_help=(text)
+ @yellow_help = text
+ update_help_texts
+ end
+
+ # Sets the help text for the blue button
+ def blue_help=(text)
+ @blue_help = text
+ update_help_texts
+ end
+
+ #
+ # Sets an event handler for the key press event. If _key_ is not
+ # given, the event handler will be called for any key, otherwise
+ # just for the specific key. In the latter case, no parameter is
+ # passed to the event handler.
+ #
+ # menu.on_keypress do |key|
+ # case key
+ # when :key_red
+ # puts "Red key pressed"
+ # when :key_yellow
+ # puts "Yellow key pressed"
+ # end
+ # end
+ #
+ # menu.on_keypress(:key_red) { puts 'Red key pressed' }
+ #
+ def on_keypress(key=:key_any, &event_handler) # :yield: key
+ @keypress_event_handler[key] = event_handler
+ end
+
+ # Deletes all menu items
+ def clear
+ super
+ end
+
+ # Refresh the menu. This must be called, when the menu has been changed.
+ def refresh
+ display
+ end
+
+ protected
+
+ def process_key(key) # :nodoc:
+ state = super(key)
+ case @close_request
+ when :close
+ return Vdr::Swig::OsBack
+ when :close_all
+ return Vdr::Swig::OsEnd
+ end
+ key_symbol = KEYMAP[key]
+ if @keypress_event_handler[:key_any]
+ @keypress_event_handler[:key_any].call(key_symbol)
+ end
+ if @keypress_event_handler[key_symbol]
+ @keypress_event_handler[key_symbol].call
+ end
+ return state
+ end
+
+ private
+
+ KEYMAP =
+ {
+ Vdr::Swig::KRed => :key_red,
+ Vdr::Swig::KGreen => :key_green,
+ Vdr::Swig::KYellow => :key_yellow,
+ Vdr::Swig::KBlue => :key_blue,
+ }
+
+ def update_help_texts
+ set_help(@red_help, @green_help, @yellow_help, @blue_help)
+ end
end
end
end
diff --git a/lib/vdr/osd/osdmessage.rb b/lib/vdr/osd/osdmessage.rb
index c6cfe8d..fe2401c 100644
--- a/lib/vdr/osd/osdmessage.rb
+++ b/lib/vdr/osd/osdmessage.rb
@@ -20,7 +20,9 @@
module Vdr
module Osd
+ # Provides an interface to display simple one line OSD messages
class OsdMessage
+ # Display _message_ for then given number of _seconds_
def OsdMessage.Show(message, seconds=5)
Vdr::Swig::COsdMessage.confirm(message, seconds, false)
end
diff --git a/lib/vdr/osd/textview.rb b/lib/vdr/osd/textview.rb
index 87bce65..d1fafbc 100644
--- a/lib/vdr/osd/textview.rb
+++ b/lib/vdr/osd/textview.rb
@@ -20,7 +20,9 @@
module Vdr
module Osd
+ # A TextView displays a vertical scrollable text in the OSD
class TextView < Vdr::Swig::CMenuText
+ # Creates a new text view with the given _title_ and _text_
def initialize(title, text)
super(title, text)
end