wx_sugar 0.1.0

data/lib/wx_sugar/accessors.rb

@@ -0,0 +1,44 @@
+# = WxSugar - Accessors
+#
+# The default WxRuby interface has lots and lots of methods like
+#
+#  * get_position()
+#  * set_size(a_size)
+#  * is_checked()
+# 
+# and so on. Methods that retrieve set, or query attributes of an object
+# are more normally in Ruby called simply by the attribute name:
+#
+#  * position()
+#  * size = a_size
+#  * checked?
+#
+# This extension creates an alias for every WxRuby instance method that
+# begins with +get_+, +set_+ or +is_+. Note that if you are calling a
+# 'setter' method on self, you must explicitly send the message to self:
+# 
+#  # set's self size to be 100px by 100px
+#  self.size = Wx::Size.new(100, 100)
+#  # only sets the value of a local variable 'size'
+#  size = Wx::Size.new
+
+require 'wx_sugar/class_definitions.rb'
+
+module NiceRubyMethodNames
+  def self.included(klass)
+    klass.class_eval do 
+      instance_methods.grep(/^([gs]et|is)_(\w+)/) do | meth |
+        prefix, basename = $1, $2
+        case prefix
+        when 'get' : alias_method(basename, meth)
+        when 'set' : alias_method("#{basename}=", meth)
+        when 'is'  : alias_method("#{basename}?", meth)
+        end
+      end
+    end
+  end
+end
+
+WxSugar::ALL_CLASSES.each do | klass |
+  klass.class_eval { include NiceRubyMethodNames }
+end

data/lib/wx_sugar/all.rb

@@ -0,0 +1,56 @@
+# = WxSugar
+# 
+# WxSugar is a set of additions to the WxRuby API, written in pure
+# ruby. They're intended to:
+#  
+# * Make some tricky WxWidgets things easier and more consistent
+# * Reduce repetitiveness and redundancy for common tasks
+# * Make code more expressive
+# * Make code more idiomatically Rubyish
+#
+# Not everyone will like all the extensions to WxRuby here. So the
+# Sugar modules:
+#
+# * Can generally be used separately, without depending on each other
+# * Supplement rather than replace the underlying 'raw' API
+# 
+# == Using WxSugar
+# 
+# The extensions can currently be used with either WxRuby (0.6.0) or
+# WxRuby2 (the SWIG version). To use all of the extensions, simple write
+#
+#   # EITHER ... New development
+#  require 'wx'
+#   # OR ... old non-SWIG beta veresion
+#  require 'wxruby'
+# 
+#  require 'wx_sugar/all'
+#  ... 
+# 
+# If you only want to load specific behaviours, just +require+ the
+# desired extensions only
+#  
+#  require 'wx_sugar/keyword_constructors'
+#  require 'wx_sugar/acccessors'
+#
+# == Overview of extensions
+#
+# [accessors.rb] 
+#  Provide ruby-style getters, setters and question-mark methods
+# [delayed_constructors.rb] 
+#  For use with +layout+, limited independent interest
+# [event_connector.rb] 
+#  Neater syntax for connecting event listeners
+# [itemdata.rb] 
+#  Associate ruby objects with items in controls *NEEDS UPDATE*
+# [keyword_constructors.rb] 
+#  Use keyword-style hash arguments to construct widgets
+# [layout.rb] 
+#  Easy interface to using WxWidgets Sizers
+# [menu.rb] 
+#  Create and update menus without a mess of system ids
+
+%w[ accessors delayed_constructors event_connector
+    itemdata keyword_constructors layout menu ].each do | ext_feature |
+  require 'wx_sugar/' + ext_feature    
+end 

data/lib/wx_sugar/class_definitions.rb

