Wx::NewClass(3pm)

NAME

NewClass - adding a new class to wxPerl

o Are there constants or events that need to be wrapped?: see "COSTANTS" and "EVENTS".
o Is the class is derived from wxObject, from wxEvtHandler or from: another class?; see "CHOOSING A TYPEMAP".
o Are class instances destroyed by wxWidgets or should they be: garbage collected like normal Perl objects?; see "DESTRUCTORS AND THREADS".
o Does the class have overloaded methods?: see "OVERLOADING".
o Does the class have virtual methods that should be overridable from: Perl?; see "VIRTUAL METHODS".

Add a new file XS/NewClass.xsp and update the MANIFEST. Choose a relevant .xs file in the top level directory (es. Controls.xs) and add this line:: INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- -t typemap.xsp XS/NewClass.xsp
A skeleton for NewClass.xsp:: %module{Wx};; #include <wx/newclass.h> // use the relevant wxWidgets header(s); %name{Wx::NewClass} class wxNewClass : public wxSomeBaseClass
{
# constructors see the CONSTRUCTORS section
wxNewClass( wxWindow* some_window, const wxString& str );

# destructors
~wxNewClass();

# methods
wxString GetString() const;
void SetString( const wxString& str );; };
Add the typemap definition to typemap.tmpl. See "CHOOSING A TYPEMAP".

There are five typemaps that should work for most wxWidgets objects:

o "O_NON_WXOBJECT": for all classes that do not derive from "wxObject" AND do not need to be garbage collected.
o "O_NON_WXOBJECT_THR": for all classes that do not derive from "wxObject" AND need to be
garbage collected (see "DESTRUCTORS AND THREADS").
o "O_WXOBJECT": for all classes that derive from "wxObject" AND do not need to be
garbage collected.
o "O_WXOBJECT_THR": for all classes derived from "wxObject" AND need to be garbage
collected (see "DESTRUCTORS AND THREADS").
o "O_WXEVTHANDLER": for all classes that derive from "wxEvtHandler". See also
"CONSTRUCTORS".

For "O_WXEVTHANDLER" typemaps, there is some additional code that needs to be added to the constructor:: wxNewClass( wxWindow* some_window, const wxString& str )
%code{% RETVAL = new wxNewClass( some_window, str );
wxPli_create_evthandler( aTHX_ RETVAL, CLASS );
%};

For many classes not derived from "wxEvtHandler" you need to add a destructor to free the C++ object when the Perl object is garbage collected. At the XS++ level this means adding: ~wxNewClass();
to the class definition, but there is a catch: the Perl threading model.
Without going into details, this is needed for Perl threads compatibility:
o Use the correct typemap: choose either "O_NON_WXOBJECT_THR" or "O_WXOBJECT_THR".
o Implement a "CLONE" method: add this code inside the class declaration:

%{
static void
wxNewClass::CLONE()
CODE:
wxPli_thread_sv_clone( aTHX_ CLASS, (wxPliCloneSV)wxPli_detach_object );

%}
o Fix the destructor.: modify the destructor like this:

~wxNewClass()
%code%{ wxPli_thread_sv_unregister( aTHX_ "Wx::NewClass", THIS, ST(0) );
delete THIS;
%};