|
|
DLPAR Error
|
|
Wx::NewClass(3pm) User Contributed Perl Documentation Wx::NewClass(3pm) NAME
NewClass - adding a new class to wxPerl CHECKLIST
o Are there constants or events that need to be wrapped? see "CONSTANTS" 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". SKELETON
Add a new file XS/NewClass.xsp and update the MANIFEST. Choose a relevant .xs file in the top level directory (eg. 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". If adding a class related to one of the wxPerl submodules ("Wx::RichText", "Wx::Html", ...) add the .xsp file to the relevant subdirectory and modify the .xs and typemap files in that subdirectory. 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". 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: 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; %}; VIRTUAL METHODS
The wrapping of virtual functions whose arguments are simple C++ types (integrals, bool, floating point) and common wxWidgets types (wxString) should be automatic: at the top of the file, load the plugin that handles virtual methods %loadplugin{build::Wx::XSP::Virtual}; and decorate virtual/pure virtual methods using the %Virtual directive // pure virtual virtual wxString GetTitle() const = 0 %Virtual{pure}; // virtual, not pure virtual int GetBestFittingWidth(unsigned int idx) const %Virtual; If the class contains pure virtual methods, it will be marked as abstract, and it will have no constructors. For abstract classes, XS++ will create an additional Perl-level class, called "Wx::Pl<classname>"; in order to override the virtual methods, you must derive from this class, and not from "Wx::<classname>". TODO allow changing the default behaviour for abstract/concrete classes TODO allow overriding the class name TODO allow specifying custom code TODO handle multiple return values TODO customized type mapping perl v5.14.2 2010-06-07 Wx::NewClass(3pm)
