1Wx::NewClass(3)       User Contributed Perl Documentation      Wx::NewClass(3)
2
3
4

NAME

6       NewClass - adding a new class to wxPerl
7

CHECKLIST

9       •   Are there constants or events that need to be wrapped?
10
11           see "CONSTANTS" and "EVENTS".
12
13       •   Is the class is derived from wxObject, from wxEvtHandler or from
14           another class?
15
16           see "CHOOSING A TYPEMAP".
17
18       •   Are class instances destroyed by wxWidgets or should they be
19           garbage collected like normal Perl objects?
20
21           see "DESTRUCTORS AND THREADS".
22
23       •   Does the class have overloaded methods?
24
25           see "OVERLOADING".
26
27       •   Does the class have virtual methods that should be overridable from
28           Perl?
29
30           see "VIRTUAL METHODS".
31

SKELETON

33       Add a new file XS/NewClass.xsp and update the MANIFEST.  Choose a
34       relevant .xs file in the top level directory (eg. Controls.xs) and add
35       this line:
36
37           INCLUDE_COMMAND: $^X -MExtUtils::XSpp::Cmd -e xspp -- -t typemap.xsp XS/NewClass.xsp
38
39       A skeleton for NewClass.xsp:
40
41           %module{Wx};
42
43           #include <wx/newclass.h> // use the relevant wxWidgets header(s)
44
45           %name{Wx::NewClass} class wxNewClass : public wxSomeBaseClass
46           {
47               # constructors see the CONSTRUCTORS section
48               wxNewClass( wxWindow* some_window, const wxString& str );
49
50               # destructors
51               ~wxNewClass();
52
53               # methods
54               wxString GetString() const;
55               void SetString( const wxString& str );
56           };
57
58       Add the typemap definition to typemap.tmpl.  See "CHOOSING A TYPEMAP".
59
60       If adding a class related to one of the wxPerl submodules
61       ("Wx::RichText", "Wx::Html", ...) add the .xsp file to the relevant
62       subdirectory and modify the .xs and typemap files in that subdirectory.
63

CHOOSING A TYPEMAP

65       There are five typemaps that should work for most wxWidgets objects:
66
67       •   "O_NON_WXOBJECT"
68
69           for all classes that do not derive from "wxObject" AND do not need
70           to be garbage collected.
71
72       •   "O_NON_WXOBJECT_THR"
73
74           for all classes that do not derive from "wxObject" AND need to be
75           garbage collected (see "DESTRUCTORS AND THREADS").
76
77       •   "O_WXOBJECT"
78
79           for all classes that derive from "wxObject" AND do not need to be
80           garbage collected.
81
82       •   "O_WXOBJECT_THR"
83
84           for all classes derived from "wxObject" AND need to be garbage
85           collected (see "DESTRUCTORS AND THREADS").
86
87       •   "O_WXEVTHANDLER"
88
89           for all classes that derive from "wxEvtHandler".  See also
90           "CONSTRUCTORS".
91

CONSTRUCTORS

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

DESTRUCTORS AND THREADS

102       For many classes not derived from "wxEvtHandler" you need to add a
103       destructor to free the C++ object when the Perl object is garbage
104       collected.  At the XS++ level this means adding
105
106           ~wxNewClass();
107
108       to the class definition, but there is a catch: the Perl threading
109       model.
110
111       Without going into details, this is needed for Perl threads
112       compatibility:
113
114       •   Use the correct typemap
115
116           choose either "O_NON_WXOBJECT_THR" or "O_WXOBJECT_THR".
117
118       •   Implement a "CLONE" method
119
120           add this code inside the class declaration:
121
122               %{
123               static void
124               wxNewClass::CLONE()
125                 CODE:
126                   wxPli_thread_sv_clone( aTHX_ CLASS, (wxPliCloneSV)wxPli_detach_object );
127               %}
128
129       •   Fix the destructor.
130
131           modify the destructor like this:
132
133               ~wxNewClass()
134                   %code%{  wxPli_thread_sv_unregister( aTHX_ "Wx::NewClass", THIS, ST(0) );
135                            delete THIS;
136                            %};
137

VIRTUAL METHODS

139       The wrapping of virtual functions whose arguments are simple C++ types
140       (integrals, bool, floating point) and common wxWidgets types (wxString)
141       should be automatic: at the top of the file, load the plugin that
142       handles virtual methods
143
144           %loadplugin{build::Wx::XSP::Virtual};
145
146       and decorate virtual/pure virtual methods using the %Virtual directive
147
148           // pure virtual
149           virtual wxString GetTitle() const = 0 %Virtual{pure};
150
151           // virtual, not pure
152           virtual int GetBestFittingWidth(unsigned int idx) const %Virtual;
153
154       If the class contains pure virtual methods, it will be marked as
155       abstract, and it will have no constructors.
156
157       For abstract classes, XS++ will create an additional Perl-level class,
158       called "Wx::Pl<classname>"; in order to override the virtual methods,
159       you must derive from this class, and not from "Wx::<classname>".
160
161       TODO allow changing the default behaviour for abstract/concrete classes
162
163       TODO allow overriding the class name
164
165       TODO allow specifying custom code
166
167       TODO handle multiple return values
168
169       TODO customized type mapping
170
171
172
173perl v5.34.0                      2021-07-27                   Wx::NewClass(3)