wxruby-ruby19 1.9.10-x86-darwin-9 → 2.0.0-x86-darwin-9

data/README

@@ -1,297 +1,198 @@
-README for wxruby2
+= README for wxRuby version 2.0
 
-Version 1.9.x
+== Introduction
 
-This is wxruby2, the second generation of wxRuby, a library 
-that allows Ruby programs to use the wxWidgets GUI toolkit. 
-It is released under a permissive MIT-style license
-(see the LICENSE file for details).
+wxRuby is a cross-platform GUI library for Ruby, based on the wxWidgets
+GUI toolkit for C++. It uses native widgets wherever possible, providing
+the correct look, feel and behaviour to GUI applications on Windows, OS
+X and Linux/GTK. wxRuby aims to provide a comprehensive solution to
+developing professional-standard desktop applications in Ruby. 
 
-This version is a beta release, in preparation for a stable release of
-wxruby version 2.0.
+== Installing wxRuby
 
-------------------------FAQ---------------------------
+wxRuby is distributed as pre-compiled binaries and source from the
+project's site on Rubyforge: http://wxruby.rubyforge.org/
 
-- What platforms and operating systems are supported in wxRuby2?
+For the majority of users, installation simply requires running 'gem
+install wxruby' on the command line. See INSTALL for further
+information.
 
-  Currently the following are fully supported:
+== wxRuby licence
 
-  Windows NT/2000/XP/Vista (i686)
-  OS X 10.4+ (i686 and PowerPc)
-  Linux (i686 + AMD-64)
+wxRuby is free and open-source. It is distributed under a liberal
+licence which is compatible with both free and commercial development.
+See LICENSE for more details.
 
-  It is unlikely that support for old Windows OS's (3.1, 95, 98, ME)
-  will be added to wxRuby2 in the near future, as these operating
-  systems have very limited support for Unicode.
+== FAQ
 
-- Why would I choose wxruby over FXRuby, Ruby/GTK, or one of the other 
-   GUI toolkits? Isn't wxruby arriving "too late"?
-   
-   There are several great GUI toolkits available for Ruby, but we 
-   like wxruby better because it has a combination of features that no 
-   other toolkit has:
-   
-     - Cross-platform (MSWindows, Mac OS X, Linux)
-     - Native widgets when possible
-     - Provides a wide selection of widgets
-     - Simple license that is compatible with proprietary and Free Software 
-     - Mature foundation (wxWidgets has been around for over 10 years)
-
-   The really big feature is native widgets. The only other cross-platform 
-   toolkits that use native widgets are either limited (Tk) or expensive if 
-   you want to develop proprietary software (Qt). We are not saying that 
-   those toolkits are bad! Just that wxruby offers a unique set of 
-   features.
-   
-- Why are native widgets important or helpful?
-
-   For one thing, it means that end-users do not have to adjust to a 
-   "foreign" interface. It also ensures maximum compatibility with 
-   "assistive technology" such as screen readers for blind users. 
-   It also allows apps to respect any themes the user may have chosen 
-   through their operating system. No matter how hard a toolkit may try 
-   to emulate a particular UI, there will always be differences in the 
-   look or behavior.
-   
-- How does wxruby2 relate to wxruby (and the wxruby 0.6.0 release)?
+=== What platforms and operating systems are supported in wxRuby2?
 
-   wxruby2 is the "next generation" of wxruby. It is being developed 
-   by the same wxruby team, and is intended to replace the older 
-   code base. wxruby2 is built using SWIG, a powerful tool that makes 
-   it much easier to create and maintain wrappers around C/C++ libraries.
-   
-- Why should I use wxruby2 instead of wxruby?
+Currently the following are fully supported:
 
