FAQ : General Questions
About HowTo User Guide Reference documentation
wxRuby3 is a (mostly) native extension library for Ruby based on the mature wxWidgets GUI toolkit for C++ providing a framework to create cross-platform GUI applications with Ruby. It uses native widgets wherever possible to achieve GUI applications with the look, feel and behaviour on Windows, OSX and Linux that users on those platforms are accustomed to.
Although building a wxRuby3 GUI application programmatically is common (and not extremely hard) there are various tools around with which to build attractive dialogs and forms/panels in a 'wysiwyg'-like fashion.
- wxUIEditor can generate and maintain Ruby code for any GUI designs;
- wxRuby3 can also load XRC files generated by a variety of tools like wxUIEditor, wxFormBuilder, DialogBlocks and the like.
wxRuby3 is free and open source. It is distributed under the liberal MIT licence which is compatible with both free and commercial (proprietary) development. See the LICENSE document for more details.
The conditions for using wxRuby3 are the same for a personal, academic or commercial developer.
In the (distant) past there existed wxRuby 0.6.0, 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 became wxRuby 2.0. This project in turn stopped being supported in 2013.
Several years of development have passed for wxWidgets and Ruby respectively, improving code quality,
adding new classes and new language features.
In 2022 the main developer of wxRuby3, Martin Corino, finally found the time and the inspiration to pick
up this project with the idea of reviving it to build some applications he had in mind.
wxRuby3 intends to provide Ruby interfaces for all relevant (!) wxWidget classes of the latest version 3.2 and beyond.
Building on the experiences of the previous (2) wxRuby developments as well as the wxPython Phoenix project it is
expected to provide a better and more maintainable solution.
As said wxRuby3 is an open source project and as such there is no direct dedicated, official, support.
That being said the developer(s) have a clear intention to maintain wxRuby3 as a stable, comprehensive solution
to developing professional-standard desktop applications in Ruby and are therefor responsive to problems and questions
reported through the project's Github Issues.
The key approaches for guaranteeing favourable responses are:
- be polite;
- be precise;
- be complete.
Currently the following platforms are supported.
| Platform | Ruby version(s) | wxWidgets version(s) |
|---|---|---|
| Windows 10 (tested) (most likely also Windows 11) |
Ruby >= 2.5 (RubyInstaller MSYS2-DevKit) |
wxWidgets >= 3.2 |
| Linux (tested; all major AMD64 and ARM64 distributions: Ubuntu, Debian, Fedora, OpenSuSE and ArchLinux) (most likely also i686) |
Ruby >= 2.5 | wxWidgets >= 3.2 |
| MacOS >= 10.10 using Cocoa (tested on AMD64 and ARM64 M1/M2 Chip) | Ruby >= 2.5 (MacPorts, Homebrew, ruby-install, RVM) | wxWidgets >= 3.2 |
wxRuby3 supports almost all of the wxWidgets 3.2+ GUI API, providing over 600 classes in total. wxWidgets classes that provide general and/or non-GUI programming support features, such as strings, networking, threading, database access and such are not and will never be ported, as it's assumed that in all these cases it's preferable to use pure Ruby features.
For more details see the User Guide (especially the Modules section) and/or the Reference documentation.
If you know of a feature in wxWidgets that you would like to see supported in wxRuby3 you are free to ask but do not EXPECT unconditional agreement or immediate response. Again the key approach is 'be polite'.
This depends largely on 3 things:
- firstly the overall wxRuby3 support policy for wxWidgets features (see above);
- secondly the availability/support of platform-specific features by wxWidgets itself (see here);
- and thirdly compatibility of wxWidgets platform specific features with Ruby.
As far as issue 3 is concerned there are some things (not many) that simply will not work in Ruby. One example of this
is wxWidgets support for native windows through their wxNativeWindow class.
The wxRuby3 project uses git to develop and maintain the code. The main repository is located on Github
which also provides Issue management, Wiki
and Reference documentation hosting.
wxRuby3 is distributed as a Ruby gem on RubyGems and can be installed with the command:
gem install wxruby3This gem can also be downloaded from the release assets on Github in which case installing the gem could be achieved with:
gem install /local/path/to/downloaded/gemFor more information concerning post-install procedures, prebuilt binaries and/or install options see the INSTALL document.
wxRuby3 is very easy to use. The following code snippet for example
require 'wx'
Wx::App.run do
Wx::Frame.new(nil, title: 'Hello world!').show
endwould display the following rudimentary Ruby GUI applications on Windows, MacOSX and Linux (GTK):
For all details concerning the various ins and outs of the wxRuby3 framework be sure to carefully read the User Guide.
Details concerning all available classes and methods can be found in the Reference documentation.
Yes! The wxRuby3 projects welcomes ideas, bugfixes (corrections), (documentation) additions.
Use Github Issues to post ideas, feature requests or problem reports. For any concrete (code or documentation) contribution the following applies:
- create a fork of the repository on Github;
- make your changes in your forked repository;
- make sure any code changes/additions build cleanly (free CPU time at CI/CD suppliers is precious and should not
be wasted); - submit a PR for your changes;
- and lastly, have a little patience (maintenance of this project is a voluntary work of love without obligations).
Be aware that:
- any new addition/enhancement should not impact existing functionality negatively;
- any new addition/enhancement should be accompanied by tests and/or samples working correctly;
- do not forget updating and/or extending documentation;
- addition of new platform support cannot be accepted without CI/CD workflows for such platforms.
Yes. Glimmer DSL for WX enables software engineers to build GUI using wxruby3 following the Ruby way with the least amount of code possible. That is by offering a minimalistic declarative high-level DSL that maps visually to the way software engineers think about the GUI hierarchy in addition to adopting Rails' strategy of Convention over Configuration via smart defaults and automation of wxruby3 low-level details. You can check out the Glimmer DSL for WX README "Coming From wxruby3" section for more information on how to translate wxruby3 apps to Glimmer DSL for WX syntax.