Difference between revisions of "User:Crond/sandbox"

Revision as of 12:38, 29 May 2011

History

Since the release of CEGUI 0.7.5, official Python bindings have been provided, primarily prompted by the fact that the new CEGUI tools are written in Python. A beneficial side effect of this is that the bindings are free for anyone to use in their Python, or embedded Python, applications.

Downloads

• Windows: PyPi repository
• For other platforms, download the SDK and use the bindings contained within.
• If you use embedded Python, it may be easier to use the Win32 bindings from the SDK.

Documentation

The PyCEGUI API resembles the C++ version as closely as possible - mainly to avoid confusion and to provide familiarity between the two. The doxygen API docs (found here) apply for most of the classes; additionally, doxygen comments are extracted and added as docstrings to all Python objects. This means that using Python docstrings is possible, although not perfect.

Implementation

PyCEGUI uses Py++ and Boost.Python - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than SWIG, and certainly slower than hand written bindings; but, since neither of those will happen, be content with what is provided. The slowness is very unlikely to be noticeable at all unless you do synthetic tests.

User data

C++ CEGUI has accessor methods `[get/set]UserData` in several classes, which are not exposed to Python. The reason for this is because of the mutable nature of most Python objects: that is to say, the majority of Python objects can have attributes defined or deleted on the fly. Consider the following:

someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)

It should be obvious, here, why `[...]UserData` functions from CEGUI are not necessary. In the happenstance that it is not, let us be very clear: any application can define a new attribute (or method, etc) on any mutable Python object, and the same rules apply to PyCEGUI objects, thus rendering "user data" methods superfluous.

Known issues

Persistence

For the folks who are exploring both CEGUI and PyCEGUI, consider that attributes and methods defined in Python do not persist when passed back into C++; that is to say, if an attribute is defined on some arbitrary PyCEGUI object, and that object is passed (indirectly) into C++, there should be no expectation that the aforementioned attribute will exist.

Reference counting

Note: Fixed; pending
C++, like C, gives the programmer a pretty free hand in allocating memory, passing it around, and possibly forgetting that it ever exists; while certainly not the recommended way of doing things, it is possible. Python, however, is a different creature altogether - by default, it has a garbage collection system which is implemented via reference counting (the specifics of this are not important, and left as an exercise to the reader if they are that interested). Basically, what this means, is that when an object is no longer needed, it is deleted.

This can play havoc with a C++ binding, if not considered carefully. For example, if a Python application has an object it wishes to let PyCEGUI (and, by association, C++ CEGUI) know about, it must take care to remember that Python is tracking the number of times the object in question has been referenced, but C++ is not. Thus, the conflict here is that Python will destroy (or garbage collect, if you prefer) the object in question, while C++ will be none the wiser; the inevitable conclusion here is an invalid pointer, segmentation fault, or other equally nasty bug.

Let us illustrate just exactly what we are talking about here; consider the following:

def outsideContext(argListbox):
  item1 = PyCEGUI.ListboxTextItem('item1')
  item2 = PyCEGUI.ListboxTextItem('item2')
  argListbox.addItem(item1)
  argListbox.addItem(item2)
  return
 
def main():
  theListbox = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'theListbox')
  outsideContext(theListbox)
  return
 
if __name__ == '__main__':
  sys.exit(main())

In the function `outsideContext`, two items are created in that scope (and registered with the Python garbage collection system), and then added to a Listbox; when the function is finished, Python is under the impression that it no longer needs the items and so it destroys the objects. Under the hood, however, pointers have been arranged that refer to these two items; in the future, when the Listbox tries to manipulate the items or when the Listbox itself is garbage collected, segmentation faults will more than likely occur.

One solution to this issue, if possible, is to bind the items to an object - preferably, the one which the Listbox is bound to, so that when the Listbox itself is no longer needed, the items will be cleaned up at the same time. Such a strategy might go as follows:

class someObject(object):
  def __init__(self):
    super(Object, self).__init__()
    self.memory = []
    return
  def anInitializationMethod(self):
    self.listbox = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
    return
  def anotherMethod(self, stringList):
    for s in stringList:
      buffer = PyCEGUI.ListboxTextItem(s)
      self.memory.append(buffer)
      self.listbox.addItem(buffer)
    return

The key point here is to have Python keep the object alive until the Listbox in question is no longer needed; the implementation of it is irrelevant.

Dangling pointers

Another issue is almost the opposite of what was outlined previously - that is to say, PyCEGUI objects can be destroyed and Python will still think they are valid (in some sense, they are - just not functional). An example of this is creating a window, storing it in a variable, then destroying the window; a code snippet:

rootWindow = PyCEGUI.WindowManager.getSingleton().createWindow('DefaultWindow', 'root')
PyCEGUI.System.getSingleton().setGUISheet(rootWindow)
 
someWindow = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/FrameWindow', 'someWindow')
rootWindow.addChildWindow(someWindow)
 
# ... things happen ...
 