@@ -0,0 +1,114 @@
+# The WxExtensions defines a number of contants which are groups of available
+# WxRuby classes. 
+#  
+#  ALL_CLASSES : As it sounds
+#  FRAME_CLASSES : All available WxWidgets that are standalone frames
+#  DIALOG_CLASSES : All available dialog classes
+#  MISC_WINDOW_CLASSES : Things that are displayed, but aren't 'controls'
+#  CONTROL_CLASSES : Controls that accept user input
+#  SIZER_CLASSES : Sizers
+
+module WxSugar
+  # helper function to check what widgets are available
+  ALL_CLASSES = Wx::constants.collect { | c | Wx::const_get(c) }.grep(Class)
+  
+  # named constant groups
+  def self.define_class_group(const_name, *possibles)
+    klasses = []
+    possibles.each do | poss |
+      begin
+        klasses << Wx.const_get(poss)
+      rescue NameError
+        next
+      end
+    end
+    const_set(const_name, klasses)
+  end 
+end
+
+WxSugar.define_class_group('FRAME_CLASSES',
+  'TopLevelWindow',
+  'Dialog',
+  'Frame',
+  'MDIChildFrame',
+  'MDIParentFrame',
+  'MiniFrame',
+  'SplashScreen',
+  'PropertySheetDialog',
+  'TipWindow',
+  'Wizard' )
+
+WxSugar.define_class_group('MISC_WINDOW_CLASSES', 
+  'Panel',
+  'ScrolledWindow',
+  'Grid',
+  'SplitterWindow',
+  'StatusBar',
+  'ToolBar',
+  'Notebook',
+  'Listbook',
+  'Choicebook',
+  'SashWindow',
+  'SashLayoutWindow',
+  'VScrolledWindow',
+  'WizardPage',
+  'WizardPageSimple'
+)
+
+WxSugar.define_class_group('CONTROL_CLASSES',
+  'Control',
+  'Button',
+  'BitmapButton',
+  'ToggleButton',
+  'CalendarCtrl',
+  'CheckBox',
+  'CheckListBox',
+  'Choice',
+  'ComboBox',
+  'DatePickerCtrl',
+  'Gauge',
+  'GenericDirCtrl',
+  'HtmlListBox',
+  'StaticBox',
+  'ListBox',
+  'ListCtrl',
+  'ListView',
+  'TextCtrl',
+  'TreeCtrl',
+  'ScrollBar',
+  'SpinButton',
+  'SpinCtrl',
+  'StaticText',
+  'StaticBitmap',
+  'RadioBox',
+  'RadioButton',
+  'Slider',
+  'VListBox'
+)
+
+# TODO
+WxSugar::define_class_group('DIALOG_CLASSES',
+                                 'Dialog', # Base class for common dialogs
+                                 'wxColourDialog', # Colour chooser dialog
+                                 'DirDialog', # Directory selector dialog
+                                 'FileDialog', #	File selector dialog
+                                 'FindReplaceDialog', # Search/replace dialog
+                                 'MultiChoiceDialog', # Dialog to get one or more selections from a list
+                                 'SingleChoiceDialog',# 	Dialog to get a single selection from a list and return the string
+                                 'TextEntryDialog', # 	Dialog to get a single line of text from the user
+                                 'PasswordEntryDialog', # Get a password from the user
+                                 'FontDialog', # Font chooser dialog
+                                 'PageSetupDialog', # Standard page setup dialog
+                                 'PrintDialog', # 	Standard print dialog
+                                 'MessageDialog', # Simple message box dialog
+                                 'Wizard' # A wizard dialog. 
+)
+
+WxSugar::define_class_group('SIZER_CLASSES',
+  'Sizer', # Abstract base class
+  'GridSizer', # A sizer for laying out windows in a grid with all fields having the same size
+  'FlexGridSizer', # A sizer for laying out windows in a flexible grid
+  'BoxSizer', # A sizer for laying out windows in a row or column
+  'StaticBoxSizer', # Same as wxBoxSizer, but with a surrounding static box
+  'NotebookSizer' # Sizer to use with the   'Notebook', # control
+)

data/lib/wx_sugar/delayed_constructors.rb

