wxRuby Documentation: Class Reference

This is the class reference for WxRuby. The classes listed below are those currently available in WxRuby2. This documentation was seeded by converting the WxWidgets C++ documentation, so it has some shortcomings.

The following tutorials contain helpful overviews specific to the wxRuby API:


wxRuby includes a large number of classes. Some represent a GUI element represented on the screen, such as a Window, Frame, Control or Menu:

Others are helper classes used in handling data and managing all aspects of user interaction with applications:

See also the list of wxRuby module functions.


Any element drawn on the screen in wxRuby is a instance of Window or one if its subclasses. This includes top-level frames and dialogs that contain GUI controls, controls for user interaction, and elements that manage the layout of controls, such as tabbed notebooks. Many important methods are inherited from Window.

Window Anything painted on the screen


There are several types of window that are directly controlled by the window manager. Frames and dialogs are similar in wxRuby. Only frames may be associated with a menu; only dialogs may appear modally (on top of all other windows).

TopLevelWindow Any top level window, dialog or frame
Dialog Dialog box base class
Frame Normal OS frame
MDIChildFrame MDI child frame
MDIParentFrame MDI parent frame
MiniFrame A frame with a small title bar
SplashScreen Splash screen class
PropertySheetDialog Property sheet dialog
TipWindow Shows text in a small window
Wizard A wizard dialog
AboutDialogInfo A specialised, platform-native “About” dialog



These are small windows or widgets which provide allow for various types of user input and interaction.

Control The base class for controls
Button Push button control, displaying text
BitmapButton Push button control, displaying a bitmap
ToggleButton A button which stays pressed when clicked by user.
CalendarCtrl Control showing an entire calendar month
CheckBox Checkbox control
CheckListBox A listbox with a checkbox to the left of each item
Choice Drop-down list from which the user can select one option
ComboBox A drop-down Choice with an editable text area
BitmapComboBox A ComboBox where each item can have an image
DatePickerCtrl Small date picker control
Gauge A control to represent a varying quantity, such as time remaining
GenericDirCtrl A control for displaying a directory tree
HtmlListBox A listbox showing HTML content
HyperlinkCtrl Displays a clickable URL that will launch a browser
StaticBox A static, or group box for visually grouping related controls
ListBox A list of strings for single or multiple selection
ListCtrl A control for displaying lists of strings and/or icons, plus a multicolumn report view
TextCtrl Single or multiline text editing control
StyledTextCtrl Sophisticated code text editor based on Scintilla
RichTextCtrl Advanced text-editing control with styles and inline images
TreeCtrl Tree (hierarchy) control
ScrollBar Scrollbar control
SpinButton A spin or ‘up-down’ control
SpinCtrl A spin control – i.e. spin button and text control
StaticText One or more lines of non-editable text
StaticBitmap A control to display a bitmap
RadioBox A group of radio buttons
RadioButton A round button to be used with others in a mutually exclusive way
Slider A slider that can be dragged by the user
VListBox A listbox supporting variable height rows
MediaCtrl A control for playing sound and video
AnimationCtrl For displaying a looping animation


Miscellaneous windows

The following are a variety of classes derived from Wx::Window and drawn on the screen, but which are not simple controls like Buttons. They typically provide ways of organising other widgets (for example, in a Notebook), or other information and interaction elements, such as a StatusBar.

Panel A window whose colour changes according to current user settings
CollapsiblePane A container with a button to collapse or expand contents
ScrolledWindow Window with automatically managed scrollbars
Grid A grid (table) window
SplitterWindow Window which can be split vertically or horizontally
StatusBar A status bar on a frame
ToolBar Toolbar with buttons
Notebook Tabbed Notebook for layout out controls
Listbook Similar to notebook but using a list control
Choicebook Similar to notebook but using a choice (dropdown) control
SashWindow Window with four optional sashes that can be dragged
SashLayoutWindow Window that can be involved in an IDE-like layout arrangement
VScrolledWindow As ScrolledWindow but supports lines of variable height
WizardPage A base class for a page in wizard dialog.
WizardPageSimple A page in wizard dialog.


Common dialogs

Common dialogs are ready-made dialog classes which are frequently used in applications. They are OS-native versions for standard GUI activities such as opening a file, requesting a text string or password, or displaying a message.

Dialog Base class for common dialogs
ColourDialog Colour chooser dialog
DirDialog Directory selector dialog
FileDialog File selector dialog
FindReplaceDialog Text search/replace dialog
MultiChoiceDialog Dialog to get one or more selections from a list
SingleChoiceDialog Dialog to get a single selection from a list and return the string
TextEntryDialog Dialog to get a single line of text from the user
PasswordEntryDialog Dialog to get a password from the user
FontDialog Font chooser dialog
PageSetupDialog Standard page setup dialog
PrintDialog Standard print dialog
ProgressDialog Progress indication dialog
MessageDialog Simple message box dialog
Wizard A wizard dialog.


