C++ Docs For Perl Programmers

From WxPerl wiki

This article describes how to read the native wxWidgets documentation, which is geared toward C++ programmers, if you know Perl but aren't so hot at C++.

Contents 1 Introduction 2 Language Syntax 2.1 Classes 2.2 Types 2.3 Prototypes 2.4 Constructors 2.5 Destructors 3 Documentation Layout 3.1 Class Name 3.2 Derived From 3.3 Include Files 3.4 Window Styles 3.5 Members 3.6 Method Details 4 Conversion hints 5 Implementation Differences (Gotchas) 6 Useful Links

Introduction

The main documentation for wxWidgets is at docs.wxwidgets.org, but the site assumes the reader is a C++ programmer, since wxWidgets is written in C++.

Language Syntax

Classes

wxWidget classes in C++ are named with identifiers that begin with "wx", and then have a camel-case descriptive name consisting of upper- and lower-case letters, no numbers or underscores or other punctuation. In general, to locate the corresponding wxPerl class, convert the "w" in the leading "wx" to uppercase, and insert two colons.

Thus wxWindow becomes Wx::Window, and wxMouseCaptureChangedEvent becomes Wx::MouseCaptureChangedEvent.

Types

C++ is a strongly-typed language, which means that every variable or parameter must have a specific data type, and each function or method must be declared to return a specific type. Every object class in C++ counts as a data type, plus there are several built-in types. Some of these are:

Type	Description
int	Integer; usually 32 bits, possibly 64.
long	Long integer; at least the size of an int. Usually 64 bits; may be 32 in some implementations.
char	Character; 1 byte.
float	Floating-point number.
double	Double-precision floating-point number.
bool	Boolean; may be assigned one of the two special values true or false.
unsigned char	This is often used for a one-byte integer value.

In addition, C++ has a special notation for indicating pointers to these types (and to class types). This is done by using a * (asterisk) or & (ampersand) in the declaration. You usually don't need to worry about the specifics (unless you're writing C++ code); just remember that a variable or parameter with a * or & before it indicates that it is an indirection to the specified data type.

For a Perl programmer reading the C++ docs, indirection can affect things in two ways. First, if a function or method parameter is declared with indirection, that usually means that it is an output parameter (in C++, like in Perl, functions may modify their arguments. In Perl, this is usually not done because of stylistic conventions. In C++, parameters have to be declared and passed somewhat differently in order to allow them to be modified).

Second, when you see a variable or parameter declared as char *, that tells you that it is a C-style string. The wxWidgets library almost always uses the class wxString for strings, but if you come across a "char *" variable, know that it is a string.

Prototypes

Each method in a C++ class is declared with a prototype, and you will see these throughout the wxWidgets class documentation. Each prototype specifies the number and type of required parameters, and the type of value returned by the method.

You can generaly ignore the C++ modifiers virtual and const, and * and & symbols around parameters. void means that the method returns no value.

Examples

virtual void SetFocus()

This method (from wxWindow) takes no arguments, and returns no value. In Perl, given a window object in $win, you would invoke it as: $win->SetFocus;

virtual wxRect GetRect() const

This method takes no arguments, and returns a wxRect object. We can ignore the "virtual" and "const", and invoke it in Perl as $win->GetRect;, and expect a Wx::Rect object to be returned.

void SetLabel(const wxString&  label)

This method (from wxButton) takes a single argument, which is a text string, and returns nothing.

Some method parameters are optional; in C++ these are decared with an equals sign in the parameter list, followed by the default value that will be used if the parameter is omitted. Example (also from wxWindow):

wxEvtHandler* PopEventHandler(bool deleteHandler = false) const

This method takes an optional parameter of type bool, meaning that it should be have a value of 0 or 1. If the parameter is omitted, false is assumed. A Wx::EvtHandler object is returned.

bool AddPage(wxNotebookPage* page, const wxString&  text, bool select = false, int imageId = -1)

This method (from wxNotebook) has two mandatory parameters, a wxNotebookPage object and a text string; and two optional parameters, a boolean which defaults to false and an integer that defaults to -1. It returns a boolean value.

Constructors

In Perl, objects are constructed by invoking a class method, typically named new. C++ has a built-in operator named new that invokes a function, defined in the class library, that has the same name as the class. The effect is pretty much the same. But when you read the class documentation and see a method with the same name as the class, that's the constructor, and its prototype tells you what you will have to pass to new() in the wxPerl class. (There are often several different variants of the constructor for a given class; often wxPerl's class implements all of the variants, sometimes not).

Destructors

In C++ as in Perl, object destructors are called automatically when needed. In Perl, the destructor is a method called DESTROY. In C++, it is named with tilde (~) followed by the class name (example: ~wxTextCtrl). You can safely ignore these.

Documentation Layout

