h1. wxRuby Overview

h2. 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.

h3. Keyword constructors for Window classes

Classes that inherit from "Window":window.html - 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":sizer.html 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.

h3. 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

  ==#== correct way
 self.size = new_size
 
h4. 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":bitmap.html#Bitmap_isok. 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?

h3. Size and Point argument shorthands

"Point":point.html and "Size":size.html 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]