wx_sugar 0.1.14 → 0.1.15

data/lib/wx_sugar/enumerable_controls.rb

@@ -0,0 +1,162 @@
+# This module enhances the family of GUI controls which display a list
+# of labelled items and allow the user to select one or more
+# items. Classes of this type include Wx::Choice, Wx::ComboBox and
+# Wx::ListBox. This module allows easy iteration over the contents of
+# these object using Ruby's +each+ and Enumerable methods.
+#
+# Note that including this file on its own won't enable this behaviour
+# for any classes; you should load it via the class extensions for
+# +control_with_items.rb+ and +listctrl.rb+.
+module WxSugar::EnumerableControl
+  include Enumerable
+  module ClassMethods
+    # Used internally to define a proxy object for items.
+    def collection(name, coll_class)
+      define_method(name) { coll_class.new(self) }
+    end
+  end
+
+  def self.included(klass)
+    klass.extend ClassMethods
+  end
+
+  # Iterates over the items in the control. In its simplest form, it
+  # passes the index of each item into the passed block:
+  # 
+  #  control.each | i | 
+  #    puts "String at #{i} is '#{control.string(i)}'"
+  #  end
+  #
+  # The passed block may have up to three block parameters, +i+,
+  # +string+, and +data+. The second parameter, if requested, is filled
+  # with the string label of the item within the control. The third
+  # parameter is filled with the client data associated with the
+  # item. Note that if you don't need the string or client data, it is
+  # more efficient to iterate over the indexes only.
+  def each(&block)
+    last = get_count - 1
+    case block.arity
+    when 1
+      0.upto(last) { | i | yield i }
+    when 2
+      0.upto(last) { | i | yield i, get_string(i) }
+    when 3
+      0.upto(last) { | i | yield i, get_string(i), get_item_data(i) }
+    else
+      raise ArgumentError, "Invalid number of block parameters"
+    end
+  end
+
+  # Returns the index of the item in the control corresponding to
+  # +value+. +value+ may be a string label, or it may be any ruby object
+  # set as client data to a list item. Returns +nil+ if nothing matches.
+  def index(value)
+    # -1 means 'not found' in WxWidgets
+    if value.kind_of?(String) && ( i = find_string(value, true) ) && i > -1
+      return i
+    end
+    indices = (0 ... get_count).to_a
+    return indices.find { | i | get_item_data(i) == value } 
+  end
+
+  # Appends this string to the control
+  def <<(str)
+    append(str)
+  end
+
+  # Deletes any items in the control for which the passed block
+  # evaluates to +true+.
+  def delete_if
+    deletions = []
+    each { | i | deletions << i if yield i }
+    deletions.reverse.each { | i | delete(i) }
+  end
+
+  # These classes provide proxy accessors for items within the control.
+  # ItemCollection is an abstract base class.
+  class ItemCollection 
+    attr_reader :cwi
+    def initialize(cwi)
+      @cwi = cwi
+    end
+
+    # Do a bounds-checked call of some value-fetching method +methdo+
+    # for the item +i+
+    def [](method, i)
+      unless index?(i)
+        raise IndexError, "No such item #{i} in #{self.cwi}"
+      end
+      cwi.send( method, i )
+    end
+
+    # Do a bounds-checked call of some value-setting method +methdo+
+    # for the item +i+ to value +val+
+    def []=(method, i, val)
+      unless index?(i)
+        raise IndexError, "No such item #{i} in #{self.cwi}"
+      end
+      cwi.send( method, i, val )
+    end
+
+    # over-ridden by some subclasses
+    def index?(i)
+      i >= 0 and i < cwi.get_count
+    end
+  end
+
+  # A proxy class for the item_data functions.
+  class ItemDataCollection < ItemCollection
+    def each 
+      cwi.each { | i | yield cwi.get_item_data(i) }
+    end
+
+    # Retrieves the item data for item +i+
+    def [](i)
+      super :get_item_data, i
+    end
+
+    # Sets the item data for +i+ to be +obj+
+    def []=(i, obj)
+      super :set_item_data, i, obj
+    end
+  end
+
+  # A proxy class for classes that use get/set_string to set labels,
+  # inheriting from ControlWithItems.
+  class StringsCollection < ItemCollection
+    def each 
+      cwi.each { | i | yield cwi.get_string(i) }
+    end
+
+    # Retrieves the string for item +i+
+    def [](i)
+      super :get_string, i
+    end
+
+    # Sets a string within the control
+    def []=(i, str)
+      super :set_string, i, str
+    end
+  end
+
+  # Fetching strings from a ListCtrl
+  class ListItemTextCollection < ItemCollection
+    def each 
+      cwi.each { | i | yield cwi.get_item_text(i) }
+    end
+
+    # Retrieves the string for item +i+
+    def [](i)
+      super :get_item_text, i
+    end
+
+    # Sets a string within the control
+    def []=(i, str)
+      super :set_item_text, i, str
+    end
+
+    def index?(i)
+      i >= 0 and i < cwi.get_item_count
+    end
+  end
+end

