wx_sugar 0.1.0

data/lib/wx_sugar/layout.rb

@@ -0,0 +1,231 @@
+# = WxSugar - Layout
+# 
+# The *Layout* extension provides an easier interface to WxWidgets
+# Sizers, in order to create GUI widget layouts that adapt as windows
+# are resized and widgets added and deleted.
+# 
+# == Introduction
+#
+# In most GUI applications, rather than specifying the size and position
+# of widgets in fixed pixels, it's desirable to specify their *relative*
+# position and size and let the GUI adapt the actual display to reflect:
+#
+# * The varying size of standard window chrome (title and status bars,
+#   standard buttons etc) across different OSes and themes
+# * User resizing of application windows
+# * Event-driven GUI updates (showing, altering or removing widgets)
+# 
+# It is possible but very laborious to handle all of these
+# manually. Fortunately, WxWidgets and WxRuby include the flexible and
+# powerful _Sizer_ classes. Unfortunately, getting the desired effect
+# with Sizers can be a tricky matter of trial and error. The +Arranger+
+# module aims to simplify the use of sizer-based layouts.
+# 
+# == Overview
+# 
+# A limited number of WxWidgets windows can contain other controls;
+# these include Wx::Panel, Wx::Frame (and descendants) and Wx::Dialog
+# (and descendants). To create flexible, resizeable layouts of controls
+# within these windows involves a few simple steps when this module is
+# in effect.
+# 
+# 1. Create the container window as normal
+# 2. Declare the layout strategy desired for that window by calling one
+#    of its +arrange_+ methods
+# 3. Add child widgets to the container using its +add+ method, passing
+#    any hints about how the child widget should be resized.
+#
+# Here's a simple example that lays out three checkboxes side-by-side,
+# with some padding space around them
+#
+#  require 'wx_extensions/layout'
+#  ...
+#  panel = Wx::Panel.new(parent, -1) # create the container
+#  panel.arrange_horizontally(:padding => 4) # specify layout strategy
+#  panel.add( Wx::Checkbox.new(panel, -1, 'item A') ) # add item,
+#  panel.add( Wx::Checkbox.new(panel, -1, 'item B') ) # another,
+#  panel.add( Wx::Checkbox.new(panel, -1, 'item C') ) # and another
+
+require 'wx_sugar/class_definitions'
+
+module WxSugar
+module Arranger
+  def self.included(klass)
+    unless klass.instance_methods.include?('add')
+      # don't over-write methods in sizer
+      klass.module_eval { alias_method :add, :nest }
+    end
+  end
+  
+  attr_accessor :padding
+  
+  # Returns the underlying sizer currently being used by this
+  # container. User code should not normally need to call this method.
+  def current_sizer()
+    if @current_sizer
+      return @current_sizer 
+    elsif sizer = self.get_sizer
+      return sizer
+    else
+      return @current_sizer = Wx::BoxSizer.new(Wx::VERTICAL)
+    end
+  end
+  
+  # Set the main or current sizer of this container window to be
+  # +a_sizer+. If no block is given, then +a_sizer+ is used as the main
+  # default sizer for this window. Note that this form should only be
+  # called once, *before* any child widgets have been added to the
+  # container.
+  #
+  # If a block is passed, then the +a_sizer+ is nested within the
+  # container window's main default sizer. For the duration of the block
+  # Widgets added to the container will be added to the nested sizer. If
+  # the nested form is called, +layout+ may contain a layout hint
+  # hash. This can contain the key +:proportion+, which should specify
+  # the integer resizing proportion for this nested sizer within the
+  # container's main arrangement.
+  def arrange(a_sizer, layout = {})
+    # run as a subordinate block
+    if block_given? and @current_sizer
+      superior_sizer, @current_sizer = @current_sizer, a_sizer
+      yield(self)
+      @current_sizer = superior_sizer
+      proportion = layout[:proportion] || 0
+      superior_sizer.add( a_sizer, proportion, 
+                          Wx::EXPAND|Wx::ALL|Wx::ADJUST_MINSIZE, padding)
+    # set as main sizer            
+    else
+      @current_sizer = a_sizer
+      yield(self) if block_given?
+      self.set_sizer(a_sizer)
+    end
+  end
+
+  # Add +child+ to the container window's layout, sizing and placing it
+  # according to +layout_hints+
+  #
+  # Layout hints may contain the keys
+  #  :proportion
+  #  :minsize
+  def nest(child, layout_hints = {})
+    child  = build_child(child)
+    layout = hints_to_constants(layout_hints)
+    proportion = layout_hints[:proportion] || 0
+    siz = self.current_sizer()
+    padding = layout_hints[:padding] || @padding
+    siz.add(child, proportion, layout, padding || 0)
+    siz.layout()
+    
+    yield child if block_given?
+    return child
+  end
+
+  
+  def arrange_vertically( layout = { }, &block )
+    arrange_linear( layout.merge( :direction => :vertical ), &block )
+  end
+
+  def arrange_horizontally( layout = { }, &block )
+    arrange_linear( layout.merge( :direction => :horizontal ), &block )
+  end
+  
+  def arrange_linear( layout = { }, &block)
+    @padding = layout[:padding] if layout[:padding]
+    if layout[:direction].to_s.downcase == 'horizontal'
+      direction = Wx::HORIZONTAL
+    elsif layout[:direction].to_s.downcase == 'vertical'
+      direction = Wx::VERTICAL
+    else
+      Kernel.raise ArgumentError, 
+                   "Unknown direction '#{layout[:direction].inspect}'"
+    end
+    
+    if layout[:label]
+      sb = Wx::StaticBox.new( self, -1, layout[:label] )
+      sizer = Wx::StaticBoxSizer.new( sb, direction )
+    elsif layout[:box]
+      sb = Wx::StaticBox.new( self, -1, '' )
+      sizer = Wx::StaticBoxSizer.new( sb, direction )
+    else
+      sizer = Wx::BoxSizer.new(direction)
+    end
+    arrange(sizer, layout, &block)
+  end
+  
+  # takes hash arguments +layout+
+  # 
+  #  :rows - integer, number of rows (mandatory, see below)
+  #  :cols - integer, number of columns (mandatory, see below)
+  #  :vgap - integer, extra vertical space between each child (optional)
+  #  :hgap - integer, extra horizontal space between each child (optional)
+  #
+  # At least one of +:rows+ and +:cols+ must be specified. If one is not
+  # specified, the other will be calculated dynamically based on the
+  # total number of child widgets added.
+  # 
+  def arrange_grid(layout, &block)
+    unless layout[:rows] or layout[:cols]
+      Kernel.raise ArgumentError,
+                   "At least one of :rows or :cols must be specified"
+    end
+
+    if layout[:padding]
+      layout[:vgap] = layout[:hgap] = layout[:padding]
+    end
+
+    # wxruby wants them in this order, and with nought if null
+    args = [ :rows, :cols, :vgap, :hgap ].map { | arg | layout[arg] or 0 }
+    sizer = Wx::FlexGridSizer.new(*args)
+    arrange( sizer, layout, &block )
+  end
+  
+  # Construct a WxWidget as specified by +child+ to add to my arrangement 
+  def build_child(child)
+    case child
+    when Proc # delayed constructor
+      child = child.call(self)
+    when Class # bare class
+      child = child.new(self)
+    when Wx::Window, Wx::Sizer # ready-to-go widget
+      child = child
+    else
+      Kernel.raise ArgumentError,
+                   "Cannot add #{child.inspect} to #{self}"
+    end
+  end
+
+
+  # Convert a hash of layout hints to WxWidgets Sizer constants
+  def hints_to_constants(layout_hints)
+    layout = Wx::ALL
+    
+    if layout_hints[:minsize]
+      layout = layout | Wx::ADJUST_MINSIZE|Wx::EXPAND
+    end
+    if layout_hints[:expand] || layout_hints[:proportion]
+      layout = layout | Wx::EXPAND
+    end
+
+    
+    if layout_hints[:align]
+      begin
+        align_const = Wx::const_get('ALIGN_' << layout_hints[:align].to_s.upcase)
+        layout = layout | align_const
+      rescue NameError
+        Kernel.raise ArgumentError,
+                     "Invalid align argument #{layout_hints[:align]}"
+      end
+    end
+    layout
+  end
+end
+end
+
+win_classes = [ WxSugar::FRAME_CLASSES, 
+                WxSugar::DIALOG_CLASSES,
+                WxSugar::SIZER_CLASSES,
+                WxSugar::MISC_WINDOW_CLASSES ].flatten
+
+win_classes.each do | klass |
+  klass.class_eval { include WxSugar::Arranger }
+end                