-   First, because development on the original wxruby codebase has stopped. 
-   Everyone is working on wxruby2, so it will continue to improve. Beyond 
-   that, wxruby2 has these advantages over wxruby 0.6.0:
-   
-     - Available as binary gems for MSWindows, OS X, and Linux (GTK)
-	 - Support for more classes, and more methods within classes
-	 - Unicode support
-	 - Vastly improved support for OS X
-	 - Looks much better under Linux because it uses GTK+2
-	 - Simpler and more permissive license 
-	 - Wraps wxWidgets 2.8.7 instead of the older 2.4 series
-	 
-- Is wxruby2 ready for "production" use?
-
-  Yes, pretty much. This is a beta release, and there may be some bugs
-  in some methods, or memory leaks. This release includes all the
-  classes and features that are proposed for inclusion in wxruby 2.0.
-
-  It is considerably more stable and fully-featured than the old 0.6.0
-  release, which was never really stable enough for heavy-duty
-  production use.
-   
-- Does wxruby2 support the Xxx class?
+* Windows NT/2000/XP/Vista (i686, MSVC and MingW)
+* OS X 10.4+ (i686 and PowerPc)
+* Linux (i686 + AMD-64)
 
-   See the "Documentation" section of the README file, or check the 
-   wxruby web site: http://wxruby.org
+Support for other platforms is not being actively developed at present,
+but patches are welcome. It is likely to be much simpler to get wxRuby
+working on similar modern systems (eg FreeBSD or Solaris with GTK) than
+on legacy systems (eg Windows 98, Mac OS 9).
+
+=== Why would I choose wxruby over FXRuby, Ruby/GTK, Shoes etc?
    
-- How are the wxruby 0.6.0 and wxruby2 licenses different?
-
-  wxruby 0.6.0 was released under the wxWindows license, which is a 
-  modified LGPL. It is a good, fair license, allowing use in both Free 
-  Software and proprietary applications. However, it is long and complex, 
-  and is more appropriate for compiled code. wxruby2 is available under a 
-  *very* simple MIT-style license, which allows just about any use with 
-  very few restrictions.
+There are several fine GUI toolkits available for Ruby, but we consider
+that wxRuby offers a combination of features that no other toolkit can match:
    
