Creating a "Hello World" Program With WxRuby

To get started in WxRuby, first look at this "Hello world" program. It's a simple program that displays an empty window. It shows a little about how WxRuby works, and acts as a good boilerplate program. When you want to write a new WxRuby program, simply copy and paste this into your text editor.

First, let's just take a look at the code.

#!/usr/bin/env ruby
require 'rubygems'
require 'wx'

class MyApp < Wx::App
  def on_init
    @frame = Wx::Frame.new( nil, -1, "Application" )
    @frame.show
  end
end

app = MyApp.new
app.main_loop

Taking a Closer Look at the Code

To load the WxRuby library, require the 'wx' module. From this point on, all the WxRuby classes will be available in the Wx module. While you may be tempted to include this module into the global namespace, the Wx module contains a lot of small, generic names such as App, Menu, Frame, etc that can easily clash with other classes in the global namespace.

Every WxRuby application is contained in a class inherited from the Wx::App class. Our test class uses the name MyApp, but you may want to change this to something a little more creative.

The on_init method of a Wx::App class is run before the main loop of that application is entered. Here, any widgets in the program can be created and any other setup routines can be run. In this example, we're creating a single widget, a Wx::Frame. A Frame is a widget that holds other widgets. Though since we're not putting any other widgets in it, we're simply using it to display an empty window.

When creating widgets, the very first parameter of the constructor is always the parent widget. Since this is the top-most widget in the application, there is no parent widget so nil is passed. If we were to create a second widget inside this frame widget, we would pass the @frame variable as the first parameter of its constructor.

The second argument of all widget constructors is an id field. This can be used to create a widget with a unique ID so it may be referred to at a later time. However, since we're not using this feature, simply pass -1 in its place. This tell WxRuby we don't care about the ID and it should determine the best value for the ID.

Finally, the third parameter of the Wx::Frame constructor (not necessarily all constructors) is the text to display in the title bar. Our rather non-descriptive string "Application" will be displayed in the title bar of our window, as well as in the task bar. Other widgets have differen third parameters, and may have even more parameters. There are also other parameters to the Wx::Frame widget, but since we don't care about them at this time, we leave them at their default for the time being. Some things you can define with these parameters is the window size and position.

Finally, after creating a widget, you must call show on it or it won't be shown. Though you may want to wait to do this for some things (such as popup windows), since this is a simple single-widget application, doing this in the on_init method is appropriate.

Since this is such a simple application, that's it for the MyApp class. The remainder of the program simply creates an instance of MyApp, then calls the method main_loop on it. This method is inherited from the Wx::App class and will call the MyApp::on_init method, then set up an event loop that redraws the window, and passes any messages (such as mouse clicks or key presses) up to your Ruby program. The main_loop method ends when you click the close button or otherwise send your application a quit message.