GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages


Manual Reference Pages  -  WX::NEWCLASS (3)

.ds Aq ’

NAME

NewClass - adding a new class to wxPerl

CONTENTS

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

Search for    or go to Top of page |  Section 3 |  Main Index


perl v5.20.3 WX::NEWCLASS (3) 2014-03-08

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.