README for wxRuby version 2.0

Introduction

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.

Installing wxRuby

wxRuby is distributed as pre-compiled binaries and source from the project’s site on Rubyforge: wxruby.rubyforge.org/

For the majority of users, installation simply requires running ‘gem install wxruby’ on the command line. See INSTALL for further information.

wxRuby licence

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.

FAQ

What platforms and operating systems are supported in wxRuby2?

Currently the following are fully supported:

  • Windows NT/2000/XP/Vista (i686, MSVC and MingW)

  • OS X 10.4+ (i686 and PowerPc)

  • Linux (i686 + AMD-64)

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?

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:

  • 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 (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