Menus typically appear at the top of a frame. They contain drop-down lists of actions, which may be accessed by mouse or keyboard shortcut.

Menu Displays a series of menu items for selection
MenuBar Contains a series of menus for use with a frame
MenuItem Represents a single menu item


RichText classes

RichTextCtrl provides a generic, cross-platform editing widget intended for working with natural language text. It supports character, paragraph and list styles, and includes support for stylesheets and printing. Import from XML, and export to XML and HTML is provided.

RichTextAttr Definition of text style properties
RichTextBuffer The internal representation of a RichTextCtrl’s contents
RichTextCharacterStyleDefinition A named character-level style
RichTextCtrl GUI widget for editing rich text
RichTextEvent Events specific to RichText
RichTextFileHandler Base class for reading and writing rich text
RichTextFormattingDialog Dialog for editing rich text styles
RichTextHeaderFooterData Helper class for printing headers and footers
RichTextHTMLHandler Export rich text to HTML
RichTextStyleDefinition Base class for named styles
RichTextParagraphStyleDefinition A named style for paragraph properties
RichTextPrinting Convenient printing of rich text content
RichTextPrinting Helper class for printing rich text
RichTextStyleListBox Control which previews and allows selection of styles from a stylesheet
RichTextStyleListCtrl Combined control for choosing styles from a stylesheet
RichTextStyleSheet A collection of named styles that can be applied to text
RichTextXMLHandler Import and export rich text in XML

HTML classes

These are a set of classes to allow display and printing of hypertext in HTML format, including images and clickable links.

HtmlHelpController HTML help controller class
HtmlWindow HTML window class, for displaying HTML
HtmlEasyPrinting Simple but useful class for printing HTML


AUI – advanced user interface

These classes enable writing a customizable IDE-like application with built-in docking, floatable panes and a flexible MDI-like interface.

AuiManager The central class for using and managing the interface within a window
AuiNotebook A replacement notebook class with extra features
AuiPaneInfo Describes a single pane
AuiDockArt Art and metrics provider for customizing the docking user interface


An event object contains information about a specific event. Event handlers blocks may optionally receive a single block parameter, which will be an Event object of the appropriate class. For more information about events and setting up event handlers, see the event handling overview

ActivateEvent A window or application activation event
CalendarEvent Used with wxCalendarCtrl
CalculateLayoutEvent Used to calculate window layout
ChildFocusEvent Called when focus is set to a child of this Window
CloseEvent A close window or end session event
CommandEvent An event from a variety of standard controls
ContextMenuEvent An event generated when the user issues a context menu command
DateEvent Used with wxDatePickerCtrl
EraseEvent An erase background event
Event The event base class
FindDialogEvent Event sent by wxFindReplaceDialog
FocusEvent A window focus event
KeyEvent A keypress event
IconizeEvent An iconize/restore event
IdleEvent An idle event
ListEvent A list control event
MenuEvent A menu event
MouseEvent A mouse event
MoveEvent A move event
NavigationKeyEvent An event caused when the user TABs between controls
NotifyEvent A notification event, which can be vetoed
PaintEvent A paint event
QueryLayoutInfoEvent Used to query layout information
RichTextEvent Events specific to RichText
ScrollEvent A scroll event from sliders, stand-alone scrollbars and spin buttons
ScrollWinEvent A scroll event from scrolled windows
SizeEvent A size event
SpinEvent An event from wxSpinButton
SplitterEvent An event from wxSplitterWindow
TextUrlEvent Mouse interaction with a URL in a TextCtrl
TimerEvent A timer expiration event
TreeEvent A tree control event
UpdateUIEvent A user interface update event
WindowCreateEvent A window creation event
WindowDestroyEvent A window destruction event
WizardEvent A wizard event


Window layout

Sizers enable the layout and size of controls and windows to adapt to the user’s resizing of frames and containers.

Sizer Abstract base class
GridSizer A sizer for laying out windows in a grid with all fields having the same size
FlexGridSizer A sizer for laying out windows in a flexible grid
GridBagSizer Another grid sizer that lets you specify the cell an item is in, and items can span rows and/or columns.
BoxSizer A sizer for laying out windows in a row or column
StaticBoxSizer Same as wxBoxSizer, but with a surrounding static box
StdDialogButtonSizer Sizer for arranging buttons on a dialog, in platform-standard order


Device contexts

Device contexts are surfaces that may be drawn on. They allow the application to draw lines, shapes, images and text directly. This can be on-screen within an application GUI, or onto paper via a printer. They provide abstraction by allowing the same set of drawing methods, documented in DC, to be used with different output targets.

