NAME

NewClass - adding a new class to wxPerl

CHECKLIST

• Are there constants or events that need to be wrapped?

  see "COSTANTS" and "EVENTS".

• Is the class is derived from wxObject, from wxEvtHandler or from another class?

  see "CHOOSING A TYPEMAP".

• Are class instances destroyed by wxWidgets or should they be garbage collected like normal Perl objects?

  see "DESTRUCTORS AND THREADS".

• Does the class have overloaded methods?

  see "OVERLOADING".

• Does the class have virtual methods that should be overridable from Perl?

  see "VIRTUAL METHODS".

SKELETON

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".

CHOOSING A TYPEMAP

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

• O_NON_WXOBJECT

  for all classes that do not derive from wxObject AND do not need to be garbage collected.

• O_NON_WXOBJECT_THR

  for all classes that do not derive from wxObject AND need to be garbage collected (see "DESTRUCTORS AND THREADS").

• O_WXOBJECT

  for all classes that derive from wxObject AND do not need to be garbage collected.

• O_WXOBJECT_THR

  for all classes derived from wxObject AND need to be garbage collected (see "DESTRUCTORS AND THREADS").

• O_WXEVTHANDLER

  for all classes that derive from wxEvtHandler. See also "CONSTRUCTORS".

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 );
            %};

DESTRUCTORS AND THREADS

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:

• Use the correct typemap

  choose either O_NON_WXOBJECT_THR or O_WXOBJECT_THR.

• 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 );
  %}

• Fix the destructor.

  modify the destructor like this:

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