Building a UI Framework with XML Resources (XRC)

Your XRC file -- when properly hooked up -- gives the initial configuration of your parcel's page. Your parcel code can alter the page dynamically after initialization, but the XRC file gives it a starting point.

It is be beyond the scope of the Chandler project to tell you everything there is to know about XRC. The XRC language is powerful but complicated, detailed, and wordy.However, because the existing documentation is a bit difficult to work with, this document will give some brief discussion.

While you might end up tweaking your XRC file by hand, you will probably like life better if you don't try to start from scratch. Instead, use an XRC editor or modify an existing file.

XRC editors

There are several XRC editors.

• XRCed, an XRC GUI. XRCed comes with the full Chandler sources; look for it at osaf/chandler/release/bin/xrced.
• tutorial for wxGlade, a wxWindows GUI builder

Existing XRC files

You can also start by copying an existing XRC files. There are examples in the Chandler parcels and also tucked away in our CVS tree.

Modifying an XRC file

Once you have an XRC file to act as a starting point, you will probably want to edit it by hand.

• Ignore the <?xml> and <resource> tags. (Don't delete them, just ignore them.)
• Make sure that you have a properly configured wxParcel object at the first level of objects (as discussed in HookingIntoChandler).
• If you have a parcel menu, make sure that it is properly configured (as discussed in HookingIntoChandler).
• Make sure that the very first line of the XRC file is the <?xml> line. Otherwise, you will get confusing error messages.

XRC files have basically three things to pay attention to

• layout controls
• flags
• widgets

The layout controls -- called "sizers" -- are somewhat complicated and a pain to work with. If you are designing a layout that is the least little bit complicated, you'll like life better if you use one of the XRC editors to do the layout.

Flags control subtleties of presentation and behavior. Those flags are specified in tags like <orient>, <style>, <flag>, and <border> but are (mostly) beyond the scope of this page. For more information on these flags, see the entry for the corresponding wxWindows control.

Below are examples of a few of the more common controls. What you need to pay attention to when creating the XRC file is the control name, as you will need that when you wire up the events (as discussed in HookingUpEvents). The names are important enough that on this page, control names are highlighted in red.

Below are some useful control widgets and simple corresponding XRC code for them.

Buttons

<object class="wxButton" name="FooButton">
    <label>This is a Foo Button</label>
</object>

Text

<object class="wxStaticText" name="FooText">
    <label>This is some static Foo text.</label>
</object>

Radio Buttons

<object class="wxRadioBox" name="FooRadioBox">
    <style>wxRA_SPECIFY_COLS</style>
    <label>Select Foo:</label>
    <dimension>1</dimension>
    <selection>0</selection>
    <content>
        <item>Choice 1</item>
        <item>Choice 2</item>
        <item>Choice 3</item>
    </content>
</object>

Text Entry Fields

<object class="wxTextCtrl" name="FooTextEntry">
    <style>wxTE_PROCESS_ENTER</style>
    <size>100,-1</size>
</object>

Here you see the wxTE_PROCESS_ENTER flag. If the flag is present, then pressing ENTER in a text entry box will cause an event. Otherwise, pressing ENTER will insert a line break in the text entry field.

There appears to be a bug in wxTextCtrl: pressing ENTER will cause an event in the Windows version of wxTextCtrl, even if wxTE_PROCESS_ENTER is not set.

XRC documentation

There is some existing XRC documentation at:

• from wxPython.org
• from wxWindows.org
• in wxPython source

-- DuckySherwood - 09 Apr 2003