data/lib/wx_sugar/version.rb

@@ -1,3 +1,3 @@
 module WxSugar
-  VERSION = '0.1.14'
+  VERSION = '0.1.15'
 end

data/lib/wx_sugar/wx_classes/control_with_items.rb

@@ -0,0 +1,23 @@
+require 'wx_sugar/enumerable_controls'
+
+# Uses WxSugar::EnumerableControl to provide methods for iterating over
+# the items within the control. 
+# 
+# Instances of all ControlWithItems classes then have an +each+ and an
+# +index+ method, plus all the methods supplied by Enumerable, such as
+# +collect+, +find+ and +any?+.
+#
+# They also have a +strings+ method which can be used as an array-like
+# accessor to the labels of the string:
+# 
+#  choice = Wx::Choice.new(parent, :choices => %w|foo bar|)
+#  choice.strings[1] # bar
+#  choice.strings[0] = 'quux' # set the first item in the control
+#
+# Similarly, there is a +data+ method to access the item data associated
+# with the control by numeric index.
+class Wx::ControlWithItems
+  include WxSugar::EnumerableControl
+  collection :strings, StringsCollection
+  collection :data, ItemDataCollection
+end

data/lib/wx_sugar/wx_classes/listctrl.rb

@@ -0,0 +1,38 @@
+require 'wx_sugar/enumerable_controls'
+
+class Wx::ListCtrl
+  include WxSugar::EnumerableControl
+  collection :strings, ListItemTextCollection
+  collection :data, ItemDataCollection
+
+  alias :get_string :get_item_text
+  alias :set_string :set_item_text
+  alias :get_count :get_item_count
+
+  # Appends 
+  def <<(str)
+    insert_item(get_item_count, str)
+  end
+
+  # Emulate the ControlWithItems find_string method. Like the cognate
+  # method, it returns -1 if the string was not found.
+  def find_string(str, case_sensitive = false)
+    if case_sensitive
+      find_string_sensitively(str)
+    else
+      find_item(-1, str)
+    end
+  end
+
+  private
+  # Implement a case-sensitive search for ListCtrl (default find_item
+  # with string is always case-insensitive)
+  def find_string_sensitively(str)
+    start = -1
+    until found = find_item(start, str) and get_item_text(found) == str
+      break if found == -1 # Not found at all
+      start = found + 1
+    end
+    return found
+  end
+end

data/lib/wx_sugar/wx_classes/treectrl.rb

@@ -1,13 +1,34 @@
 class Wx::TreeCtrl
   # Recurses over the tree item +start_item+ and its descendants,
-  # yielding each Wx::TreeItemId in turn into the passed block. This
-  # TreeItemId can be used as an argument to many other methods within
-  # TreeCtrl (for example, get_item_text).
+  # yielding each item in the tree in turn into the block. If
+  # +start_item+ is not specified, this method will recurse over every
+  # item within the tree, starting with the root item.
   #
-  # If +start_item+ is not specified, this method will recurse over
-  # every item within the tree, starting with the root item.
+  # In its simplest form, the method accepts a block with one parameter,
+  # which will be the TreeItemId of the item. This is an opaque integer
+  # value which uniquely identifies the tree item. It can be used as an
+  # argument to many other methods within TreeCtrl (for example,
+  # get_item_text).
+  #
+  # The block passed to +traverse+ may optionally receive two additional
+  # parameters, +text+ and +data+. If these are specified, they will be
+  # filled with the text label for the item and any ruby item data
+  # associated with the item, respectively.
   def traverse(start_item = self.get_root_item, &block)
-    block.call(start_item)
+    case block.arity
+    when 1
+      block.call(start_item)
+    when 2
+      block.call(start_item, 
+                 get_item_text(start_item))
+    when 3
+      block.call(start_item, 
+                 get_item_text(start_item), 
+                 get_item_data(start_item))
+    else
+      raise ArgumentError, "Invalid number of block parameters"
+    end
+
     if has_children(start_item)
       child, cookie = get_first_child(start_item)
       while child.nonzero?

data/lib/wx_sugar/wx_classes/window.rb

@@ -18,7 +18,7 @@ class Wx::Window
   #  # Example - find a StaticText with a label matching /foo/
   #  a_frame.find_window(Wx::StaticText) { | tx | tx.label =~ /foo/ }
   def find_window(a_class = Wx::Window, &block)
-    descendants.grep(a_class).detect(&block)
+    get_descendants.grep(a_class).detect(&block)
   end
 
   # Returns the window's current size as a two element array
@@ -32,4 +32,19 @@ class Wx::Window
     pos = get_position
     return pos.x, pos.y
   end
