CEGUI Wiki - Crazy Eddie's GUI System (Open Source) - User contributions [en]

Python3 SWIG interface

2019-08-30T22:22:01Z

Rrp: add category

{{VersionBadge|1.0}}

Default branch of CEGUI provide Python3 binding with [http://www.swig.org/ SWIG]. Currently SWIG interface covers a large part of libCEGUIBase, but don't cover any renderer module.

= About SWIG =

SWIG is wrappers generators, it can generate Python and other APIs without the need writing a lot of wrapper code.

== How it works ==

SWIG parse <code>.i</code> file and generate C++ file, that (in Python case) directly uses libpython (so no depends on boost, pybind or similar). C++ file is build into Python <code>.so</code> lib. SWIG generate also small <code>.py</code> file to support import this lib. Cmake run SWIG on <code>.i</code> and <code>$CXX</code> on generated wrapper code (in Ogre case is very big file, so <code>$CXX</code> need some time to build it).

SWIG automatically generate wrapper from <code>.i</code> file(s) and <code>%include</code> C++ <code>.h</code> files. SWIG <code>.i</code> file is set of <code>%</code> directive, such as:
* <code>%include "file.h"</code> – add interface from file.h to generated API
* <code>%{ ... %}</code> to add some C++ stuff (e.g. <code>#include</code> directive with header needed to build whole generated <code>.cpp</code> file)
* <code>%extend</code>, <code>%proxycode</code>, <code>%ignore</code> to adjust generated API

<code>.h</code> files for classes that should be exposed in generated API must be directly <code>%include in <code>.i</code> file (SWIG do not use <code>#include</code> in <code>%include</code> files as <code>%include</code>). Order of <code>%include</code> is important – first <code>%include</code> base classes, otherwise SWIG generate warning about missing base class and in generated API is missing info about class hierarchy (can't put derived class object to function that get base class object, can't call base class method on derived class object).

= Build CEGUI Python3 binding =

To build CEGUI Python SWIG interface you should enable CEGUI_BUILD_PYTHON_MODULES_SWIG cmake option:

<code>mkdir build; cd build; cmake .. -D CEGUI_BUILD_PYTHON_MODULES_SWIG=ON && make</code>

This require libpython3 and swig.

= Usage CEGUI Python3 binding =

Primary intention of this binding is allow use (and create) CEGUI object from Python scripts system in game engines.

== Using with boost::python ==

SWIG generated API can be used with code that use boost::python to expose own interface. For example, if some project use CEGUI and have python API created with boost, it can return some CEGUI object via boost and this object can be used in python with CEGUI SWIG interface (this need only small piece of code to “cast” object between boost and SWIG):

<source lang="cpp">
#include "swig2BoostPython.inl"

#include <CEGUI/Window.h>

PREPARE_EXPOSE_PTR_VIA_SWIG(CEGUI::Window, "CEGUI::Window *");

CEGUI::Window * getRootWindow();

BOOST_PYTHON_MODULE(MyPyAPI) {
EXPOSE_PTR_VIA_SWIG(CEGUI::Window);
boost::python::def(
"getRootWindow", &getRootWindow,
boost::python::return_value_policy<reference_existing_object_via_SWIG>()
);
}
</source>

<code>swig2BoostPython.inl</code> is small, header only, MIT license lib for connect boost and swig interfaces available on [https://bitbucket.org/OpCode-eu-org/python-swig-boost bitbucket git repo].

== Down-cast CEGUI::Window and subscribeEvent() ==

SWIG Python interface provide down-casting function for CEGUI::Window class. For example to get CEGUI::FrameWindow form CEGUI::Window you should use CEGUI.toFrameWindow(win).

In SWIG Python interface to subscribeEvent() function should be pass objects of python class with realize event action. This class must have run method witch get event argument and return bool value.This object can't be delete before run events.

=== example of creating window from python (with close button event) ===

<source lang="python">
import CEGUI
import MyPyAPI

mywin = CEGUI.WindowManager.getSingleton().loadLayoutFromFile("Info.layout")
class Callback(CEGUI.PySubscriber):
def run(self, n):
mywin.hide()
return True; # must return bool
handleHideInfoWin = Callback() # can't be temporary object !!!
CEGUI.toFrameWindow(mywin).getCloseButton().subscribeEvent( CEGUI.PushButton.EventClicked.c_str(), handleHideInfoWin )

MyPyAPI.getRootWindow().addChild(mywin)
</source>

[[Category:HowTo]]

Python3 SWIG interface

2019-08-30T22:21:18Z

Rrp: initial version