wxRuby Overview

Syntax

As of version 1.9.1, a number of syntax additions were made to place the wxRuby API style more in line with Ruby rather than C++ conventions. As these apply globally to a large number of classes, they are not currently listed as alternatives in the individual class reference documentation, but instead are described here.

Keyword constructors for Window classes

Classes that inherit from Window – covering all GUI widgets and frames – typically have quite long lists of parameters passed to their new method. As well as class-specific arguments, they usually have parameters for window id, size, position and style. This means calls to new can end looking unwieldy.

For example, to create a multiline “TextCtrl”, the TE_MULTILINE style must be passed. If default positioning and default sizing is desired (as is usually the case when using Sizers to manage layouts), the call ends up looking like this:

text = Wx::TextCtrl.new(parent, -1, 'some text'
                        Wx::DEFAULT_POSITION,
                        Wx::DEFAULT_SIZE,
                        Wx::TE_MULTILINE)

As of version 1.9.1, it is possible to use named keyword arguments to specify constructor parameters in arbitrary order. The names of the arguments can be got from the class documentation. Omitted arguments will be given their default value. The above call could look like

text = Wx::TextCtrl.new(parent, :text => 'some text', 
                                :style => Wx::TE_MULTILINE)

Which is both less typing, and easier to read.

Ruby-style accessors

In the wxWidgets API, methods for getting and setting properties of instances are named according to the convention commonest in C++ and Java. For example, to get and set the size of a widget, the methods are named:

widget.get_size
widget.set_size(new_size)

In Ruby, much the commoner convention is to have accessor methods named simply after the property. Therefore, in wxRuby, the following are valid alternatives to the above:

widget.size
widget.size = new_size

Note that in Ruby, if you are calling a setter argument within an instance’s method, you must explicitly specify self as the receiver. Without this, Ruby will interpret the call as an assignment to a local variable rather than a method call:

# won't work, seen as assignment to local variable "size" 
size = new_size
self.size = new_size

is_ methods

Similar to the getters and setters, there are numerous methods in the C++ API which test a condition, such as Bitmap#is_ok. Ruby enables such methods which return true or false to have a name ending with the ”?” character. In wxRuby, therefore, both the following are permitted

# C++ style
a_bitmap.is_ok

Or

# Ruby style
a_bitmap.ok?

Size and Point argument shorthands

Point and Size are simple Wx classes which represent an x/y position and a width/height size respectively. They are widely used in the API, including in widget constructors. For example, to create a button at a specific position:

button = Wx::Button.new( parent, -1, 'press me', Wx::Point.new(50, 50) )

As a terser alternative, Point and Size arguments may be specified using a two-element Ruby array, specifying an x/y co-ordinate or a width/height size. The above could be re-written:

button = Wx::Button.new( parent, -1, 'press me', [50, 50])

Or, neater, using keyword arguments:

button = Wx::Button.new( parent, :label => 'press me', 
                                 :pos => [50, 50])

These can be used in any method accepting a size argument:

# Resize widget
widget.size = [200, 100]

Or a point argument

# Move widget
widget.move [40, 20]

[This page automatically generated from the Textile source at Thu May 01 00:50:49 +0100 2008]