Information about extending or debugging the library
Contributing to the library
I welcome and encourage others to extend the library, improving the wrappers that
I've already written and wrapping new classes. If you take a look at the wxWidgets
documentation, you'll see that there are a LOT of classes, and pretty much all of them
are available to wxEuphoria, once the proper wrapper is generated.
If you do want to contribute something, please send the source to me. Also, please
document your wrappers using the same format as the rest of the library, so that it
can be easily included in the wxEuphoria documentation, which is automatically
generated from the source files.
Wrapping additional functions is usually pretty easy. Take a look at both wxeud.e and
the *.cpp source files for some examples. Most of the wxEuphoria C++ source code is
made up of one-liners that call the appropriate wxWidgets routine. Here are a few tips:
- Declare any pointers to wxWidgets objects as 'int's in the C++ code. To use these as
the appropriate C++ object, you usually just have to do a simple cast:
- Make sure that you put WXEUAPI in front of the routine definition (look at the code
- If you wrap a new object, the constructor should be wrapped in a function with a name
of the form "new_wxNewClassName".
- If you're returning a pointer (or any integer that could be bigger than a Euphoria integer)
be sure to use the BOX_INT() macro when returning the value. It will convert the value
to a Euphoria atom if necessary.
- Use the helper functions in wxeu.cpp:
- get_int( seq, index ): Basic subscript operation ( seq[index] ), and returns
the value as a C++ int. It's used for extracting values from a sequence that's passed to
a C++ routine from Euphoria, and handles any conversion from an atom.
- get_int( x ): Converts a Euphoria atom to a C++ int.
- get_string( seq ): Converts a sequence to a wxString.
- get_string( seq, index): Converts a subscript of a sequence to a wxString.
- get_sequence( string ): Converts a wxString into a Euphoria sequence
- Literal strings in your C++ code should be surrounded with the wxT() macro, which
is used by wxWidgets to assist with Unicode portability.
- Declare any Euphoria objects (i.e., when the wx_define_c_* uses dll:E_OBJECT, dll:E_SEQUENCE, dll:E_ATOM)
passed to C++ as "object" in the C++ code.
- Make sure you dereference the Euphoria objects that are passed to C++ code using the
wxEuphoria macros defined in wxeu.h. Not doing so will cause memory leaks, since their
reference counts will never go to zero.
- wxDeRef( obj ): Checks to see if the object is a sequence or an atom stored as a double,
and dereferences it if either condition is true.
- wxDeRefDS( obj ): Dereferences the object. Use this only if you know that a variable
is either a double or a sequence.
- Use the wrap.exw utility to update wxeud.e. It will generate a file named wxeud2.e with
your additions. It adds the wx_define_c_* statements, updates the create constants if you
added any new objects, adds the euphoria wrappers and some simple documentation. The documentation
will all be attributed to "topic Auto". You'll need to replace the "Auto" with whatever the
correct topic should be.
To build on windows, the wat_mswdll\exports.lbc file needs to be updated. If you have
grep and sed installed (possibly through Cygwin, or GnuWin32),
then you can use the OpenWatcom makefile to regenerate this file using the command:
"wmake -f makefile.wat exports". Otherwise, just add lines at the bottom of exports.lbc to
make sure that your new routines are exported.
- Use the export.exw utility to update wat_mswdll\exports.lbc file. It will build the list
based on the same method used in wrap.exw.
- Use the wxmake.bat utility (wxmake on Linux) to automatically build wxEuphoria. It will run
exports.exw, Watcom MAKE, and wrap.exw, then (assuming wxEuphoria built correctly) install the
new wxEuphoria binaries on your system.
Extending wxWidgets with other C++ libararies
The library can be extended by building additional shared libraries to wrap other features
or other contributions by the wxWidgets community (such as the wxSTC text editor widget).
You'll probably want to take a look at how the library is put together, using be.c, wxeu.h
and wxeu.cpp. These files provide some useful routines for dealing with euphoria and
wxWidgets C++ data, such as converting sequences to wxStrings.
You'll need to call add_create_func() to integrate your wrapper with the wxEuphoria library.
This function can be used to extend the library by adding a constructor that can
be used in euphoria code. The only parameter em rid, is the result of a call
to define_c_func or routine_id. (If passing a routine_id, it must be enclosed as a
sequence.) The function should take a sequence as a parameter, and should return an
atom containing a pointer to the created object.