-- I am getting an error trying to compile wxruby2
-
-  Please double-check the requirements. You may be using the wrong
-  version of SWIG, wxWidgets, or some other tool. Double-check the
-  instructions on the wxRuby wiki (http://wxruby.rubyforge.org/)
-  
-  If you need help, please ask your question on the wxruby mailing list 
-  (see the link at http://wxruby.org). 
-
-- I am getting an error trying to run any wxruby2 application, such as 
-  the samples that are included in the gem.
-  
-  If you are using Linux, be sure you have configured your system to 
-  have RUBYOPT=-rubygems. This can be done in .bashrc or /etc/environment, 
-  depending on your distribution and preferences. [More details to follow].
-  
-- Why aren't the wx network, file, date, database and other non-GUI
-  classes supported?
-
-  Because Ruby has its own versions of each of them, providing
-  cross-platform abstractions of these functions with familiar syntax
-  and methods. We assume you are writing your application in Ruby, so it
-  makes sense to keep as much code as possible in Ruby. We have only
-  wrapped the wx classes that are necessary to write GUI code.
-
-  There may be some advantages to porting the Wx network classes into
-  ruby, if they work better with multi-(native)-threaded code. This is
-  currently under evaluation.
-  
-- Why has it taken so long for wxruby2 to be released?
-
-  Nobody is getting paid to develop wxruby, so each of the wxruby developers 
-  are limited in the amount of time they can dedicate to the project. We are 
-  always looking for more volunteers to help code, test, document, manage 
-  the bug list, handle publicity, or do other necessary chores.
-  
-  Wrapping wx is a big project that requires a wide variety of skills. As of 
-  February 2008, the wxRuby project has over 100,000 lines of code, including 
-  ruby, C++, and SWIG scripts. If we weren't using SWIG it would be far bigger.
-
-
-For more details, see the project home page:
-  http://wxruby.org/
-
-
-------------------------USING WXRUBY---------------------------
-INSTALLING:
-
-wxRuby is available as binary gems for MS Windows, Mac OS X, and Linux
-with GTK+ 2. Unless you wish to work on wxRuby itself, we strongly
-recommend installing the gem rather than building from source.
-
-REQUIREMENTS TO CREATE AND RUN WXRUBY APPS:
-
-- Ruby 1.8
-- MS Windows NT/2000/XP/Vista, Mac OS X 10.4+, or Linux with GTK+ 2, 
-
-- On Windows, gdiplus.pll and msvcp71.dll. These are available on most
-  systems, but can be downloaded and installed for free from the
-  internet
-- On Linux, libgstreamer. This can be installed from most package sources
-
-SAMPLES:
-
-There is a samples/ directory containing many small sample wxRuby apps 
-that demonstrate how to use various classes. A few samples do not work 
-across all platforms at this time.
-	
-The bigdemo sample is fairly comprehensive, but not all of the 
-sections work on all platforms. 
-
-
-WRITING YOUR OWN WXRUBY APP:
-
-To use wxruby-swig in your app, use:
-  require 'wx'
-  
-samples/minimal.rb can be used as a template for creating your 
-own wxruby application.
-
-
-DOCUMENTATION:
-
-- wxRuby-specific API documentation can be found here:
-
-    http://wxruby.org/doc/
-	
-   (Note: This documentation is auto-generated from the C++ wxWidgets API
-   docs. There are some broken links, some sample code in C++, and some
-   sections which do not apply to ruby. The documentation is continually
-   being improved.)
-
-- The latest version of the documentation can be downloaded from the
-  wxRuby 'Files' section on Rubyforge.
-
-  http://www.rubyforge.org/frs/?group_id=35
-
-- Tables summarizing which wx classes are and are not supported can 
-  be found here:
-  
-    http://wxruby.org/wiki/wiki.pl?ClassesSupportedByCategory
-	
-- Most wxWidgets and wxPython tutorials and references can also be used, if 
-  you remember that wxRuby uses ruby_style_naming for methods and variables 
-  instead of MixedCase as used by wxWidgets.
-  
-
-
-API DIFFERENCES FROM WXWIDGETS:
-- In many cases, wxRuby follows the lead of wxPython (or in some cases, 
-  wxPerl), adjusting certain method calls when the C++ style doesn't fit 
-  dynamic languages.
-- Since initialize is reserved in ruby, use SplitterWindow#init instead.
-- Many wx classes have not been wrapped because native ruby classes work 
-  as well or better. These include wxDateTime, wxString, networking 
-  classes, database classes.
-- log_message and log_status take a single string parameter, 
-  rather than a format string followed by additional values 
-  to be inserted. Use Ruby's sprintf if required.
-
-----------------------COMPILING WXRUBY--------------------------
-REQUIREMENTS TO COMPILE/BUILD WXRUBY ITSELF
-
-- rake 
-- SWIG, version 1.3.32 or later. Earlier versions will not work correctly.
-- wxWidgets 2.8.x SDK. See further information on the wxruby website for
-  recommended compile-time options for wxWidgets.
-
-
-OBTAINING THE SOURCE:
-
-Source code is hosted in Subversion at rubyforge.org. See the links on
-the wxruby web site (http://wxruby.org). Check out the wxruby2
-Subversion module (not the old wxruby module).
-  
-
-BUILDING:
-
-From the top-level directory (typically wxruby2/), 
-just start the rake build with the command:
-
-  rake
-  
-There is no ./configure step, nor do you need to run ruby extconf.rb.
-
-
-INSTALLING THE LIBRARY:
-
-You can install the library using:
-  rake install
-  
-Note that on some systems you may need to be "root" to do this.
-To manually install, copy all the files in the lib/ subdirectory 
-to somewhere on your ruby library path, such as a ruby extensions 
-directory.
-
-
-PORTING TO OTHER PLATFORMS
-
-Platform-dependent rakefiles are used to set up compiler-specific
-settings. The following platforms are currently fully supported:
-
-  Mac OSX (gcc):        rakemacosx.rb
-  MS Windows (VC++):    rakemswin.rb
-  Linux (GTK2 + gcc):   rakelinux.rb
-  
-For other platforms, you may need to edit the appropriate
-platform-dependent rake file if your system is not yet supported, or if
-it is unusual. These files are found in the rake subdirectory:
-
-  MS Windows BC++:      rakebccwin.rb
-  MS Windows MingGW:    rakemingw.rb
-  MS Windows Cygwin:    rakecygwin.rb
-  NetBSD:               rakenetbsd.rb
-
-When editing a platform-dependent rakefile, you might 
-merely need to set one or more of the following variables:
-
-    $extra_cppflags
-    $extra_ldflags
-    $extra_objs
-    $extra_libs
-
-
-CREDITS
-
-Kevin Smith set up the wxruby2 project using SWIG and did much of the
-work that still forms the core of the library in its present form. Over
-the years dozens of volunteers have contributed invaluable patches and
-new functionality. The list is too long to give here, but their
-contributions are recorded in the wxruby mailing list archives.
-
------------------------------------------------------------
-
-LEAD MAINTAINER:
-  Alex Fenton
-  alex at pressure dot to
+* Cross-platform (MS Windows, Mac OS X, Linux)
+* Real native widgets wherever possible
+* Provides a comprehensive selection of widgets and other GUI features
+* Useful non-GUI support classes, eg for Images and internationalisation
+* Simple licence that is compatible with proprietary and Free Software 
+* Mature and actively developed foundation in wxWidgets
+* Easy to install and redistribute
+   
+=== Why are native widgets important or helpful?
+
+The really important feature among the above is, for many people, native
+widgets. Several toolkits are to some degree able to simulate the native
+appearance of widgets, but wxRuby widgets are actually native widgets -
+so they behave and interact exactly according to the desktop's GUI
+conventions.
+
+For one thing, this means that end-users do not have to adjust to a
+"foreign" interface. It ensures maximum compatibility with "assistive
+technology" such as screen readers for blind users.  It also allows apps
+to respect any themes the user may have chosen through their operating
+system. 
+
+Desktop conventions go beyond widget appearance, to the labelling and
+positioning of items in standard dialogs and menus. wxRuby offers
+features to help with these too.
+
+== Where can I ask a question, or report a bug?
+
+The main mailing list for those using wxRuby for GUI development is
+wxruby-users. General questions and queries of all sorts are appropriate
+for this list, and new users are welcome.
+
+When asking a question, if something is not working as you expect,
+please provide a *minimal*, *runnable* sample of code that demonstrates
+the problem, and say what you expected to happen, and what actually
+happened. Please also provide basic details of your platform, ruby and
+wxruby version, and make a reasonable effort to find answers in the
+archive and documentation before posting. People on the list are happy
+to help, but it's too much to expect them to guess what you're trying to
+do, or try and debug 1,000 lines of your application.
+
+There is a bug-tracker and feature-request system on the rubyforge
+project pages for wxRuby. Using these helps ensure that a bug is
+followed through and resolved. You're strongly encouraged to post to
+these logged-in to rubyforge and not anonymously. You won't receive any
+requests for follow-up information on anonymous items, and so these can
+end up being closed without being resolved if needed information isn't
+supplied.
+
+wxruby-development is a secondary mailing list for all those interested
+in the current and future development of wxRuby. The discussion on this
+list tends to deal more with the internals of the library.
+
+== How can I learn to use wxRuby?
+
+wxRuby is a large API and takes some time to learn. The wxRuby
+distribution comes with numerous samples which illustrate how to use
+many specific parts of the API. A good one to start with is the
+'minimal' sample, which provides an application skeleton. All the
+bundled samples are expected to work with current wxRuby 2.0, although
+some use a more modern coding style than others.
+
+Complete wxRuby API documentation can downloaded separately; this tends
+to focus on how to use specific classes and methods, rather than on how
+to construct an application overall.
+
+There are also tutorials on the wiki, as well as on third-party
+websites. These typically provide in-depth view of a particular topic,
+but some may be out-of-date.
+
+One of the advantages of wxRuby is the much larger ecosystem of
+wxWidgets and wxPython resources out there. There is a book for
+wxWidgets,"Cross-Platform Programming in wxWidgets", whcih can be freely
+downloaded as a PDF. This provides very comprehensive coverage of the
+wxWidgets API in C++. The code may not be directly useful, but the
+descriptions of how widgets and events and so forth work are almost
+always relevant to wxRuby.
+
+When using a search engine to find answers about a wxRuby class, it can
+be worth searching for the same term but with 'wx' prepended. For
+example, if you wanted answers about the "Grid" class, try searching for
+"wxGrid" as this will turn up results relating to wxWidgets and wxPython
+which may be relevant.
+
+== What wxWidgets features are supported by wxRuby?
+
+wxRuby supports almost all of the wxWidgets 2.8.9 GUI API, around 300
+classes in total. wxWidgets classes that provide general programming
+support features, such as strings, networking, threading and database
+access are not and will never be ported, as it's assumed that in all
+these cases it's preferable to use a Ruby library.
+
+If you know of a feature in wxWidgets that you would like to see
+supported in wxRuby
+
+== How does wxRuby 2.0 relate to the wxruby 0.6.0 release?
+
+wxRuby 0.6.0 was the last in a series of releases developed using a
+different approach in the early days of wxRuby. Work on this series
+stopped in early 2005, in favour of what is now wxRuby 2.0. Several
+years of development have gone into wxRuby since, making it vastly more
+capable and correct than the 0.6.0 release, which is only offered for
+legacy applications. 
+
+== I am getting an error trying to install or compile wxRuby
+
+Please double-check the INSTALL documents, and search the mailing list
+archives. If this doesn't help, please post your question on the wxruby
+mailing list (http://wxruby.rubyforge.org/wiki/wiki.pl?MailingLists)
+
+= Credits 
+
+Kevin Smith established the wxRuby 2.0 project using SWIG in 2005. Since
+then it has benefitted from the input of dozens of volunteers, who have
+contributed code, documentation, testing, bug reports and feature
+requests. 
+
+The alphabetic list shows (some of) those who've contributed code to
+wxRuby 2.0.
+
+Albin Holmgren
+Alex Fenton
+Artur Kuptel
+Cezar Espinola
+Chauk-Mean Proum
+Christophe Bludau
+Curt Hibbs
+Dale Edmons
+Daniel Savarese
+David Whetstone
+Dirk Traulsen
+Hawley Waldman
+Jani Monoses
+Joe Seeley
+Jonathan Maasland
+Kevin Smith
+Mario Steele
+Nic
+Pascal Hurni
+Robert Carlin
+Roy Sutton
+Ryuichi Sakamoto
+Sean Lindsay
+Sean Long
+Tobias Gruetzmacher
+Zach Dennis
+
+If your name is missing and should be here, please get in touch
+with the current development team.
+
+== Lead Maintainer
+
+Alex Fenton: alex at pressure dot to

data/lib/wx/accessors.rb

@@ -5,16 +5,21 @@
 #  * get_position()
 #  * set_size(a_size)
 #  * is_checked()
+#  * can_undo()
+#  * has_style(a_style)
 # 
 # and so on. Methods that retrieve set, or query attributes of an object
-# are more normally in Ruby called simply by the attribute name:
+# are more normally in Ruby called simply by the attribute name, or, in
+# other cases, with a predicate method:
 #
-#  * position()
-#  * size = a_size
-#  * checked?
+#  * pos = my_widget.position
+#  * my_widget.size = a_size
+#  * my_widget.checked?
+#  * my_widget.can_undo?
+#  * my_widget.has_style?
 #
 # This extension creates an alias for every WxRuby instance method that
-# begins with +get_+, +set_+ or +is_+. Note that if you are calling a
+# begins with +get_+, +set_+, +is_+, +can_+ and +has_+. 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
@@ -23,11 +28,18 @@
 #  size = Wx::Size.new
 
 module WxRubyStyleAccessors
+  # Ruby-style method named are implemented by method-missing; if an
+  # unknown method is called, see if it is a rubyish name for a real
+  # method. In principle it would be possible to set up real aliases for
+  # them at start-up, but in practice this is far too slow for all the
+  # classes that need to be started up.
   def method_missing(sym, *args)
     case sym.to_s
-    when /^(.*)\=$/
+    when /^(\w+)\=$/ 
       meth = "set_#{$1}"
-    when /^(.*)\?$/
+    when /^((?:has|can)\w+)\?$/
+      meth = $1
+    when /^(\w+)\?$/
       meth = "is_#{$1}"
     else
       meth = "get_#{sym}"

data/lib/wx/classes/bitmap.rb

@@ -25,6 +25,9 @@ class Wx::Bitmap
     new(img, depth)
   end
 
+  # Ruby methods that switch class are conventionally named to_foo
+  alias :to_image :convert_to_image
+
   # Redefine the initialize method so it raises an exception if a
   # non-existent file is given to the constructor; otherwise, wx Widgets
   # just carries on with an empty bitmap, which may cause faults

data/lib/wx/classes/clipboard.rb

@@ -1,8 +1,4 @@
 class Wx::Clipboard
-  # See if we like these better
-  alias :place :set_data
-  alias :fetch :get_data
-
   class << self
     # This is provided internally by the SWIG interface file, but all
     # public access should be via Clipboard.open; see below
@@ -29,4 +25,32 @@ class Wx::Clipboard
        clip.close if clip
     end
   end
+
+  # Need to do some internal record-keeping to protect data objects on
+  # the clipboard from garbage collection
+  @@__clip_data = []
+
+  # These methods affect the clipboard contents; each time, update the
+  # record with the changed data contents
+  wx_add_data = instance_method(:add_data)
+  define_method(:add_data) do | the_data |
+    @@__clip_data << the_data
+    wx_add_data.bind(self).call(the_data)
+  end
+
+  wx_clear = instance_method(:clear)
+  define_method(:clear) do 
+    @@__clip_data.clear
+    wx_clear.bind(self).call
+  end
+
+  wx_set_data = instance_method(:set_data)
+  define_method(:set_data) do | the_data |
+    @@__clip_data = [ the_data ]
+    wx_set_data.bind(self).call(the_data)
+  end
+
+  # Aliases, more clearly expressive?
+  alias :place :set_data
+  alias :fetch :get_data
 end

data/lib/wx/classes/image.rb

@@ -17,6 +17,11 @@ class Wx::Image
     bmp.convert_to_image
   end
 
+  # Ruby methods that switch class are conventionally named to_foo
+  def to_bitmap
+    Wx::Bitmap.from_image(self)
+  end
+
   # Redefine the initialize method so it raises an exception if a
   # non-existent file is given to the constructor; otherwise, wx Widgets
   # just carries on with an invalid image, which may cause faults

data/lib/wx/classes/toolbar.rb

@@ -2,20 +2,23 @@
 class Wx::ToolBar
   # Generic method to add items, supporting positional and named
   # arguments
-  ADD_ITEM_PARAMS = [ Wx::Parameter[ :position, -1 ], 
+  ADD_ITEM_PARAMS = [ 
+                      Wx::Parameter[ :bitmap2, Wx::NULL_BITMAP ],
+                      Wx::Parameter[ :position, -1 ], 
                       Wx::Parameter[ :id, -1 ],
                       Wx::Parameter[ :label, "" ], 
-                      Wx::Parameter[ :bitmap2, Wx::NULL_BITMAP ],
                       Wx::Parameter[ :kind, Wx::ITEM_NORMAL ], 
                       Wx::Parameter[ :short_help, "" ], 
                       Wx::Parameter[ :long_help, "" ], 
                       Wx::Parameter[ :client_data, nil ] ]
   
-  def add_item(bitmap, *mixed_args)
+  def add_item(bitmap1, *mixed_args)
     args = Wx::args_as_list(ADD_ITEM_PARAMS, *mixed_args)
 
+    bitmap2 = args.shift
     pos = args.shift
-    args.insert(2, bitmap)
+    args.insert(2, bitmap1)
+    args.insert(3, bitmap2)
 
     # Call add_tool to append if default position
     if pos == -1

data/lib/wx/classes/validator.rb

@@ -0,0 +1,7 @@
+class Wx::Validator
+  # Default implementation of clone, may need to be over-ridden in
+  # custom subclasses should state variables need to be copied
+  def clone
+    self.class.new
+  end
+end