This section describes the usual layout of wxWidgets class documentation pages. It is current as of version 2.8 of the wxWidgets documentation. The wxWidgets developers could change their documentation style at any time, but this is how they currently look.

Class Name

The first section of every wxWidgets class documentation page has the name of the class and a brief text description of how it is used.

Derived From

Then there follows a list of the inheritance hierarchy for the class — its parent class, that class's parent, and so on all the way up to (usually) wxObject.

This is useful, because while child classes generally only provide specialized methods for their own purposes, they usually also retain most or all of their parents' funtionality.

For example, suppose you want to change the font and color of text on a Wx::Button control. If you look at the wxWidget documentation for wxButton, you will see no way to set these characteristics. But if you look at the "Derived From" section at the top of the page, you will see that wxButton derives from wxWindow (and thus Wx::Button derives from Wx::Window). So it inherits a great deal of functionality from there. In this case, you'd call SetFont() and/or SetForegroundColour() on the button.

Include Files

This section is not relevant to Perl programming; ignore it.

Window Styles

For most controls (Wx::Control objects), this section describes flags that can be passed to the object constructor (or to the SetWindowStyleFlag method) to control the appearance or behavior of the control. Keep in mind that most controls can use at least some of styles described in the wxWindow (Wx::Window) page as well.

Members

A list of the methods provided by this class. Usually the list starts with the constructor and proceeds alphabetically. (Some pages deviate from this pattern). This list is composed of links to the method documentation further down the page, so it acts as a handy table of contents.

Method Details

The rest of each page consists of details of each method, generally starting with the object constructor. Each method description begins with the method's prototype, as described above. Often there will be variants — which may or may not be implemented in the wxPerl version.

Conversion hints

Here are some hints for converting from what you see on the C++ wxWidgets page to wxPerl.

• Almost all classes, and almost all methods within each class, are implemented in wxPerl. So be confident that almost everything you see is usable.
• Method prototypes will tell you what arguments you need to pass, and roughly what data type they should be. Any parameter that has a default value (specified with an equals sign) may be omitted if no later arguments need to be specified.
• The C++ numeric types long, int, float, etc can be replaced with ordinary Perl scalar variables that hold numeric values.
• Any wxString or "char *" parameter can be replaced with an ordinary Perl scalar variable holding any sort of string value.
• Any wxSize or wxPoint argument can be replaced with a reference to a two-position array; that is, [$width, $height] or [$x, $y].
• Most global constants used throughout the wxWidgets documentation are of the form wxCAPITAL_NAME — that is, a lowercase "wx" followed by a descriptive name in all-caps (possibly with underscores). For example: wxID_ANY, wxEVT_NULL, wxCB_SIMPLE. These correspond exactly to wxPerl. They are provided as constants that are exported by the Wx module (some are exported by Wx::Event).
• Event bindings are done by functions whose names are all uppercase-and-underscores and which begin with "EVT" (the C++ pages correctly identify these as "macros", not "functions", but the distinction is not important here). For example: EVT_TEXT, EVT_CLOSE. These names correspond exactly to wxPerl, as functions that are exported by Wx::Event. However, in Perl these functions all take one extra parameter at the beginning, which is a reference to the object that will be handling the event.
• Many wxWidgets pages include links to descriptive topic pages, such as "Window Style Overview", or "Event Handling Overview", or "Programming with wxBoxSizer" — narrative documentation that may not have been converted to the WxPerl wiki yet. These are often very illuminating, and usually don't require a whole lot of C++ knowledge to read.

Implementation Differences (Gotchas)

Sometimes classes in wxPerl are just implemented differently than in wxWidgets. This can lead to irritating surprises for the Perl programmer.

Usually, this is because C++ lends itself to a different programming style than Perl. wxPerl generally follows the C++ style, except where it makes more sense to do things in the Perl idiom.

For example, consider the GetTextExtent method in the wxWindow/Wx::Window class. In C++, this method returns nothing (void), and accepts a string argument and four output arguments, which are pointers to integers that will receive the width and height values:

void GetTextExtent(wxString&  string, int* x, int* y, int* descent, int* externalLeading);

(Note: this prototype has been simplified for purposes of this discussion). It is implemented this way because C++ can only return one value from a function or method. Perl, however, can return a list of values, so in Perl it is used as follows:

($x, $y, $descent, $externalLeading) = $window->GetTextExtent($string);

Unfortunately, there is as yet no definitive list of methods whose input arguments and return values are rearranged in wxPerl (unless you care to read the XS code in Window.xs in the wxPerl source distribution). So you will have to beware when invoking methods that, in C++, accept pointers to output variables.

Useful Links

• The WxWidgets library documentation site. C++-oriented.
• WxWidget (C++) alphabetical class reference. From the above website.
• Advice and information on WxWidgets programming, by topic. From the above website.