data/lib/wx_sugar/menu.rb

@@ -0,0 +1,186 @@
+module Wx::Extensions
+  module EasyMenuName
+    def clean_name(str)
+      str.gsub(/\&/, '')
+    end
+    
+    def internal_name(str)
+       str.gsub(/\s+/, "_").gsub(/\W/, "").downcase
+    end
+  end
+  
+  module EasyMenuBar
+    include EasyMenuName
+    attr_accessor :target, :source
+    def connect(source, target = source)
+      self.source = source
+      # source.set_menu_bar(self)
+      self.target = target
+    end
+    
+    def add_menu(title)
+      menu = Wx::Menu.new()
+      menu.target  = self.target
+      menu.source  = self.source
+      yield menu
+      append(menu, title)
+      # these are here because wxruby 0.6.0 doesn't 
+      # support get_menu and find_menue
+      menu_labels << internal_name(title)
+      menu_menus << menu
+      menu
+    end
+
+    def menu_menus()
+      @menu_menus||= []
+    end
+    
+    def menu_labels()
+      @menu_labels ||= []
+    end
+    
+    def get_menu(idx)
+      menu_menus[idx]
+    end
+    
+    # only used if find_menu is not available in WxRuby
+    def find_menu(str)
+      menu_labels.index( internal_name(str) ) || Wx::NOT_FOUND
+    end
+    
+    # Return the Menu item corresponding to +menu_id+. This can be a zero-based
+    # integer specifying the menu's offset within the MenuBar, or a string
+    # title, with or without accelerator key.
+    def [](menu_id)
+      case menu_id
+      when Integer
+        index = menu_id
+      when String
+        # a_MenuBar.find_menu missing in wxruby 0.6.0
+        index = find_menu(menu_id)
+        raise RuntimeError, "No menu called #{menu_id}" if index == Wx::NOT_FOUND
+      else
+        raise ArgumentError, "Bad menu specifier #{menu_id.inspect}"       
+      end
+      get_menu(index)
+    end
+  end
+  
+  module EasyMenu
+    include EasyMenuName
+    @base_id = 1000
+    def self.next_id()
+      @base_id = @base_id ? @base_id + 1 : 2000
+    end
+
+    # The target window for menu events from this source
+    attr_accessor :target, :source
+    def menu_ids(*args)
+      @menu_ids ||= {}
+    end
+    
+    def next_id()
+      EasyMenu.next_id()
+    end
+    
+    def [](ident)
+      case ident
+      when String, Symbol
+        menu_id = menu_ids[internal_name(ident)] or
+          raise RuntimeError, "Not found #{ident} #{menu_ids.inspect}"
+      when Fixnum
+        menu_id = ident
+      end
+      # find_item(menu_id)
+    end
+    
+    # adds the item +command_str+ to the menu, with the optional
+    # shortcut key +command_key+, and sets it to run the associated
+    # block when the menu item is chosen. The menu item can later be
+    # referred to by the symbol with the commands name with special
+    # characters removed andspaces turned to underscores. For
+    # example, "Save Project" becomes :save_project
+    # 
+    # The handler event can be specified in a number of ways:
+    # 1. Passing a block, which can optionally receive an event parameter
+    # 2. Passing a :handler option, which can be a method name in the target,
+    #    or a Proc or BoundMethod object.
+    # 3. Simply defining a method in the +target+ called on_xxxx, where xxxx
+    #    is the lower-case name of the menu item with special characters removed.
+    #
+    # So, if creating a menu item called 'Save Project', simply define a method
+    # called +on_save_project+ in the event target.
+    def add(command_str, options = {}, &block)
+      ident = internal_name(command_str)
+      const = options[:sys_id] || self.next_id()
+      menu_ids[ident] = const
+      
+      # Find out how the handler is defined:
+      # Using an explicit block?
+      if block
+        handler = block
+      # Specifying a :handler in the options hash
+      elsif meth = options[:handler]
+        # .. a method object?
+        if meth.respond_to?(:call)
+          handler = meth
+        # .. or a method name?
+        else
+          handler = target.method(meth)
+        end
+      # or else try guessing name from among target's methods
+      else
+        handler = target.method('on_' << ident)
+      end
+      
+      if options[:checked]
+        itemtype = Wx::ITEM_CHECK
+      elsif options[:radio]
+        itemtype = Wx::ITEM_RADIO
+      else
+        itemtype = Wx::ITEM_NORMAL
+      end
+      
+      command_key = options[:shortcut] || ''
+      append(const, "#{command_str}\t#{command_key}", "", itemtype)
+      # define the WxWidgets handler, passing a event object if required
+      if handler.arity == 1
+        source.evt_menu(const) { | e | handler.call(e) }
+      else
+        source.evt_menu(const) { handler.call() }
+      end
+      return ident
+    end
+
+    def add_separator
+      append_separator
+    end
+    
+    # pass a series of symbol idents eg :save_project, :close
+    def enable_items(*idents)
+      idents.each { | ident | self.enable( self[ident], true ) }
+    end
+    alias :enable_item :enable_items
+
+    def disable_items(*idents)
+      idents.each { | ident | self.enable( self[ident], false ) }
+    end
+    alias :disable_item :disable_items
+
+    def check_items(*idents)
+      idents.each { | ident | self.check( self[ident], true ) }
+    end
+    alias :check_item :check_items
+
+    def uncheck_items(*idents)
+      idents.each { | ident | self.check( self[ident], false ) }
+    end
+    alias :uncheck_item :uncheck_items
+  end
+  class Wx::MenuBar
+    include EasyMenuBar
+  end
+  class Wx::Menu
+    include EasyMenu
+  end 
+end

metadata

@@ -0,0 +1,46 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.10
+specification_version: 1
+name: wx_sugar
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-09-07
+summary: Syntax extensions for WxRuby.
+require_paths: 
+  - lib
+email: alex@pressure.to
+homepage: http://www.pressure.to/qda/
+rubyforge_project: weft-qda
+description: Ruby-ifies the ruby API for WxRuby.
+autorequire: 
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+    - 
+      - ">="
+      - !ruby/object:Gem::Version 
+        version: 1.8.1
+  version: 
+platform: ruby
+authors: 
+  - Alex Fenton
+files: 
+  - lib/wx_sugar/accessors.rb
+  - lib/wx_sugar/all.rb
+  - lib/wx_sugar/class_definitions.rb
+  - lib/wx_sugar/delayed_constructors.rb
+  - lib/wx_sugar/event_connector.rb
+  - lib/wx_sugar/itemdata.rb
+  - lib/wx_sugar/keyword_classes.rb
+  - lib/wx_sugar/keyword_constructors.rb
+  - lib/wx_sugar/layout.rb
+  - lib/wx_sugar/menu.rb
+test_files: []
+rdoc_options: []
+extra_rdoc_files: []
+executables: []
+extensions: []
+requirements: []
+dependencies: []