Contents Up Previous Next 原文へのリンク

The wxWidgets resource system

wxWidgets has an optional resource file facility, which allows separation of dialog, menu, bitmap and icon specifications from the application code.

NOTE: this format is now deprecated in favour of the XML-based XRC resource system. 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 wxWidgets resource file is currently ASCII-only, suffixed .WXR. Note that under Windows, the .WXR file does not 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 wxWidgets resource functions.

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

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

The format of a .WXR file
Dialog resource format
Menubar resource format
Bitmap resource format
Icon resource format
Resource format design issues
Compiling the resource system


The format of a .WXR file

A wxWidgets 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:

/*
 * wxWidgets 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]).";
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 resource object is of standard wxExpr syntax, that is, an object name such as dialog or 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).


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 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 ::wxResourceParseData is called early on in initialization of the application (usually in 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.

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

If a wxWidgets resource object (such as a bitmap resource) refers to a C++ data structure, such as static XPM data, a further call (::wxResourceRegisterBitmapData) needs to be made on initialization to tell wxWidgets about this data. The wxWidgets 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 OnInit. Note that at this stage, no actual wxWidgets dialogs, menus, bitmaps or icons are created; their 'templates' are merely being set up for later use.

/*
 * 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;
}
The following code shows a dialog:

  // project.wxr contains dialog1
  MyDialog *dialog = new MyDialog;
  if (dialog->LoadFromResource(this, "dialog1"))
  {
    wxTextCtrl *text = (wxTextCtrl *)wxFindWindowByName("text3", dialog);
    if (text)
      text->SetValue("wxWidgets resource demo");
    dialog->ShowModal();
  }
  dialog->Destroy();
Please see also the resource sample.


Dialog resource format

A dialog resource object may be used for either panels or dialog boxes, and consists of the following attributes. In the following, a font specification is a list consisting of point size, family, style, weight, underlined, optional facename.

.
Attribute Value
id The integer identifier of the resource.
name The name of the resource.
style Optional dialog box or panel window style.
title The title of the dialog box (unused if a panel).
modal Whether modal: 1 if modal, 0 if modeless, absent if a panel resource.
use_dialog_units If 1, use dialog units (dependent on the dialog font size) for control sizes and positions.
use_system_defaults If 1, override colours and fonts to use system settings instead.
button_font The font used for control buttons: a list comprising point size (integer), family (string), font style (string), font weight (string) and underlining (0 or 1).
label_font The font used for control labels: a list comprising point size (integer), family (string), font style (string), font weight (string) and underlining (0 or 1). Now obsolete; use button_font instead.
x The x position of the dialog or panel.
y The y position of the dialog or panel.
width The width of the dialog or panel.
height The height of the dialog or panel.
background_colour The background colour of the dialog or panel.
label_colour The default label colour for the children of the dialog or panel. Now obsolete; use button_colour instead.
button_colour The default button text colour for the children of the dialog or panel.

Then comes zero or more attributes named 'control' for each control (panel item) on the dialog or panel. The value is a list of further elements. In the table below, the names in the first column correspond to the first element of the value list, and the second column details the remaining elements of the list. Note that titles for some controls are obsolete (they don't have titles), but the syntax is retained for backward compatibility.

Control Values
wxButton id (integer), title (string), window style (string), name (string), x, y, width, height, button bitmap resource (optional string), button font spec
wxCheckBox id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional integer, 1 or 0), label font spec
wxChoice id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), label font spec, button font spec
wxComboBox id (integer), title (string), window style (string), name (string), x, y, width, height, default text value, values (optional list of strings), label font spec, button font spec
wxGauge id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer), range (optional integer), label font spec, button font spec
wxStaticBox id (integer), title (string), window style (string), name (string), x, y, width, height, label font spec
wxListBox id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), multiple (optional string, wxSINGLE or wxMULTIPLE), label font spec, button font spec
wxStaticText id (integer), title (string), window style (string), name (string), x, y, width, height, message bitmap resource (optional string), label font spec
wxRadioBox id (integer), title (string), window style (string), name (string), x, y, width, height, values (optional list of strings), number of rows or cols, label font spec, button font spec
wxRadioButton id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional integer, 1 or 0), label font spec
wxScrollBar id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer), page length (optional integer), object length (optional integer), view length (optional integer)
wxSlider id (integer), title (string), window style (string), name (string), x, y, width, height, value (optional integer), minimum (optional integer), maximum (optional integer), label font spec, button font spec
wxTextCtrl id (integer), title (string), window style (string), name (string), x, y, width, height, default value (optional string), label font spec, button font spec


Menubar resource format

A menubar resource object consists of the following attributes.

Attribute Value
name The name of the menubar resource.
menu A list containing all the menus, as detailed below.

The value of the menu attribute is a list of menu item specifications, where each menu item specification is itself a list comprising:

If the menu item specification is the empty list ([]), this is interpreted as a menu separator.

If further (optional) information is associated with each menu item in a future release of wxWidgets, it will be placed after the help string and before the optional pulldown menu specifications.

Note that the menu item identifier must be an integer if the resource is being included as C++ code and then parsed on initialisation. Unfortunately, #define substitution is not performed inside strings, and therefore the program cannot know the mapping. However, if the .WXR file is being loaded dynamically, wxWidgets will attempt to replace string identifiers with #defined integers, because it is able to parse the included #defines.


Bitmap resource format

A bitmap resource object consists of a name attribute, and one or more bitmap attributes. There can be more than one of these to allow specification of bitmaps that are optimum for the platform and display.


Icon resource format

An icon resource object consists of a name attribute, and one or more icon attributes. There can be more than one of these to allow specification of icons that are optimum for the platform and display.


Resource format design issues

The .WXR file format is a recent addition and subject to change. The use of an ASCII resource file format may seem rather inefficient, but this choice has a number of advantages:

The disadvantages of the approach include:


Compiling the resource system

To enable the resource system, set wxUSE_WX_RESOURCES to 1 in setup.h.