@@ -0,0 +1,25 @@
+require 'wx_sugar/class_definitions'
+
+win_classes = [ WxSugar::FRAME_CLASSES, 
+                WxSugar::DIALOG_CLASSES,
+                WxSugar::MISC_WINDOW_CLASSES,
+                WxSugar::CONTROL_CLASSES ].flatten
+
+# = Wx Extensions - Delayed Constructors
+# 
+# Intended mainly for use with the +layout+ extension, adds additional
+# class methods to all Window classes that return a proc that can be
+# called later to attach a Window created with the specified args to a
+# parent.
+win_classes.flatten.each do | klass |
+  # Returns a Proc object that when called with a single argument,
+  # +parent+, will return a new widget constructed according to +args+ 
+  def klass.[](*args)
+    lambda { | parent | new(parent, *args) }
+  end
+
+  # Alias for klass.[]
+  def klass.child(*args)
+    lambda { | parent | new(parent, *args) }
+  end
+end

data/lib/wx_sugar/event_connector.rb

@@ -0,0 +1,151 @@
+# = EventConnector
+# 
+# This module is meant to make it easier to connect ruby methods to
+# WxWidgets events generated by user interaction. It introduces a
+# consistent syntax for linking events to handlers, using the +listen+
+# method:
+#
+#  listen(evt, source, handler) { block }
+# 
+# The parameter +evt+ is the type of event that should be listened for,
+# for example the click of a button. To ask to listen to 'click' events,
+# pass the argument +:click+
+#
+# The parameter +source+ is the widget whose events should be listened
+# for. This might be a particular button. If no +source+ is specified,
+# and lots of widgets might generate this kind of event (for example, if
+# you have multiple buttons), it assumes that *ANY* button's clicking
+# should be handled.
+# 
+# The final part of dealing with user events is specifying what should
+# be done when the event occurs. One way is to pass the +handler+
+# argument, which should be the name of a method (as a string or symbol)
+# which will handle the event. The other way is to pass a block which
+# should be called when the event is triggered.
+# 
+# This handling method or block may, optionally, accept a single
+# argument, which will be the Event object generated by the event.
+# 
+# == Explanation
+#
+# This module is meant to take some of the pain out of hooking up event
+# handlers to objects. There are subtle differences in WxWidgets in how
+# different types of events are passed to widgets. Some events
+# (typically those fired by controls, subclasses of +CommandEvent+) are
+# passed upwards to any containing window that is interested. Others,
+# WxWidgets assumes, are only of interest to the window that generates
+# the event: most events related to frames (ActivateEvent, for example)
+# and miscellaneous windows (Sashes, ScrollWindows) fall under this
+# category.
+module EventConnector
+  module ClassMethods
+    def event_hooks()
+      @__ehooks__ ||= {} 
+    end
+
+    # look out for on_xxx methods being added, so they can be hooked up
+    # automatically when instances of this widget are created
+    def method_added(name)
+      if name.to_s =~ /^on_(.*)/
+        event_hooks[$1.intern] = name
+      end
+    end
+  end
+
+  def self.included(klass)
+    klass.extend ClassMethods
+    # need a general way to safely interpose in Module methods
+  end
+
+  # Listen to events of type +evt+ (eg. 'click', 'mousedown'), on the
+  # widget +source+, and handle it by +handler+ or +block+
+  # The handling code can be specified in a number of different ways:
+  # If neither +handler+ or +block+ is passed, then the method will
+  # attempt to attach events to a listener method called "on_EVT", where
+  # EVT is 'click', 'mousedown' etc). 
+  # 
+  #  listen(:click, my_button) # assumes on_click is defined
+  # 
+  # If handler is specified as a symbol, the listener will call this
+  # named method when the event is triggered
+  # 
+  #  listen(:click, my_button, :on_click_my_button)
+  #
+  # If a block is passed, it will be run when the event is triggered.
+  # 
+  #  listen(:click, my_button) { p "click my button" }
+  # 
+  # Methods or blocks that are defined as handlers may optionally
+  # receive one argument, the Wx event object (see the WxWidgets documentation
+  # for more details on this object):
+  # 
+  #  listen(:checkbox, my_checkbox) { | e | puts e.is_checked }
+  # 
+  # Or in a handler method:
+  #
+  #  def on_checkbox(e)
+  #    if e.is_checked
+  #      puts "The checkbox is now checked"
+  #    end
+  #  end
+  #
+  def listen(evt, source = nil, handler = nil, &block)
+    # get the WxWidget evt_xxx method that will be called for binding
+    event = "evt_#{evt}"
+    if self.respond_to?(event)
+      # try to bind to recipient's methods
+      evt_meth = method(event)
+    elsif source and source.respond_to?(event)
+      evt_meth = source.method(event)
+    else
+      Kernel.raise NameError,
+                   "Widget #{self} doesn't generate events of type '#{evt}'"
+    end
+
+    # get the block or method that will handle the event
+    begin
+      if block
+        handler_meth = block
+      elsif handler
+        handler_meth = self.method(handler)
+      else
+        handler ||= "on_#{evt}"
+        handler_meth = self.method(handler)
+      end
+    rescue NameError
+      Kernel.raise NameError, "#{self} has no handler #{handler}"
+    end
+
+    # Optionally allow block or handler methods to receive the event
+    # object as an argument
+    if handler_meth.arity == 0
+      proc = lambda { handler_meth.call() }
+    else
+      proc = lambda { | e | handler_meth.call(e) }
+    end
+
+
+    source_id = source ? source.get_id : Wx::ID_ANY
+    begin
+      # Some WxWidgest event connector methods expect the ID of the
+      # triggering widget, others don't. So we try both ways to hide
+      # this complexity
+      evt_meth.call( source_id, &proc )
+    rescue ArgumentError
+      # Try with no ID specified.
+      evt_meth.call( &proc )
+    end
+  end
+
+  # TODO - not called - needs to be done by redefining new
+  def initialize(*args)
+    super(*args)
+    self.class.event_hooks.each do | sym, handler |
+      listen(self, sym, handler)
+    end
+  end
+end
+
+class Wx::EvtHandler
+  include EventConnector
+end

