Managing Plug-in Resources

Prerequisites

You may want to read the tutorial Creating a simple "Hello_World" plugin before starting this tutorial

This tutorial assumes you have a working version of Code::Blocks installed and some knowledge of how to deal with projects, in particular how to compile them. To use the Code::Blocks SDK you must also have a working version of wxWidgets installed. For more information see Compiling wxWidgets (MSW) 2.8.12 on Windows using makefile.gcc

REVISE THIS...To develop Code::Blocks plugins you will also need a copy of the Code::Blocks SDK, which can be found on the Code::Blocks download page. Install this to somewhere sensible that you will remember later on. Personally I keep the SDK in a folder called CodeBlocks\sdk (which contains the include/ and lib/ from in the zip). This means that the header files refered to in the tutorial would be found under Codeblocks\sdk\include, so cbPlugin.h is Codeblocks\sdk\include\cbPlugin.h for example.

Overview

This tutorial will show you how to package and access Resources (toolbars, forms, dialogs and bitmaps) and other static data in your plug-in.

Plugin File Structure

Every plugin in its undeployed state is simply a nested file structure in compressed archive form (zip). The typical structure of a plugin (which we'll call "myplugin" in this tutorial) is as follows:

+myplugin.cbplugin
 +myplugin.dll
 +myplugin.png
 +myplugin-off.png
 +myplugin.zip
  +manifest.xml
  +XML Based Resources
 +Extra Files

The essential components of this structure are created automatically when you build a plugin project created with the CB Plugin Wizard. What are these files?

• myplugin.cbplugin: this is simply a zip archive containing all of the plugins files and resources. It is given a cbplugin extension to make it easy for the Code::Blocks plugin installer to recognize.
• myplugin.dll (or _libmy-plugin.so_ on linux): the compiled shared library containing you plugins executable content
• myplugin.png: this is an 80x80 bitmap displayed by default in the image list in "Environment Settings" when the plugins configuration has the focus (for plugins that have a configuaration panel). This file is optional
• myplugin-off.png: this is an 80x80 bitmap displayed by default in the image list in "Environment Settings" when the plugins configuration does not have the focus(for plugins that have a configuaration panel). This file is optional
• myplugin.zip: a compressed archive file containing the file manifest.xml and resources
• manifest.xml: a file containing information about the plugin. (see the Creating a simple "Hello_World" plugin)
• XML Based Resources: One or more wxWidgets XML based resource files (XRC files) such as toolbars, dialogs and forms. You can also place binary bitmap images in this archive if they are accompanied by an XRC descriptor file. XML Resources are optional
• Extra Files: Place other static, non-XRC resources here. You should keep these files to a mimimum because they are copied to the shared space of the users Code::Blocks installation. These files are optional

In this tutorial we will discuss the use of XML Based Resources and Extra Files

Tutorial: Creating a New Plugin and Examining Its Structure

We will use this tutorial to demonstrate concepts associated with plugin resource management throughout the article. Before you start, make sure you have installed wxWidgets, compiled a recent nightly build or have a current Code::Blocks release with a copy of the SDK installed. (TODO: Links to relevant instructions)

1. Select file -> new -> project

2. Select projects, code::blocks plugin, then click "GO"

3. Project title "Plugin_XRC_Example", then click "Next"

4. Plugin Name "XRC_Example", Plugin Type "Generic", Check "Creates Menu Entries", then click "Next"

5. Click Next/Finish on the remaining items (I'm assuming you will use wxWidgets 2.8.X, the GCC compiler)

6. You should now have a new plugin project. Compile and make sure it works correctly. Specifically you should see in the build log window:

Running target post-build steps
zip -j9 XRC_Example.zip manifest.xml
 adding: manifest.xml (188 bytes security) (deflated 52%)
zip -j9 XRC_Example.cbplugin XRC_Example.dll XRC_Example.zip
 adding: XRC_Example.dll
 (188 bytes security) (deflated 83%)
 adding: XRC_Example.zip (188 bytes security) (deflated 8%)

As you can see, Code::Blocks automatically creates a minimal XRC_Example.cbplugin file for you. If you have a GUI Archive tool such as 7-zip or WinZIP, you should be able to browse to your project, open XRC_Example.cbplugin with your archive tool and confirm it conforms to the minimal structure. In the remainder of the tutorial we will add additional resources to this simple plugin.

Working with XML Based wxWidgets Resources

What is XRC and why would I want to use it?

XRC is a standardized way of describing wxWidgets forms (including panels and dialogs), menus, toolbars and bitmap lists in a human readable XML format. A simple example is the XRC file for the compiler toolbar (found in the CB source at: src/plugins/compilergcc/resources/compiler_toolbar.xrc):

<?xml version="1.0" ?>
<resource>
  <object class="wxToolBarAddOn" name="compiler_toolbar">
    <object class="tool" name="idCompilerMenuCompile">
      <tooltip>Build</tooltip>
      <longhelp>Build the active project</longhelp>
      <bitmap>images/compile.png</bitmap>
    </object>
    <object class="tool" name="idCompilerMenuRun">
      <tooltip>Run</tooltip>
      <longhelp>Run the active project</longhelp>
      <bitmap>images/run.png</bitmap>
    </object>
...
...
...
    <object class="separator"/>
    <object class="wxStaticText" name="idToolTargetLabel">
      <label>Build target:</label>
    </object>
    <object class="wxChoice" name="idToolTarget">
      <content/>
        <size>160,-1</size>
    </object>
  </object>
</resource>

As you can see, this file specifies that it is an XML file in the first line, that it contains resources denoted by the <resource> and </resource> tags in the second and last lines respectively. Within the resource tags, the XRC file specifies a sequence of objects laid out in a hierarchical structure. Each object belongs to a class (specified with the attribute class, and corresponding to a wxWidgets form or control class) and has a unique identifier. In this file there is only one base level object, named "compiler_toolbar" derived from the Code::Blocks class "wxToolBarAddOn", a Code::Blocks extension of the wxWidgets type "wxToolbar". Note that base level objects are restricted to a handful of types, namely:

• Frames
• Dialogs
• Panels
• MenuBars
• Menus
• Toolbars
• Bitmaps
• Icons

In contrast, the objects owned by base level objects run the entire gamut of wxWidgets controls. In the case of the Compiler toolbar, it owns a sequence of standard bitmap toolbar buttons (idCompilerMenuCompile, idCompilerMenuRun etc), a static text control (idToolTargetLabel) and a choice box (idToolTarget). Panels and dialogs will also contain layout objects derived from classes such as wxSizer. In addition to the basic class and name attributes, base and lower level objects in an XRC file will specify additional detail about their structure, such as associated images, sizing and layout (basically giving you the same control over the intialization of an object as if you had executed its constructor in your c++ code).

While somewhat verbose, the XML-based XRC file is far more readable than the terse 50+ lines of equivalent C++ code required to create a toolbar, load its images and assign unique ids. XRC files can be loaded and displayed in a few lines of C++. You still retain the ability to access individual controls loaded from the XRC. We'll deal with these issues shortly.

In addition to its readability, XRC offers the advantage of separating form layout (contained in the XRC file) from form logic (coded into your plugin binary). XRC files are loaded each time you start your plugin, which allows you to make changes to the layout of a form without the need to recompile you plugin.

A definitive description of the XRC syntax is described in the wxWidgets wiki at http://www.wxwidgets.org/wiki/index.php/Using_XML_Resources_with_XRC

Creating XRC files for use in your plugin

While you can create your own XRC widget layouts by coding the XML in a simple text editor, it is far easier to use a GUI program to create the layout, XML and accompanying C++ code for you. For example, in Code::Blocks you can use the wxSmith plugin to design your XRC forms and accompanying C++ classes for your plugin. wxFormBuilder (TODO: link) is another alternative.

Tutorial Continued: Creation of an XRC Panel using wxSmith

Now we will add a simple XRC-based panel to our plugin using wxSmith:

7. Select wxSmith -> Add panel

8. Use the class name "TaskPanel", check "XRC file", then press OK

9. The management window should now show a "Resources" tab and open a new editor window displaying an empty panel with a toolbar containing widgets below it. (TODO: screen shot)

10. From the widget toolbar, select "Layout" tab, then choose wxBoxSizer and click anywhere in the panel. After you click the panel, it will be resized and you should see a border indicating the presence of a sizer. A Box Sizer is a container for widgets, that lays out the widgets in either a horizontal or vertical layout. (TODO: Link to more info on sizers)

11. From the widget toolbar, select "Standard" tab, then choose wxComboBox and click within the sizer. This adds a ComboBox to the sizer

12. Choose wxTextCtrl and click within the sizer. This adds a Text Control to the sizer (it should be located to the right of the combo box)

13. In the resources tab, click on the wxBoxSizer entry in the widget tree. Properties for the Box Sizer should appear in the bottom half of this tab. Change the orientation property to wxVertical.

14. Now click on the wxTextCtrl entry in the widget tree, open the styles property and check "wxTE_MULTILINE". Also check the "Expand" property, which will expand the control to the full width of the panel.

15. Now click on the wxComboBox entry in the widget tree, change the proportion property to zero. This tells the Box Sizer to only expand the Text Control when the size of the panel changes (the Text Control has a positive proportion). Also check the "Expand" property.

16. Save your work. This will save the panel and create the XRC file "TaskPanel.xrc" and C++ header and sources TaskPanel.cpp/TaskPanel.h. You should now have a panel that looks like the following screen shot:

17. Close the wxSmith editor.

Working with XRC files in your plugin

After you have created your XRC file defining your objects, you will want to be able to use them in your plugin. To do this, we generally want to create a new C++ class associated with each resource object. In the constructor of each class we will use wxWidgets resource loader to find, load and create an instance of the object. Optionally we will associate the widgets contained within each object with member variables.

wxWidgets library offers a global XRC manager wxXmlResource and a number of convenience functions and macros for working with objects defined in XRC files. In general, for each object defined in XRC you will:

• Define a C++ class that corresponds to the object (e.g. Create a class derived from wxDialog for each Dialog defined in the XRC)
• Call wxXmlResource::Get()->LoadXXXX(this, parent, "object_name", [class_derived_from]) in the constructor of your class (where LoadXXXX will be one of LoadBitmap, LoadDialog, LoadPanel, LoadObject etc)
• Access controls of the object using the macro: XRCCTRL(this, "control_name", controlclass) (or alternatively using XRCID and the FindWindow(XRCID("control_name")) method (see the next part of the tutorial below))
• Use the XRCID("control_name") macro to refer to an object's controls in Event tables. For example: EVT_TEXT(XRCID("ID_TEXTCTRL1"), TaskPanel::TextChange)

TODO: wxWidgets links for more info

Tutorial Continued: Associate XRC Objects and Controls with C++ Classes and Members

In this part of the tutorial, we will see how wxSmith maps XRC objects to C++ Classes.

18. It will be helpful to add the XRC file to the project (if it wasn't added already). Select project -> add file and select "TaskPanel.xrc"

19. From the management pane, choose "Projects" tab, expand the resources folder of the project and you should see the newly added XRC file

20. Let's take a look at the contents of the XRC file. Right click on the XRC file, select open with, internal editor. The contents of the file should look something like:

<?xml version="1.0" encoding="utf-8" ?>
<resource xmlns="http://www.wxwidgets.org/wxxrc">
	<object class="wxPanel" name="TaskPanel">
		<object class="wxBoxSizer">
			<orient>wxVERTICAL</orient>
			<object class="sizeritem">
				<object class="wxComboBox" name="ID_COMBOBOX1" />
				<flag>wxALL|wxEXPAND|wxALIGN_CENTER_HORIZONTAL|wxALIGN_CENTER_VERTICAL</flag>
				<border>5</border>
			</object>
			<object class="sizeritem">
				<object class="wxTextCtrl" name="ID_TEXTCTRL1">
					<value>Text</value>
					<style>wxTE_MULTILINE</style>
				</object>
				<flag>wxALL|wxEXPAND|wxALIGN_CENTER_HORIZONTAL|wxALIGN_CENTER_VERTICAL</flag>
				<border>5</border>
				<option>1</option>
			</object>
		</object>
	</object>
</resource>

We see our base object is a wxPanel called TaskPanel and it contains a box sizer with two widgets "ID_COMBOBOX1" and "ID_TEXTCTRL1". Close the XRC file.

21. wxSmith will already have added TaskPanel.cpp and TaskPanel.h to your project. TaskPanel.h defines a minimal TaskPanel class (I've taken the liberty of trimming some of the file contents) and defines pointers to the two controls in the Panel

class TaskPanel: public wxPanel
{
	public:
		TaskPanel(wxWindow* parent);
		virtual ~TaskPanel();
		//(*Declarations(TaskPanel)
		wxComboBox* ComboBox1;
		wxTextCtrl* TextCtrl1;
		//*)
		DECLARE_EVENT_TABLE()
};

Open TaskPanel.cpp and you should see the following implementations:

BEGIN_EVENT_TABLE(TaskPanel,wxPanel)
	//(*EventTable(TaskPanel)
	//*)
END_EVENT_TABLE()

TaskPanel::TaskPanel(wxWindow* parent)
{
	//(*Initialize(TaskPanel)
	wxXmlResource::Get()->LoadObject(this,parent,_T("TaskPanel"),_T("wxPanel"));
	ComboBox1 = (wxComboBox*)FindWindow(XRCID("ID_COMBOBOX1"));
	TextCtrl1 = (wxTextCtrl*)FindWindow(XRCID("ID_TEXTCTRL1"));
	//*)
}

TaskPanel::~TaskPanel()
{
	//(*Destroy(TaskPanel)
	//*)
}

The good news is wxSmith takes care of the hard work involved in creating a class corresponding to your XML object and its controls. This is all done in the TaskPanel constructor. The line

wxXmlResource::Get()->LoadObject(this,parent,_T("TaskPanel"),_T("wxPanel"));

will search among the codeblocks resources (including all plugin resources) for an XRC object named TaskPanel and create an instance of it derived from the wxPanel class. The call to LoadObject is used in place of a call to the wxPanel constructor (make sure that if you edit this code you do not call the wxPanel constructor. Moreover, do not edit inside the comment blocks //(* and //*) as these are wxSmith controlled portions of your code and will be overwritten each time you save your GUI Layouts in the wxSmith editor) The next two lines

ComboBox1 = (wxComboBox*)FindWindow(XRCID("ID_COMBOBOX1"));
TextCtrl1 = (wxTextCtrl*)FindWindow(XRCID("ID_TEXTCTRL1"));

create member pointers to the Combo Box and Text Control widgets, making it easy for you to refer to those widgets in your programming logic. Notice that there is no need to release anything in the TaskPanel class destructor.

"But what if I don't want to use wxSmith?"

No problem. Other GUI builders can also create the necessary code to define and instantiate your XRC objects as C++ Classes, which should closely correspond to the code generated by wxSmith. You will need to manually add the XRC objects and C++ files that were created by these builders to your plugin project.

If you don't want to use automatically generated code at all, that's fine too, but you will then need to create the Class by hand using appropriate calls to LoadDialog, LoadPanel, LoadObject and friends.

Tutorial Continued: Programming your XRC objects and controls

CONTENT COMING SOON

Tutorial Continued: Adding the XRC file to your cbplugin bundle

CONTENT COMING SOON

Working with Extra Files

MORE CONTENT COMING SOON...

Further Information

It is essential to learn how wxWidgets works if you seriously plan on working on plugins, since most of Code::Blocks depends on it, and you will find it easier to add and manipulate components if you have a firm grasp of its principles. More information on this can be found in the wxWidgets documentation. Another good place to learn from is the source code from the existing Code::Blocks plugins, which can be downloaded along with the rest of the Code::Blocks source code from the download page.