DC The device context base class; all drawing methods are listed here
ClientDC A device context to access the client area outside Paint events
PaintDC A device context to access the client area inside Paint events
WindowDC A device context to access the non-client area
ScreenDC A device context to access the entire screen
MemoryDC A device context for drawing into bitmaps
GCDC A device context for anti-aliased drawing
PrinterDC A device context for drawing to printers
RendererNative Assists drawing native-look GUI elements in custom controls

The interface provided by the DeviceContext classes will be sufficient for most normal drawing needs. wxRuby also provides an advanced set of drawing classes which offer complex lines, splines and matrix transformations:

GraphicsContext An anti-aliased drawing context
GraphicsBrush Brush for use with GraphicsContext
GraphicsFont Font for use with GraphicsContext
GraphicsPath Geometric path for use with GraphicsContext
GraphicsPen Pen for use with GraphicsContext
GraphicsMatrix Matrix for specifying transformations in a GraphicsContext


Graphics device interface

These classes are related to drawing on device contexts and windows.

Colour Represents the red, blue and green elements of a colour
Animation Represents an animation, such as an animated GIF
Bitmap Represents a bitmap
Brush Used for filling areas on a device context
Cursor A small, transparent bitmap representing the cursor
Font Represents fonts
Icon A small, transparent bitmap for assigning to frames and drawing on device contexts
IconBundle A group of similar icons of different sizes
Image A platform-independent image class
ImageList A list of images, used with some controls
Mask Represents a mask to be used with a bitmap for transparent drawing
Pen Used for drawing lines on a device context
Region Represents a simple or complex region on a window or device context
RendererNative Abstracts high-level drawing primitives



These are the window validators, used for filtering and validating user input.

Validator Base validator class
TextValidator Text control validator class


Data structures

Object The root class for most wxRuby classes
Point Representation of a point (x, y position)
Rect A class representing a rectangle
Region A class representing a region
Size Representation of a size (height and width)


Document/view framework

The wxWidgets API supports a document/view framework which provides housekeeping for a document-centric application – but this is not yet ported to Ruby.


Printing framework

A printing and previewing framework is implemented to make it relatively straightforward to provide document printing facilities.

PreviewFrame Frame for displaying a print preview
PreviewCanvas Canvas for displaying a print preview
PreviewControlBar Standard control bar for a print preview
PrintDialog Standard print dialog
PageSetupDialog Standard page setup dialog
Printer Class representing the printer
PrinterDC Printer device context
Printout Class representing a particular printout
PrintPreview Class representing a print preview
PrintData Represents information about the document being printed
PrintDialogData Represents information about the print dialog
PageSetupDialogData Represents information about the page setup dialog


Drag and drop and clipboard classes

These classes provide support for passing to and from other desktop applications, as well as between widgets within a wxRuby application.

DataObject Data object class
TextDataObject Text data object class
FileDataObject File data object class
BitmapDataObject Bitmap data object class
Clipboard Clipboard class
DropTarget Drop target class
FileDropTarget File drop target class
TextDropTarget Text drop target class
DropSource Drop source class


XML-based resources

Resources allow your application to create controls and other user interface elements from specifications stored in an XML format.

XmlResource The main class for working with resources.


Online help

Set of classes for providing context-sensitive help and online documentation. These allow an application to enter a “help” mode and provide information about specific UI elements, and to display HTML documentation in a standalone Window.

HelpController Family of classes for controlling help windows
HtmlHelpController HTML help controller class
ContextHelpButton Button class for putting application into context-sensitive help mode
HelpProvider Base class for providing context-sensitive help; inherit from this to write your own
SimpleHelpProvider Simple TipWindow provider of context-sensitive help
HelpControllerHelpProvider Provides context-sensitive help provision via a help controller
TipWindow Window class for displaying tips
ToolTip Class implementing tooltips



App application class
Caret A caret (cursor) object
Display Provides information about monitors / displays
DragImage An image that can be dragged across windows
GLCanvas Canvas that you can render OpenGL calls to.
LayoutAlgorithm An alternative window layout facility
Locale Discover standard operating system language and encoding etc
Log Base class for logging
LogTextCtrl A TextCtrl that displays application log messages
Sound Play simple sounds from Windows WAV files
Timer Timer class
TaskBarIcon Icon that appears in the task bar, system tray or dock, and can have a popup menu
StandardPaths Get OS-standard directory locations for settings, config etc
SystemSettings System settings class for obtaining various global parameters
AcceleratorTable Accelerator table for setting up shortcut keys
CalendarDateAttr Used with wxCalendarCtrl

[This page automatically generated from the Textile source at Wed Sep 09 02:21:00 +0100 2009]