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 HOWTO

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:

  ((wxObject*)the_object)->SomeRoutine();
  

• Make sure that you put WXEUAPI in front of the routine definition (look at the code for examples).
• 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.