tresourc.tex

Wxpython Implemented on Windows CE, Source code

\section{The wxWindows resource system}\label{resourceformats}

wxWindows has an optional {\it resource file} facility,
which allows separation of dialog, menu, bitmap and icon specifications
from the application code.

{\bf NOTE:} this format is now deprecated in favour of the XML-based \helpref{XRC resource system}{xrcoverview}.
However it is still available if wxUSE\_RESOURCES is enabled.

The format is similar in principle to the Windows resource file (whose ASCII form is
suffixed .RC and whose binary form is suffixed .RES). The wxWindows resource
file is currently ASCII-only, suffixed .WXR. Note that under Windows,
the .WXR file does not {\it replace} the native Windows resource file,
it merely supplements it. There is no existing native resource format in X
(except for the defaults file, which has limited expressive power).

For details of functions for manipulating resource files and loading
user interface elements, see \helpref{wxWindows resource functions}{resourcefuncs}.

You can use Dialog Editor to create resource files. Unfortunately neither
Dialog Editor nor the .WXR format currently cover all wxWindows controls;
some are missing, such as wxSpinCtrl, wxSpinButton, wxListCtrl, wxTreeCtrl and others.

Note that in later versions of wxWindows, this resource format will be replaced
by XML specifications that can also include sizers.

\subsection{The format of a .WXR file}

A wxWindows resource file may look a little odd at first. It is C++
compatible, comprising mostly of static string variable declarations with
wxExpr syntax within the string.

Here's a sample .WXR file:

\begin{verbatim}
/*
 * wxWindows Resource File
 *
 */

#include "noname.ids"

static char *my_resource = "bitmap(name = 'my_resource',\
  bitmap = ['myproject', wxBITMAP_TYPE_BMP_RESOURCE, 'WINDOWS'],\
  bitmap = ['myproject.xpm', wxBITMAP_TYPE_XPM, 'X']).";

static char *menuBar11 = "menu(name = 'menuBar11',\
  menu = \
  [\
    ['&File', 1, '', \
      ['&Open File', 2, 'Open a file'],\
      ['&Save File', 3, 'Save a file'],\
      [],\
      ['E&xit', 4, 'Exit program']\
    ],\
    ['&Help', 5, '', \
      ['&About', 6, 'About this program']\
    ]\
  ]).";

static char *project_resource = "icon(name = 'project_resource',\
  icon = ['project', wxBITMAP_TYPE_ICO_RESOURCE, 'WINDOWS'],\
  icon = ['project_data', wxBITMAP_TYPE_XBM, 'X']).";

static char *panel3 = "dialog(name = 'panel3',\
  style = '',\
  title = 'untitled',\
  button_font = [14, 'wxSWISS', 'wxNORMAL', 'wxBOLD', 0],\
  label_font = [10, 'wxSWISS', 'wxNORMAL', 'wxNORMAL', 0],\
  x = 0, y = 37, width = 292, height = 164,\
  control = [1000, wxButton, 'OK', '', 'button5', 23, 34, -1, -1, 'my_resource'],\
  control = [1001, wxStaticText, 'A Label', '', 'message7', 166, 61, -1, -1, 'my_resource'],\
  control = [1002, wxTextCtrl, 'Text', 'wxTE_MULTITEXT', 'text8', 24, 110, -1, -1]).";
\end{verbatim}

As you can see, C++-style comments are allowed, and apparently include files
are supported too: but this is a special case, where the included file
is a file of defines shared by the C++ application code and resource file
to relate identifiers (such as FILE\_OPEN) to integers.

Each {\it resource object} is of standard \helpref{wxExpr}{wxexpr} syntax, that is,
an object name such as {\bf dialog} or {\bf icon}, then an open
parenthesis, a list of comma-delimited attribute/value pairs, a closing
parenthesis, and a full stop. Backslashes are required to escape newlines,
for the benefit of C++ syntax. If double quotation marks are used to
delimit strings, they need to be escaped with backslash within a C++ string
(so it is easier to use single quotation marks instead).

\normalbox{{\it A note on string syntax:} A string that begins with
an alphabetic character, and contains only alphanumeric characters,
hyphens and underscores, need not be quoted at all. Single quotes and double
quotes may be used to delimit more complex strings. In fact, single-quoted
and no-quoted strings are actually called {\it words}, but are treated
as strings for the purpose of the resource system.}

A resource file like this is typically included in the application main file,
as if it were a normal C++ file. This eliminates the need for a separate
resource file to be distributed alongside the executable. However, the
resource file can be dynamically loaded if desired (useful for non-C++
languages such as Python).

Once included, the resources need to be `parsed' (interpreted), because
so far the data is just a number of static string variables. The function\rtfsp
{\bf ::wxResourceParseData} is called early on in initialization of the application
(usually in {\bf wxApp::OnInit}) with a variable as argument. This may need to be
called a number of times, one for each variable. However, more than one
resource `object' can be stored in one string variable at a time, so you can
get all your resources into one variable if you want to.

{\bf ::wxResourceParseData} parses the contents of the resource, ready for use
by functions such as {\bf ::wxResourceCreateBitmap} and {\bf wxPanel::LoadFromResource}.

If a wxWindows resource object (such as a bitmap resource) refers to a
C++ data structure, such as static XPM data, a further call ({\bf ::wxResourceRegisterBitmapData}) needs
to be made on initialization to tell
wxWindows about this data. The wxWindows resource object will refer to a
string identifier, such as `project\_data' in the example file above.
This identifier will be looked up in a table to get the C++ static data
to use for the bitmap or icon.

In the C++ fragment below, the WXR resource file is included,
and appropriate resource initialization is carried out in {\bf OnInit}.
Note that at this stage, no actual wxWindows dialogs, menus, bitmaps or
icons are created; their `templates' are merely being set up for later
use.

\begin{verbatim}
/*
 * File:    project.cpp
 * Purpose: main application module
 */

#include "wx/wx.h"
#include "project.h"

// Includes the dialog, menu etc. resources
#include "project.wxr"

// Includes XPM data
#include "project.xpm"

IMPLEMENT_APP(AppClass)

// Called to initialize the program
bool AppClass::OnInit()
{
  wxResourceRegisterBitmapData("project_data", project_bits, project_width, project_height);

  wxResourceParseData(menuBar11);
  wxResourceParseData(my_resource);
  wxResourceParseData(project_resource);
  wxResourceParseData(panel3);
  ...

  return true;
}
\end{verbatim}

The following code shows a dialog:

\begin{verbatim}
  // project.wxr contains dialog1
  MyDialog *dialog = new MyDialog;
  if (dialog->LoadFromResource(this, "dialog1"))
  {
    wxTextCtrl *text = (wxTextCtrl *)wxFindWindowByName("text3", dialog);
    if (text)
      text->SetValue("wxWindows resource demo");