+
+  # Tests if the GUI object has the given window style +style+. Returns
+  # +style+ if it has been applied, or +nil+ if the window does not have
+  # that style.
+  # 
+  #  combobox.has_style?(Wx::CB_READONLY)
+  #  textctrl.has_style?(Wx::TE_MULTILINE)
+  # 
+  # Note that you should at least know that the constant +style+ is
+  # applicable to self. You may get false positives if testing a widget
+  # for a style belonging to an irrelevant class, e.g. testing a
+  # Wx::TextCtrl for the WX::CB_READONLY style.
+  def has_style?(style)
+    ( get_window_style & style ).nonzero?
+  end
 end

data/lib/wx_sugar.rb

@@ -37,22 +37,25 @@
 # 
 # The following are the WxSugar behaviours that are available. In
 # general you require one of these extensions, it modifies the behaviour
-# of all relevant Wx classes, and affects all new instances.
+# of all relevant Wx classes, and affects all new instances. The
+# following are listed in order of interest
 #
 # [accessors] 
 #  Provide ruby-style getters, setters and question-mark methods
-# [delayed_constructors] 
-#  Required by +layout+, of limited independent interest
-# [event_connector] 
-#  Neater syntax for connecting event listeners
 # [keyword_constructors] 
 #  Use keyword-style hash arguments to construct widgets
+# [event_connector] 
+#  Neater syntax for connecting event listeners
 # [layout] 
 #  Easy interface to using WxWidgets Sizers to arrange controls
-# [menu] 
-#  Create and update menus without a mess of system ids
 # [wx_classes]
 #  Useful ruby methods added to individual Wx classes.
+# [menu] 
+#  Create and update menus without a mess of system ids
+# [enumerable controls]
+#  Treat list-like GUI controls as Ruby enumerables with an +each+ method
+# [delayed_constructors] 
+#  Required by +layout+, of limited independent interest
 #
 # === Deprecated extensions
 #

data/samples/sugar-sample.rb

@@ -18,9 +18,12 @@ class SugaryFrame < Wx::Frame
     add( Wx::Panel, :proportion => 1 ) do | panel |
       # a text control
       panel.background_colour = Wx::Colour.new(200, 150, 100) 
-      panel.add( Wx::TextCtrl[ :value => 'initial value', 
+      tx = panel.add( Wx::TextCtrl[ :value => 'initial value', 
                                :style => Wx::TE_MULTILINE,
                                :size  => [200, 300]  ] )
+      # test if a style is applied to a control
+      tx.has_style?(Wx::TE_MULTILINE) # true
+      tx.has_style?(Wx::TE_READONLY) # false
     end
 
     # use a nested grid sizer to arrange bottom area
@@ -32,8 +35,15 @@ class SugaryFrame < Wx::Frame
       end
 
       # a drop down
-      choices = %w[ nasty nice ]
-      add( Wx::Choice[ :choices => choices ], :padding => 4)
+      choices = add( Wx::Choice[ :choices => %w[ nasty nice salty ] ], 
+                     :padding => 4 )
+      choices << 'sweet'
+      # access client data via a collection
+      choices.data[3] = Object.new
+      # iterate over a dropdown's content simply
+      choices.each { | i | nil }
+      # iterate over a dropdown's full content
+      choices.each { | i, str, data | nil }
 
       # another button
       add( Wx::Button[ :label => 'foo' ] ) do | button |

metadata

@@ -3,8 +3,8 @@ rubygems_version: 0.9.0
 specification_version: 1
 name: wx_sugar
 version: !ruby/object:Gem::Version 
-  version: 0.1.14
-date: 2007-03-22 00:00:00 +00:00
+  version: 0.1.15
+date: 2007-04-03 00:00:00 +01:00
 summary: Syntax extensions for WxRuby.
 require_paths: 
   - lib
@@ -36,6 +36,7 @@ files:
   - lib/wx_sugar/all.rb
   - lib/wx_sugar/class_definitions.rb
   - lib/wx_sugar/delayed_constructors.rb
+  - lib/wx_sugar/enumerable_controls.rb
   - lib/wx_sugar/event_connector.rb
   - lib/wx_sugar/itemdata.rb
   - lib/wx_sugar/keyword_classes.rb
@@ -46,6 +47,8 @@ files:
   - lib/wx_sugar/wx_classes
   - lib/wx_sugar/wx_classes.rb
   - lib/wx_sugar/wx_classes/colour.rb
+  - lib/wx_sugar/wx_classes/control_with_items.rb
+  - lib/wx_sugar/wx_classes/listctrl.rb
   - lib/wx_sugar/wx_classes/position.rb
   - lib/wx_sugar/wx_classes/size.rb
   - lib/wx_sugar/wx_classes/treectrl.rb