data/lib/wx_sugar/itemdata.rb

@@ -0,0 +1,80 @@
+module WxSugar
+module ItemData
+    # for faked-up item data
+    def get_item_data(id)
+      data[id]
+    end
+    alias :get_client_data :get_item_data
+
+    # for faked-up item data
+    def set_item_data(id, data_obj)
+      data[id] = data_obj
+    end
+    alias :set_client_data :set_item_data
+    
+    # returns the key associated with the value +value+
+    def value_to_ident(value)
+      return nil if value.nil?
+      if value.nil?
+        return nil
+      elsif value.kind_of?(Fixnum)
+        the_id = value
+      elsif value.respond_to?(:id)
+        the_id = value.id
+      else
+        Kernel.raise "Cannot search for invalid value #{value.inspect}"
+      end
+      return index(the_id)
+    end
+    alias :object_to_item :value_to_ident
+  end
+  
+  module ListLikeItemData
+    include ItemData
+    def data()
+      @data_table ||= Array.new()
+    end
+    
+    def delete_item_data(the_data)
+      if i = value_to_ident(the_data)
+        data.delete_at(i)
+      end
+    end
+    
+    def unshift_item_data(the_data)
+      delete_item_data(the_data)
+      data.unshift(the_data)
+    end
+
+    def push_item_data(the_data)
+      delete_item_data(the_data)
+      data.push(the_data)
+    end
+    
+    def index(the_id)
+      data.each_with_index do | val, i |
+        return i if val.id == the_id
+      end
+      return nil
+    end
+  end
+
+  module HashLikeItemData
+    include ItemData
+    def data()
+      @data_table ||= Hash.new()    
+    end
+
+    def delete(the_id)
+      data.delete(the_id)
+      super(the_id)
+    end
+    
+    def index(the_id)
+      data.each do | k, val |
+        return k if val.id == the_id
+      end
+      return nil
+    end
+  end
+end