PyCEGUI.WindowManager.getSingleton().destroyWindow(someWindow)
PyCEGUI.WindowManager.getSingleton().cleanDeadPool()
 
# Death
# - Any functional method will crash the program; the choice of `disable` is totally arbitrary.
someWindow.disable()

This is a contrived example, and most programs will have some form of logic that will prevent this, but it is worth noting.

Panda3D integration

morgul has integrated CEGUI with Panda via these bindings.

Examples

Basic OpenGL

A demonstration of a basic application using PyCEGUI and OpenGL can be found here.

Subscriptions

• A demonstration of subscribing to events in the context of a single class can be found here.
• A demonstration of subscribing to events in the context of multiple classes can be found here.

todo: Subscriptions

One major thing that isn't documented in doxygen or other wiki docs and that is important in python is how subscriptions work.

Subscribing to listenerClass:

wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, "methodInThatClass")

Subscribing to a free function:

wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)

Example

An example of this, using a single class for simplicity, might go as follows.

class SingleClassGUI:
 
    # Initialization things
    # - Create/set the GUISheet.
    def __init__(self):
        self.GUISheet = PyCEGUI.WindowManager.getSingleton().createWindow('DefaultWindow', 'root')
        PyCEGUI.System.getSingleton().setGUISheet(self.GUISheet)
        return
 
    # Setup a window with a button to demonstrate subscriptions
    def setupMenu(self):
        menu = PyCEGUI.WindowManager.getSingleton().loadWindowLayout('menu.layout') # See below for 'menu.layout'
 
        # This defines the widget we are accessing (in this case, the widget with path 'Menu/Button') ...
        # the event we are listening for (in this case, the clicking of a push button) ...
        # and the method we want to call when the aforementioned event takes place.
        #
        # Important note: the second argument to `subscribeEvent` is the class which should be used to find the
        # method, as indicated by the third argument. Because this is a single class example, we just use `self`.
        # If, however, this was a more practical example, a different class would be passed in, which would be
        # investigated for the proper method to call.
        menu.getChild('Menu/Button').subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonClicked')
 
        # Or, it could be written like this, which is more verbose but functionally equivalent
        #button = menu.getChild('Menu/Button')
        #button.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonClicked')
 
        # Don't forget to do this
        self.GUISheet.addChildWindow(menu)
        return
 
    # Handler
    # - `args` is context sensitive; which is to say that its value depends on the type of event. See the EventArgs class for details.
    def buttonClicked(self, args):
        print('buttonClicked')
        return

This is the XML layout file which defines how the window frame will appear. There is no doubt more information than necessary here for the example, but the main points (from a coding point of view) to pay attention to are the properties which define the name of the menu, and the button.

<?xml version="1.0" encoding="UTF-8"?>
 
<GUILayout >
    <Window Type="TaharezLook/FrameWindow" Name="Menu" >
        <Property Name="Font" Value="DejaVuSans-10" />
        <Property Name="Text" Value="An example Menu" />
        <Property Name="TitlebarFont" Value="DejaVuSans-10" />
        <Property Name="RollUpEnabled" Value="False" />
        <Property Name="TitlebarEnabled" Value="True" />
        <Property Name="UnifiedAreaRect" Value="{{0.157031,0},{0.194911,0},{0.783984,0},{0.687913,0}}" />
        <Property Name="DragMovingEnabled" Value="False" />
        <Property Name="CloseButtonEnabled" Value="False" />
        <Property Name="EWSizingCursorImage" Value="set:Vanilla-Images image:MouseArrow" />
        <Property Name="InheritsTooltipText" Value="False" />
        <Property Name="NSSizingCursorImage" Value="set:Vanilla-Images image:MouseArrow" />
        <Property Name="NESWSizingCursorImage" Value="set:Vanilla-Images image:MouseArrow" />
        <Property Name="NWSESizingCursorImage" Value="set:Vanilla-Images image:MouseArrow" />
        <Window Type="TaharezLook/Button" Name="Menu/Button" >
            <Property Name="Text" Value="Button" />
            <Property Name="UnifiedAreaRect" Value="{{0.78567,0},{0.620646,0},{0.979596,0},{0.749355,0}}" />
        </Window>
    </Window>
</GUILayout>

The fourth line defines the type of window, and the name of it - this is the name used to access it (and its children) from Python.

Farther down (the next <Window></Window> block) is the line where the button is defined; first there is the type of button, and then the name of it - in this case, 'Menu/Button'; note that this is the name (or path, if you prefer) we use to access it from Python (see the SingleClassGUI.setupMenu method above).

On a final note, this example assumes that some renderer has been setup - via OpenGL, Ogre, etc. Out of the box, this example will not work, because [Py]CEGUI has no renderer setup; once a system has been bootstrapped, this example will display a frame with a button, which when clicked, will print 'buttonClicked' to the console.

Something akin to the following:

# Renderer setup goes here
pass
 
# Make it so.
gui = SingleClassGUI()
gui.setupMenu()
 
# Enter rendering loop goes here

Multi-class example

See here.