Using Subclass

Subclass is a property that can be found in the wxWindow section of the property grid for each control. The idea behind subclass is to make it easy to use a custom class that is a child of a standard widget.

For example, I want to make a custom text control to change the default response to a keystroke. It looks just like a wxTextCtrl, it just acts differently.

class wxCustomTextCtrl : public wxTextCtrl
{
public:
  // It is important that the custom class has an identical constructor
  wxCustomTextCtrl( wxWindow* parent, wxWindowID id, const wxString& value, const wxPoint& pos, const wxSize& size, long style );

  /* More code follows */

};

Before the subclass property, I would have had to create a wxCustomTextCtrl and add it to a sizer manually. It was tedious to do and difficult to visualize. Example:

#include "wxCustomTextCtrl.h"

/* some unrelated code */

// I need to get a sizer to add the wxCustomTextCtrl to. Assume I have a panel member named m_memberPanel.
wxSizer* sizer = m_memberPanel->GetSizer();
if ( sizer )
{
  wxCustomTextCtrl* myCustomCtrl = new wxCustomTextCtrl( m_memberPanel, -1 );
  sizer->Add( myCustomCtrl, 1, wxEXPAND | wxALL, 5 );
}

/* more unrelated code */

Now, using the subclass property, I can place a wxTextCtrl using wxFormBuilder and generate code for a wxCustomTextCtrl. Essentially, this causes wxFormBuilder to replace the text "wxTextCtrl" with the text "wxCustomTextCtrl" in all generated code, so it is important that the constructor of the custom class matches the constructor of the class it replaces.

Example:

/* In the header generated by wxFormbuilder */

// With the subclass property blank
wxTextCtrl* m_textCtrl;

// With subclass = wxCustomTextCtrl
wxCustomTextCtrl* m_textCtrl;

/* In the source file generated by wxFormbuilder */

// With the subclass property blank
m_textCtrl = new wxTextCtrl( this, ID_DEFAULT, wxT(""), wxDefaultPosition, wxDefaultSize, 0 );

// With subclass = wxCustomTextCtrl
m_textCtrl = new wxCustomTextCtrl( this, ID_DEFAULT, wxT(""), wxDefaultPosition, wxDefaultSize, 0 );

The only tricky part is remembering that this code will not compile unless the header where the wxCustomTextCtrl class is declared is included in the files generated by wxFormBuilder.

In version 3.0 beta 2 and beyond, there is a "header" child of the subclass property. Just enter the header where the subclass is declared, and it will be included in the appropriate generated file.

Prior to version 3.0 beta 2, there was a "user_headers" property on the project item (the very top item in the object tree). Add the header where wxCustomTextCtrl is declared to the user_headers property, and wxFormBuilder will include that header in the generated files.