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

User:Crond

2011-07-11T00:51:20Z

Crond: /* Places */

== Todo ==
* Finish the PyCEGUI page
** Application
* Add Python code examples for 'In Practice' series.
* Find the Triforce - except there is no try. (Two references in one sentence - put that in your pipe and smoke it).

== Places ==
[[User:Crond/sandbox|Sandbox]] 
Inspiration to continue [http://www.youtube.com/watch?v=y-I7gjPNJbE the application].

User:Crond

2011-07-10T21:36:20Z

Crond: /* Todo */ beers

User:Crond

2011-07-10T15:23:38Z

Crond: /* Todo */

== Todo ==
* Finish the PyCEGUI page
** Application
* Add Python code examples for 'In Practice' series.

== Places ==
[[User:Crond/sandbox|Sandbox]]

User:Crond/sandbox

2011-07-10T15:22:48Z

Crond: /* OpenGL driver bugs */ someone elses problem

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

=== Future release (0.8+) ===
'''TODO: Resolve repetition.''' 
In the future, the signatures have been changed to be much more flexible and Pythonic. 'subscribeEvent' now takes any callable object (bound member function, free function, lambda, functor, etc). Moving from the old syntax to the new syntax, the following

<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, instance, "someMethod")
</source>

becomes this

<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, instance.someMethod)
</source>

== Known issues ==
=== Reference counting ===
'''Note: Fixed; pending release (0.8+)''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL driver bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset, which are outside the scope of [Py]CEGUI to deal with.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* See [[User:Crond/sandbox/application1|here]].

User:Crond/sandbox

2011-07-10T15:20:11Z

Crond: rm more user data; update

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

=== Future release (0.8+) ===
'''TODO: Resolve repetition.''' 
In the future, the signatures have been changed to be much more flexible and Pythonic. 'subscribeEvent' now takes any callable object (bound member function, free function, lambda, functor, etc). Moving from the old syntax to the new syntax, the following

<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, instance, "someMethod")
</source>

becomes this

<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, instance.someMethod)
</source>

== Known issues ==
=== Reference counting ===
'''Note: Fixed; pending release (0.8+)''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL driver bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* See [[User:Crond/sandbox/application1|here]].

User:Crond/sandbox

2011-07-10T15:13:03Z

Crond: /* Known issues */ rm user data

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Reference counting ===
'''Note: Fixed; pending release''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL driver bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* See [[User:Crond/sandbox/application1|here]].

Build PyCEGUI from source for Windows

2011-07-10T15:10:51Z

Crond: /* Windows 7 (x64) */ ce

{{VersionBadge|0.7}}
 

== Windows 7 (x64) ==
The main documentation (found [http://www.cegui.org.uk/docs/current/compiling.html here]) does a good job of explaining the process. However, a caveat with x64 is that consistency needs to be maintained across several software packages. In the context of CEGUI, this is particularly relevant in regards to Python and Boost; which is to say that if you are trying to build the PyCEGUI project from the generated solution, and are getting a lot of unresolved linker errors, you are probably trying to link against a 64bit installation of Python.

The solution, as might be expected, is to uninstall the existing 64bit version of Python, and to install a 32bit variant.

=== Who this affects ===
An assumption is that this is only a problem for people who installed precompiled versions of boost as provided by [http://boostpro.com/download/ these fine people]; if you compiled the boost libraries yourself, this may not be an issue.

[[Category:HowTo]]

Build PyCEGUI from source for Windows

2011-07-10T12:06:42Z

Crond: created; mainly, to document the architecture mismatch

{{VersionBadge|0.7}}
 

== Windows 7 (x64) ==
The main documentation (found [http://www.cegui.org.uk/docs/current/compiling.html here]) does a good job of explaining the process. However, a caveat with x64 is that consistency needs to be maintained across several software packages. In the context of CEGUI, this is particularly relevant in regards to Python and Boost; which is to say that if you are trying to build the PyCEGUI project from the generated solution, and are getting a lot of unresolved linker errors, you are probably trying to link against a 64bit installation of Python.

The solution, as might be expected, is to uninstall the existing 64bit version of Python, and reinstall a 32bit variant.

=== Who this affects ===
An assumption is that this is only a problem for people who installed precompiled versions of boost as provided by [http://boostpro.com/download/ these fine people]; if you compiled the boost libraries yourself, this may not be an issue.

[[Category:HowTo]]

Talk:Build PyCEGUI from source for Linux

2011-07-10T11:30:18Z

Crond: sign; header

== Thoughts ==
A good topic, one close to my heart.

I am curious, though; in this snippet:

<code>
sudo rmdir /usr/local/lib/python2.6/site-packages
sudo ln -s /usr/local/lib/python2.6/dist-packages/ /usr/local/lib/python2.6/site-packages
</code>

* If 'site-packages' is not empty, that command will fail; an 'rm -r' would be necessary, but in that case it means the directory might have valuable contents.
* Which leads to my next question: is deleting that directory a good idea? Could it cause future problems with some other arbitrary piece of software?
- [[User:Crond|Crond]] 11:30, 10 July 2011 (UTC)

Talk:Build PyCEGUI from source for Linux

2011-07-10T11:29:24Z

Crond: blather

A good topic, one close to my heart.

I am curious, though; in this snippet:

<code>
sudo rmdir /usr/local/lib/python2.6/site-packages
sudo ln -s /usr/local/lib/python2.6/dist-packages/ /usr/local/lib/python2.6/site-packages
</code>

* If 'site-packages' is not empty, that command will fail; an 'rm -r' would be necessary, but in that case it means the directory might have valuable contents.
* Which leads to my next question: is deleting that directory a good idea? Could it cause future problems with some other arbitrary piece of software?

Build PyCEGUI from source for Linux

2011-07-10T11:26:09Z

Crond: made python version the same across code snippets

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.4}}
= Ubuntu 11.04 =
Version shipped in repositories is 0.6.0 (as of 7th July 2011) so if we want 0.7.x we need to build it from source.

* Install dependency packages: <code>sudo apt-get install build-essential pkg-config python-dev libfreetype6-dev libpcre3-dev libboost-python-dev libglut3-dev libpng-dev libmng-dev libjpeg-dev libfreeimage-dev</code>
* Obtain a copy of CEGUI [http://prdownloads.sourceforge.net/crayzedsgui/CEGUI-0.7.5.tar.gz?download here]
* Extract to a folder
* Before we build, we have to symlink the site-packages directory correctly, so it installs to the correct place.
sudo rmdir /usr/local/lib/python2.6/site-packages
sudo ln -s /usr/local/lib/python2.6/dist-packages/ /usr/local/lib/python2.6/site-packages
* Build CEGUI with python support
./configure && make && sudo make install && sudo ldconfig
* ''Note: On some Ubuntu systems it seems that CEGUI's configure system does not correctly detect the Python headers. To solve this, do the following:''
export CXXFLAGS=-I/usr/include/python2.6
./configure && make && sudo make install && sudo ldconfig

= Still not working? =
You can try running your program with:
PYTHONPATH="/usr/local/lib/python2.6/site-packages:$PYTHONPATH" python <file.py>

'''Note for Panda3D users'''
You can run your program at the same way, using:
PYTHONPATH="/usr/local/lib/python2.6/site-packages:$PYTHONPATH" ppython <file.py>

[[Category:HowTo]]

User:Crond

2011-06-22T07:25:41Z

Crond: /* Todo */

== Todo ==
* Finish the PyCEGUI page
** Test the UserData hypothesis.
* Add Python code examples for 'In Practice' series.
* Some new demos/examples?
* Application

== Places ==
[[User:Crond/sandbox|Sandbox]]

User:Crond/sandbox/application1

2011-06-21T16:51:40Z

Crond: preliminary outline

User:Crond/sandbox/application1

2011-06-20T16:02:42Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
{{Series|PyCEGUI: BeerTracker|1}}
 

== Introduction ==
This is the first in a series of articles, designed to build an application from the ground up - that is to say, the planning, construction, and utilization of the application are all documented.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== What is the application? ==
I gave this a good amount of thought, then I realized that I am sitting here, thinking, while drinking beer. Thus, the wonderful idea of writing an application to track the amount of beer I drank, as well as my thoughts on each individual beer, formed; not only will it do these wonderful things, it will be persistent - the application will remember whatever it is told. Finally, it will have a history feature: which is to say, a user can go back to a specific date and read about how they felt about the beer they drank that day - you know, in case they don't remember.

== Why this application? ==
I'm pretty sure this is self-explanatory.

== Series ==
* n
* n+1
* ...

== TODO ==
* Create initial application; then post it.
* Create category for series '''only after''' the initial application is done.
* ETA of initial application: 6/24+

User:Crond/sandbox/openglEventExample2

2011-06-20T16:01:08Z

Crond: /* Source */ use getText method

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a slightly refined example of using subscriptions to respond to events. The example will generate some text on the console when an Editbox receives input, and when Enter/Return is pressed while the Editbox has focus.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglEventExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutDestroyWindow(glutCreateWindow(''))
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
self.editboxText = self.windowNewNode.getChild('Demo/NewNode/Editbox')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextChanged, self, 'handlerTextChanged')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextAccepted, self, 'handlerTextAccepted')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Handler: Text changed
def handlerTextChanged(self, args):
print('Text has changed.')
return

# Handler: Text accepted
def handlerTextAccepted(self, args):
print('Text [{0}]has been accepted.'.format(self.editboxText.getText()))
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Enter some text into the Editbox, and/or press Return while the Editbox has focus.

== Examination ==
In the context of the previous examples, this is all pretty straightforward; this simply demonstrates some additional events which are relevant to an Editbox.

As an exercise for the reader, consider the implications of removing the mapping of the return key from `KEYMAP_ASCII`, and why the effects are what they are.

User:Crond/sandbox/openglEventExample2

2011-06-20T15:55:25Z

Crond: /* Notes */ fix link

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a slightly refined example of using subscriptions to respond to events. The example will generate some text on the console when an Editbox receives input, and when Enter/Return is pressed while the Editbox has focus.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglEventExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutDestroyWindow(glutCreateWindow(''))
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
self.editboxText = self.windowNewNode.getChild('Demo/NewNode/Editbox')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextChanged, self, 'handlerTextChanged')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextAccepted, self, 'handlerTextAccepted')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Handler: Text changed
def handlerTextChanged(self, args):
print('Text has changed.')
return

# Handler: Text accepted
def handlerTextAccepted(self, args):
print('Text has been accepted.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Enter some text into the Editbox, and/or press Return while the Editbox has focus.

== Examination ==
In the context of the previous examples, this is all pretty straightforward; this simply demonstrates some additional events which are relevant to an Editbox.

As an exercise for the reader, consider the implications of removing the mapping of the return key from `KEYMAP_ASCII`, and why the effects are what they are.

User:Crond/sandbox/openglEventExample

2011-06-20T15:54:36Z

Crond: /* Notes */ change link

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the latter two arguments; in their place, a function/method object is sufficient.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox/openglEventExample2

2011-06-20T15:52:08Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a slightly refined example of using subscriptions to respond to events. The example will generate some text on the console when an Editbox receives input, and when Enter/Return is pressed while the Editbox has focus.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/opengEventExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutDestroyWindow(glutCreateWindow(''))
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
self.editboxText = self.windowNewNode.getChild('Demo/NewNode/Editbox')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextChanged, self, 'handlerTextChanged')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextAccepted, self, 'handlerTextAccepted')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Handler: Text changed
def handlerTextChanged(self, args):
print('Text has changed.')
return

# Handler: Text accepted
def handlerTextAccepted(self, args):
print('Text has been accepted.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Enter some text into the Editbox, and/or press Return while the Editbox has focus.

== Examination ==
In the context of the previous examples, this is all pretty straightforward; this simply demonstrates some additional events which are relevant to an Editbox.

As an exercise for the reader, consider the implications of removing the mapping of the return key from `KEYMAP_ASCII`, and why the effects are what they are.

User:Crond/sandbox/openglEventExample

2011-06-20T15:51:43Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the latter two arguments; in their place, a function/method object is sufficient.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox/openglSpecialKeyboardExample

2011-06-20T15:51:19Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic keyboard processing OpenGL application, as found [[User:Crond/sandbox/openglKeyboardExample|here]]. The goal is to present a further refinement of keyboard processing, specifically the handling of "special" keys, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
As before, we can see that this works by running the application, typing into the Editbox, and pressing the arrow keys, or any of the other keys.

Several keys, such as Escape and Return, are not readily testable (i.e. produce no discernible effects on the application), although they do work. It is left as an exercise to the reader to prove it.

== Examination ==
=== GLUT, ASCII, PyCEGUI ===
It can be a little tricky, at times, to separate them all. A good rule of thumb is that using the `ord` function on any input received via GLUT will produce the ASCII value, which can then be handled in whatever way the application desires - e.g. mapping it to a PyCEGUI value.

An additional note is that what GLUT considers to be a "special" key is not exactly what PyCEGUI (or any other library, for that matter) considers to be special. For this reason, the `KEYMAP_ASCII` exists and helps define additional keys that are special, whatever that may mean in a particular context.

User:Crond/sandbox/openglKeyboardExample

2011-06-20T15:50:58Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [[User:Crond/sandbox/openglExample|here]]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
self.sys.injectChar(ord(key))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())

</source>

== Demonstration ==
We can see that this works by running the application, and typing into the Editbox, as provided by the 'New Node' frame window.

== Examination ==
=== 'ord' function ===
The 'ord' function is a built-in Python function, which converts a single character (or a string of length one, if you prefer) to its Unicode/ASCII value; for further details, see the Python documentation [http://docs.python.org/release/2.6.5/library/functions.html#ord here].

User:Crond/sandbox/openglExample

2011-06-20T15:50:27Z

Crond: /* Requirements */ superfluous

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a minimal PyCEGUI application, using OpenGL as the renderer. The goal is to familiarize the reader with the basics of how to get PyCEGUI up and running, and to provide a few pointers along the way.

== Requirements ==
* Python 2.6
* PyCEGUI
* PyOpenGL

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

User:Crond/sandbox/openglEventExample

2011-06-20T07:50:25Z

Crond: /* Layout to Python */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the latter two arguments; in their place, a function/method object is sufficient.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox/openglEventExample

2011-06-20T07:50:02Z

Crond: /* Layout to Python */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the latter two arguments; rather, a function/method object.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox

2011-06-18T22:03:22Z

Crond: /* OpenGL bugs */ specificity

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Persistence ===
'''Todo: Is this true? And if it's not, why did I think it was?''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL driver bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* See [[User:Crond/sandbox/application1|here]].

User:Crond/sandbox/application1

2011-06-18T22:01:32Z

Crond: initial placeholder

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
{{Series|PyCEGUI: BeerTracker|1}}
 

== Introduction ==
This is the first in a series of articles, designed to build an application from the ground up - that is to say, the planning, construction, and utilization of the application are all documented.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== What is the application? ==
I gave this a good amount of thought, then I realized that I am sitting here, thinking, while drinking beer. Thus, the wonderful idea of writing an application to track the amount of beer I drank, as well as my thoughts on each individual beer, formed; not only will it do these wonderful things, it will be persistent - the application will remember whatever it is told. Finally, it will have a history feature: which is to say, a user can go back to a specific date and read about how they felt about the beer they drank that day - you know, in case they don't remember.

== Why this application? ==
I'm pretty sure this is self-explanatory.

== Series ==
* n
* n+1
* ...

== TODO ==
* Create initial application; then post it.
* Create category for series '''only after''' the initial application is done.
* ETA of initial application: 6/24+

User:Crond/sandbox

2011-06-18T21:49:17Z

Crond: /* Application from scratch */ placeholder

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Persistence ===
'''Todo: Is this true? And if it's not, why did I think it was?''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* See [[User:Crond/sandbox/application1|here]].

User:Crond/sandbox

2011-06-18T21:37:32Z

Crond: /* Examples */ to be done

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Persistence ===
'''Todo: Is this true? And if it's not, why did I think it was?''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== Application from scratch ===
* n
* n+1
* ...

PyCEGUI/Example

2011-06-18T21:35:55Z

Crond: oops

== Introduction ==
This is an example which creates a light, non-comprehensive framework for PyCEGUI, with the rendering system used being [Py]OpenGL. The reason OpenGL is used is because it's free, easy to get on any Ubuntu system (which this was written on), and portable. Also, it's the one demonstrated on the official [[PyCEGUI]] page.

== Links of interest ==
*[http://docs.python.org/release/2.6.5/ Python 2.6.5 documentation]
*[http://pyopengl.sourceforge.net/documentation/manual-3.0/index.xhtml PyOpenGL reference]
*[http://pyopengl.sourceforge.net/documentation/manual-3.0/index.xhtml#GLUT PyOpenGL GLUT reference]

== Requirements ==
=== General ===
*Python 2.6
*PyCEGUI
*PyOpenGL, GLU, GLUT
=== Datafiles ===
This example assumes the CEGUI datafiles are in the same directory as `demo.py`; see the following section.
=== Directory hierarchy ===
*/home/foo/bar/demo
**demo.py
**datafiles/
***datafiles/layouts/demomenu.layout
**config/
***constants.py
**error/
***errors.py
**input/
***input.py
**video/
***video.py
**gui/
***gui.py
***demomenu.py

== General notes ==
This is not intended to be fully comprehensive; rather, the intention is to illustrate '''one way''' of setting up a GUI system. A minimal amount of thought was given to "problems down the road;" which is to say that there is no guarantee that a particular design constraint will not render the framework unsuitable for a particular purpose.

In short: your mileage may vary.

== Comments, improvements, etc ==
Use the discussion page.

== Source ==
=== constants.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# constants.py

"""Constant values.

Values currently contained in this file include:

Version information
Window name(s)

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Versioning
MINOR_VERSION = '01'
MAJOR_VERSION = '0'
FULL_VERSION = '.'.join([MAJOR_VERSION, MINOR_VERSION])

# Name: Root window
NAME_ROOT_WINDOW = 'Demo: %s' % FULL_VERSION
</source>

=== errors.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# errors.py

"""Errors.

Currently defined errors include:

InitializationError

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# InitializationError
class InitializationError(Exception):
def __init__(self, msg):
self.msg = msg
def __str__(self):
return ('InitializationError: %s' % self.msg)
</source>

=== video.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# video.py

"""Video functionality.

This class brings together PyCEGUI and OpenGL into a comfortable interface.

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Import: OpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Import: User
from constants import *
from errors import InitializationError

# Video
class Video(object):

# Initialize: OpenGL
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1)
glutCreateWindow(NAME_ROOT_WINDOW)
glutSetCursor(GLUT_CURSOR_NONE)

# Handlers
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerReshape)
return

# Initialize: PyCEGUI
def initializePyCEGUI(self):
self.renderer = Renderer.bootstrapSystem()
return

# Initialize
def Initialize(self):
try:
self.initializeOpenGL()
self.initializePyCEGUI()
except Exception, msg:
raise InitializationError(msg)
return

# Shutdown
# - For implicit use, use the Python special method `__del__`.
def Shutdown(self):
self.renderer.destroySystem()
return

# Handler: Display
# - This is called to refresh the screen.
# - See PyOpenGL documentation.
def handlerDisplay(self):
thisTime = glutGet(GLUT_ELAPSED_TIME)
elapsed = (thisTime - self.lastFrameTime) / 1000.0
self.lastFrameTime = thisTime
self.updateFPS = self.updateFPS - elapsed
PyCEGUI.System.getSingleton().injectTimePulse(elapsed)

# Render this frame
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
PyCEGUI.System.getSingleton().renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Reshape
# - This is called when the window is resized and/or switches to fullscreen.
# - See PyOpenGL documentation.
def handlerReshape(self, width, height):
glViewport(0, 0, width, height)
glMatrixMode(GL_PROJECTION)
glLoadIdentity()
gluPerspective(60.0, width / height, 1.0, 50.0)
glMatrixMode(GL_MODELVIEW)
PyCEGUI.System.getSingleton().notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Main loop
# - Set the initial values.
# - This never returns; once this gets called, the application is driven entirely by events.
def EnterMainLoop(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
self.updateFPS = 0
glutMainLoop()
return
</source>

=== input.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# input.py

"""Input functionality.

This class sets up input processing by creating handlers for GLUT that inject
input into PyCEGUI.

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Import: OpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI

# Import: User
from constants import *
from errors import InitializationError

# Input
class Input(object):

# Initialize: Handlers
def initializeHandlers(self):
glutKeyboardFunc(self.handlerKeyDown)
glutMouseFunc(self.handlerMouseButton)

# The difference between these two is that the passive one is called when there is
# mouse motion while no buttons are pressed, and the other is called when there
# is mouse motion while buttons are pressed. See PyOpenGL documentation.
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize
def Initialize(self):
try:
self.initializeHandlers()
except Exception, msg:
raise InitializationError(msg)
return

# Handler: Key Down
# - `ord` is a built-in Python function.
def handlerKeyDown(self, key, x, y):
PyCEGUI.System.getSingleton().injectChar(ord(key))
return

# Handler: Mouse Button
def handlerMouseButton(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
PyCEGUI.System.getSingleton().injectMouseButtonUp(PyCEGUI.LeftButton)
else:
PyCEGUI.System.getSingleton().injectMouseButtonDown(PyCEGUI.LeftButton)

# A thought is to turn this into an `else` clause; however, this implies that any
# button besides the left is interpreted as the right button - this seems undesirable
# for any mouse with more than two buttons.
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
PyCEGUI.System.getSingleton().injectMouseButtonUp(PyCEGUI.RightButton)
else:
PyCEGUI.System.getSingleton().injectMouseButtonDown(PyCEGUI.RightButton)

# An `else` clause could also go here to perform some arbitrary action on unhandled
# mouse input; this is left as an exercise for the reader. Instead, we just implicitly
# ignore it.
return

# Handler: Mouse Motion
# - This might seem arbitrary, but in fact this is required or else the position of the mouse
# will never be updated inside the window.
def handlerMouseMotion(self, x, y):
PyCEGUI.System.getSingleton().injectMousePosition(x, y)
return
</source>

=== gui.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# gui.py

"""GUI.

This class is the entry point for the GUI; which is to say that it starts the
main menu and the rest is event driven.

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Import: PyCEGUI
import PyCEGUI

# Import: User
from errors import InitializationError
import demomenu

# GUI
class GUI(object):

# Initialize: Resources
def initializeResources(self):
rp = PyCEGUI.System.getSingleton().getResourceProvider()
rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = PyCEGUI.System.getSingleton().getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: Defaults
def initializeDefaults(self):
sm = PyCEGUI.SchemeManager.getSingleton()
sm.create('VanillaSkin.scheme')
sm.create('TaharezLook.scheme')
PyCEGUI.System.getSingleton().setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')
return

# Initialize
def Initialize(self):
try:
self.initializeResources()
self.initializeDefaults()

# GUISheet
self.GUISheet = PyCEGUI.WindowManager.getSingleton().createWindow('DefaultWindow', 'Root')
PyCEGUI.System.getSingleton().setGUISheet(self.GUISheet)
except Exception, msg:
raise InitializationError(msg)
return

# Setup
# - Important: the instance of `demomenu.DemoMenu` has to be bound to this object; if it is
# a local variable (read: destroyed when it goes out of scope), exceptions will be raised
# about the `buttonClicked` method not existing. This is a drawback of the type of setup
# this example uses, and as a consequence of Python being a garbage collected language.
def Setup(self):
self.demoMenu = demomenu.DemoMenu()
self.demoMenu.Initialize()
self.demoMenu.Setup()
return

# Setup: Interface
def setupInterface(self):
self.Setup()
return
</source>

=== demomenu.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# demomenu.py

"""DemoMenu.

This class represents a demonstration of how to control a menu with PyCEGUI and PyOpenGL.

"""

# Import: std
import sys

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Import: PyCEGUI
import PyCEGUI

# Import: User
from errors import InitializationError

# DemoMenu
class DemoMenu(object):

# Initialize
def Initialize(self):
self.GUISheet = PyCEGUI.System.getSingleton().getGUISheet()

# Load the layout
self.menu = PyCEGUI.WindowManager.getSingleton().loadWindowLayout('DemoMenu.layout')
return

# connectHandlers
# - Wrapper method to define the subscription/listener relationships.
# - If there are a lot, it may behoove the coder to encapsulate them in methods, then call those methods here.
def connectHandlers(self):
self.menu.getChild('DemoMenu/Button').subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonClicked')
return

# Setup
def Setup(self):

# Connect the handlers
self.connectHandlers()

# Attach
self.GUISheet.addChildWindow(self.menu)
return

# Handler: buttonClicked
def buttonClicked(self, args):
print('buttonClicked')
return
</source>

=== demo.py ===
<source lang="python">
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# demo.py

"""Demo entry point.

A demonstration; mildly comprehensive, but not really.

"""

# Import: std
import sys, os.path
sys.path.append(os.path.join(os.getcwd(), 'config'))
sys.path.append(os.path.join(os.getcwd(), 'error'))
sys.path.append(os.path.join(os.getcwd(), 'input'))
sys.path.append(os.path.join(os.getcwd(), 'video'))
sys.path.append(os.path.join(os.getcwd(), 'gui'))

# Import: psyco
try:
import psyco
psyco.full()
except ImportError:
pass

# Import: User
from errors import InitializationError
from input import Input
from video import Video
from gui import GUI

# Main
def main():
gfx = Video()
inp = Input()
gui = GUI()

# Initialize
try:
gfx.Initialize()
inp.Initialize()
gui.Initialize()
except InitializationError as error:
print(error)
return 1

# Setup the interface
gui.setupInterface()

# Main Loop
gfx.EnterMainLoop()

# Done
# - We will never actually get here.
gfx.Shutdown()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

=== demomenu.layout ===
<source lang="xml">
<?xml version="1.0" encoding="UTF-8"?>

<GUILayout >
<Window Type="TaharezLook/FrameWindow" Name="DemoMenu" >
<Property Name="Font" Value="DejaVuSans-10" />
<Property Name="Text" Value="Demo 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/StaticText" Name="DemoMenu/Text" >
<Property Name="Text" Value="Enter some text" />
<Property Name="UnifiedAreaRect" Value="{{0.0212363,0},{0.619781,0},{0.346946,0},{0.751932,0}}" />
</Window>
<Window Type="TaharezLook/Editbox" Name="DemoMenu/Edit" >
<Property Name="MaxTextLength" Value="1073741823" />
<Property Name="UnifiedAreaRect" Value="{{0.36704,0},{0.623671,0},{0.769671,0},{0.750419,0}}" />
<Property Name="TextParsingEnabled" Value="False" />
</Window>
<Window Type="TaharezLook/Button" Name="DemoMenu/Button" >
<Property Name="Text" Value="Click me" />
<Property Name="UnifiedAreaRect" Value="{{0.78567,0},{0.620646,0},{0.979596,0},{0.749355,0}}" />
</Window>
</Window>
</GUILayout>
</source>

== Modifications ==
=== demomenu.py ===
To further demonstrate usage of how to manipulate the widgets and branch the script/code divide, consider the following modification to the `demomenu.DemoMenu.buttonClicked` method:

<source lang="python">
def buttonClicked(self, args):
editbox = self.menu.getChild('DemoMenu/Edit')
print(editbox.getText())
return
</source>

Now, when the button is clicked, it will print to the console whatever has been typed in the box.

As an exercise to the reader, consider adding support for Backspace/Delete/Arrow keys (hint: Special) keys.

PyCEGUI/Example

2011-06-18T21:35:30Z

Crond: Delete me.

Delete me.

User:Crond/sandbox/openglEventExample2

2011-06-18T21:34:12Z

Crond: Created page with "{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}} == Introduction == This presents a slightly refined example of using subscriptions to respond to events. T..."

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a slightly refined example of using subscriptions to respond to events. The example will generate some text on the console when an Editbox receives input, and when Enter/Return is pressed while the Editbox has focus.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/opengEventExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutDestroyWindow(glutCreateWindow(''))
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
self.editboxText = self.windowNewNode.getChild('Demo/NewNode/Editbox')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextChanged, self, 'handlerTextChanged')
self.editboxText.subscribeEvent(PyCEGUI.Editbox.EventTextAccepted, self, 'handlerTextAccepted')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Handler: Text changed
def handlerTextChanged(self, args):
print('Text has changed.')
return

# Handler: Text accepted
def handlerTextAccepted(self, args):
print('Text has been accepted.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Enter some text into the Editbox, and/or press Return while the Editbox has focus.

== Examination ==
In the context of the previous examples, this is all pretty straightforward; this simply demonstrates some additional events which are relevant to an Editbox.

As an exercise for the reader, consider the implications of removing the mapping of the return key from `KEYMAP_ASCII`, and why the effects are what they are.

User:Crond/sandbox/openglEventExample

2011-06-18T21:23:01Z

Crond: /* Source */ add keyboard support

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the 'self' argument.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox

2011-06-18T21:18:46Z

Crond: /* Persistence */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Persistence ===
'''Todo: Is this true? And if it's not, why did I think it was?''' 
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].

User:Crond/sandbox

2011-06-18T21:18:35Z

Crond: /* Persistence */ hmm

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== Known issues ==
=== Persistence ===
'''Todo: Is this true? And if it's not, why did I think it was?'''
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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].

User:Crond/sandbox

2011-06-18T21:17:46Z

Crond: /* Subscriptions */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== 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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A basic demonstration of subscribing to events can be found [[User:Crond/sandbox/openglEventExample|here]].
* A further demonstration of event subscriptions can be found [[User:Crond/sandbox/openglEventExample2|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].

User:Crond/sandbox/openglEventExample

2011-06-18T21:13:34Z

Crond:

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents the basics of using subscriptions to respond to events. The example retrieves two buttons and defines a method to be called when they are each clicked.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
The source code uses a modified version of the OpenGL example posted [[User:Crond/sandbox/openglExample|here]].

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', './datafiles/schemes')
self.rp.setResourceGroupDirectory('imagesets', './datafiles/imagesets')
self.rp.setResourceGroupDirectory('fonts', './datafiles/fonts')
self.rp.setResourceGroupDirectory('layouts', './datafiles/layouts')
self.rp.setResourceGroupDirectory('looknfeels', './datafiles/looknfeel')
self.rp.setResourceGroupDirectory('schemas', './datafiles/xml_schemas')
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize: Subscriptions
def initializeSubscriptions(self):

# In order to be able to access the buttons, we need to get a copy of their parent.
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')

# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')

# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
self.initializeSubscriptions()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Handler: buttonOkayClicked
def buttonOkayClicked(self, args):
print('Okay has been clicked.')
return

# Handler: buttonCancelClicked
def buttonCancelClicked(self, args):
print('Cancel has been clicked.')
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
Just click either of the two buttons on the 'NewNode' frame window; some output will appear on the console.

== Examination ==
=== Layout to Python ===
To subscribe to an event, the application needs two fundamental details: the layout, and the widget that should respond to an event. The layout is simple - we just pass the name of it to the PyCEGUI WindowManager object; getting child windows and/or widgets can be a little more subtle - to do this, we have to know the name of the window in question.

In the case of the example above, we want to respond to events on the 'NewNode' frame window, so we first retrieve a copy of it - as indicated by this line:

<source lang="python">
self.windowNewNode = self.rootWindow.getChild('Demo/NewNode')
</source>

Then, we need a copy of the buttons which we want to listen for events, as indicated by these lines:

<source lang="python">
# Now, we get the buttons.
self.buttonOkay = self.windowNewNode.getChild('Demo/NewNode/Okay')
self.buttonCancel = self.windowNewNode.getChild('Demo/NewNode/Cancel')
</source>

Finally, we want to set what events we respond to and how we respond to them. We do this by defining methods on our object, and telling PyCEGUI to call them when specific events happen. This is indicated by the following:

<source lang="python">
# And subscribe to the events, telling PyCEGUI what method it should call when the event happens.
self.buttonOkay.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonOkayClicked')
self.buttonCancel.subscribeEvent(PyCEGUI.PushButton.EventClicked, self, 'buttonCancelClicked')
</source>

The first argument is specifying what event to listen for (in this case, the clicking of the button), and the second/third arguments specify what function/method should be invoked when the event in question happens.

'''Note: Future versions do not require the 'self' argument.'''

=== Layout editing ===
The exact name of the widgets you want to access can be determined via the XML 'Name' property, as found in the layout files.

In the event you are not creating your layout files by hand, the names can be found via the CELayoutEditor under the 'Name' property in the Main Dialog.

User:Crond/sandbox/openglEventExample

2011-06-18T21:01:01Z

Crond: Created page with "{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}} == Introduction == This presents the basics of using subscriptions to respond to events. The example retri..."

User:Crond/sandbox

2011-06-18T20:54:27Z

Crond: /* Examples */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== 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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A demonstration of subscribing to events in the context of a single class can be found [[User:Crond/sandbox/openglEventExample|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].

User:Crond/sandbox/eventExample1

2011-06-18T20:53:23Z

Crond: delete me

Delete me.

User:Crond/sandbox/openglSpecialKeyboardExample

2011-06-18T20:52:16Z

Crond: /* Source */ pep8

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic keyboard processing OpenGL application, as found [[User:Crond/sandbox/openglKeyboardExample|here]]. The goal is to present a further refinement of keyboard processing, specifically the handling of "special" keys, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
As before, we can see that this works by running the application, typing into the Editbox, and pressing the arrow keys, or any of the other keys.

Several keys, such as Escape and Return, are not readily testable (i.e. produce no discernible effects on the application), although they do work. It is left as an exercise to the reader to prove it.

== Examination ==
=== GLUT, ASCII, PyCEGUI ===
It can be a little tricky, at times, to separate them all. A good rule of thumb is that using the `ord` function on any input received via GLUT will produce the ASCII value, which can then be handled in whatever way the application desires - e.g. mapping it to a PyCEGUI value.

An additional note is that what GLUT considers to be a "special" key is not exactly what PyCEGUI (or any other library, for that matter) considers to be special. For this reason, the `KEYMAP_ASCII` exists and helps define additional keys that are special, whatever that may mean in a particular context.

User:Crond/sandbox/openglKeyboardExample

2011-06-18T20:51:08Z

Crond: /* Source */ pep8

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [[User:Crond/sandbox/openglExample|here]]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
self.sys.injectChar(ord(key))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())

</source>

== Demonstration ==
We can see that this works by running the application, and typing into the Editbox, as provided by the 'New Node' frame window.

== Examination ==
=== 'ord' function ===
The 'ord' function is a built-in Python function, which converts a single character (or a string of length one, if you prefer) to its Unicode/ASCII value; for further details, see the Python documentation [http://docs.python.org/release/2.6.5/library/functions.html#ord here].

User:Crond/sandbox/openglExample

2011-06-18T20:49:00Z

Crond: /* Source */ pep8

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This presents a minimal PyCEGUI application, using OpenGL as the renderer. The goal is to familiarize the reader with the basics of how to get PyCEGUI up and running, and to provide a few pointers along the way.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

User:Crond/sandbox/openglSpecialKeyboardExample

2011-06-18T20:42:29Z

Crond: /* GLUT, ASCII, PyCEGUI */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic keyboard processing OpenGL application, as found [[User:Crond/sandbox/openglKeyboardExample|here]]. The goal is to present a further refinement of keyboard processing, specifically the handling of "special" keys, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
As before, we can see that this works by running the application, typing into the Editbox, and pressing the arrow keys, or any of the other keys.

Several keys, such as Escape and Return, are not readily testable (i.e. produce no discernible effects on the application), although they do work. It is left as an exercise to the reader to prove it.

== Examination ==
=== GLUT, ASCII, PyCEGUI ===
It can be a little tricky, at times, to separate them all. A good rule of thumb is that using the `ord` function on any input received via GLUT will produce the ASCII value, which can then be handled in whatever way the application desires - e.g. mapping it to a PyCEGUI value.

An additional note is that what GLUT considers to be a "special" key is not exactly what PyCEGUI (or any other library, for that matter) considers to be special. For this reason, the `KEYMAP_ASCII` exists and helps define additional keys that are special, whatever that may mean in a particular context.

User:Crond/sandbox/openglSpecialKeyboardExample

2011-06-18T20:39:34Z

Crond: /* Introduction */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic keyboard processing OpenGL application, as found [[User:Crond/sandbox/openglKeyboardExample|here]]. The goal is to present a further refinement of keyboard processing, specifically the handling of "special" keys, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
As before, we can see that this works by running the application, typing into the Editbox, and pressing the arrow keys, or any of the other keys.

Several keys, such as Escape and Return, are not readily testable (i.e. produce no discernible effects on the application), although they do work. It is left as an exercise to the reader to prove it.

== Examination ==
=== GLUT, ASCII, PyCEGUI ===
It can be a little tricky, at times, to separate them all. A good rule of thumb is that using the `ord` function on any input received via GLUT will produce the ASCII value, which can then be handled in whatever way the application desires - e.g. mapping it to a PyCEGUI value.

User:Crond/sandbox/openglSpecialKeyboardExample

2011-06-18T20:37:31Z

Crond: Created page with "{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}} == Introduction == This is a simple modification of the basic OpenGL application, as found [[User:Crond/sa..."

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [[User:Crond/sandbox/openglExample|here]]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Keymap: ASCII
KEYMAP_ASCII = {8 : PyCEGUI.Key.Scan.Backspace,
13 : PyCEGUI.Key.Scan.Return,
27 : PyCEGUI.Key.Scan.Escape,
127 : PyCEGUI.Key.Scan.Delete}

# Keymap: GLUT
KEYMAP_GLUT = {GLUT_KEY_LEFT : PyCEGUI.Key.Scan.ArrowLeft,
GLUT_KEY_RIGHT : PyCEGUI.Key.Scan.ArrowRight,
GLUT_KEY_HOME : PyCEGUI.Key.Scan.Home,
GLUT_KEY_END : PyCEGUI.Key.Scan.End}

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutSpecialFunc(self.handlerKeyboardSpecial)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Assist keyboard
def handlerAssistKeyboard(self, key):
try:
self.sys.injectKeyDown(KEYMAP_ASCII[key])
except KeyError:
return False
return True

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
k = ord(key)
if not self.handlerAssistKeyboard(k):
self.sys.injectChar(ord(key))
return

# Handler: Keyboard special
def handlerKeyboardSpecial(self, key, x, y):
try:
self.sys.injectKeyDown(KEYMAP_GLUT[key])
except KeyError:
# Ignore it.
pass
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
As before, we can see that this works by running the application, typing into the Editbox, and pressing the arrow keys, or any of the other keys.

Several keys, such as Escape and Return, are not readily testable (i.e. produce no discernible effects on the application), although they do work. It is left as an exercise to the reader to prove it.

== Examination ==
=== GLUT, ASCII, PyCEGUI ===
It can be a little tricky, at times, to separate them all. A good rule of thumb is that using the `ord` function on any input received via GLUT will produce the ASCII value, which can then be handled in whatever way the application desires - e.g. mapping it to a PyCEGUI value.

User:Crond/sandbox

2011-06-18T20:21:29Z

Crond: /* Basic OpenGL */ more link

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== 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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].
*A further modification, which adds special keyboard support, can be found [[User:Crond/sandbox/openglSpecialKeyboardExample|here]].

=== Subscriptions ===
* A demonstration of subscribing to events in the context of a single class can be found [[User:Crond/sandbox/eventExample1|here]].
* A demonstration of subscribing to events in the context of multiple classes can be found [[User:Crond/sandbox/eventExample2|here]].
* A demonstration of subscribing to events using the Observer pattern can be found [[User:Crond/sandbox/eventExample3|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].

User:Crond/sandbox/openglKeyboardExample

2011-06-18T20:19:32Z

Crond: ord

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [[User:Crond/sandbox/openglExample|here]]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
self.sys.injectChar(ord(key))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
We can see that this works by running the application, and typing into the Editbox, as provided by the 'New Node' frame window.

== Examination ==
=== 'ord' function ===
The 'ord' function is a built-in Python function, which converts a single character (or a string of length one, if you prefer) to its Unicode/ASCII value; for further details, see the Python documentation [http://docs.python.org/release/2.6.5/library/functions.html#ord here].

User:Crond/sandbox/openglKeyboardExample

2011-06-18T20:14:55Z

Crond: /* Introduction */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [[User:Crond/sandbox/openglExample|here]]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
self.sys.injectChar(ord(key))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
We can see that this works by running the application, and typing into the Editbox, as provided by the 'New Node' frame window.

User:Crond/sandbox/openglKeyboardExample

2011-06-18T20:14:35Z

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 

== Introduction ==
This is a simple modification of the basic OpenGL application, as found [User:Crond/sandbox/openglExample|here]. The goal is to present the basics of keyboard processing, via OpenGL and PyCEGUI.

== Requirements ==
* Python 2.6 (untested on Python 3.+)
* PyCEGUI
* PyOpenGL (GLU and GLUT, as well)

== Notes ==
This example assumes you have the CEGUI resources located in the same directory as the script; change `PATH_RESOURCES` if they are elsewhere.

== Source ==
<source lang="python">
#!/usr/bin/env python
#
#
# example.py

# Import: std
import sys, os

# Import: PyOpenGL
from OpenGL.GL import *
from OpenGL.GLU import *
from OpenGL.GLUT import *

# Import: PyCEGUI
import PyCEGUI
from PyCEGUIOpenGLRenderer import OpenGLRenderer as Renderer

# Constants
PATH_RESOURCES = './'

# Application
class Application(object):

# Constructor
def __init__(self):
super(Application, self).__init__()
self.lastFrameTime = 0
self.updateFPS = 0
return

# Initialize: OpenGL
# - A full list of values for `glutInitDisplayMode` can be found in the GLUT
# documentation.
def initializeOpenGL(self):
glutInit()
glutInitDisplayMode(GLUT_DEPTH | GLUT_DOUBLE | GLUT_RGBA)
glutInitWindowSize(1024, 768)
glutInitWindowPosition(-1, -1) # Let the windowing system figure it out
glutCreateWindow("Crazy Eddie's GUI Mk-2 - glut Base Application")
glutSetCursor(GLUT_CURSOR_NONE)
return

# Initialize: Handlers
# - Setup the methods which will be called when events happen.
def initializeHandlers(self):
glutDisplayFunc(self.handlerDisplay)
glutReshapeFunc(self.handlerResize)
glutKeyboardFunc(self.handlerKeyboard)
glutMouseFunc(self.handlerMouse)
glutMotionFunc(self.handlerMouseMotion)
glutPassiveMotionFunc(self.handlerMouseMotion)
return

# Initialize: PyCEGUI
# - Store some components; saves a lot of typing.
def initializePyCEGUI(self):
Renderer.bootstrapSystem()
self.sys = PyCEGUI.System.getSingleton()
self.rp = self.sys.getResourceProvider()
self.scheme = PyCEGUI.SchemeManager.getSingleton()
self.wm = PyCEGUI.WindowManager.getSingleton()
return

# Initialize: Defaults
# - Resource locations.
def initializeDefaults(self):
self.rp.setResourceGroupDirectory('schemes', os.path.join(PATH_RESOURCES, 'datafiles/schemes'))
self.rp.setResourceGroupDirectory('imagesets', os.path.join(PATH_RESOURCES, 'datafiles/imagesets'))
self.rp.setResourceGroupDirectory('fonts', os.path.join(PATH_RESOURCES, 'datafiles/fonts'))
self.rp.setResourceGroupDirectory('layouts', os.path.join(PATH_RESOURCES, 'datafiles/layouts'))
self.rp.setResourceGroupDirectory('looknfeels', os.path.join(PATH_RESOURCES, 'datafiles/looknfeel'))
self.rp.setResourceGroupDirectory('schemas', os.path.join(PATH_RESOURCES, 'datafiles/xml_schemas'))
PyCEGUI.Imageset.setDefaultResourceGroup('imagesets')
PyCEGUI.Font.setDefaultResourceGroup('fonts')
PyCEGUI.Scheme.setDefaultResourceGroup('schemes')
PyCEGUI.WidgetLookManager.setDefaultResourceGroup('looknfeels')
PyCEGUI.WindowManager.setDefaultResourceGroup('layouts')
parser = self.sys.getXMLParser()
if parser.isPropertyPresent('SchemaDefaultResourceGroup'):
parser.setProperty('SchemaDefaultResourceGroup', 'schemas')
return

# Initialize: GUI
# - This is where we are actually setting up the windows we will see.
def initializeGUI(self):
self.scheme.create('VanillaSkin.scheme')
self.scheme.create('TaharezLook.scheme')

# GUISheet
self.rootWindow = self.wm.loadWindowLayout('VanillaWindows.layout')
self.sys.setGUISheet(self.rootWindow)

# Cursor
self.sys.setDefaultMouseCursor('Vanilla-Images', 'MouseArrow')

# An extra window
w = self.wm.createWindow('TaharezLook/FrameWindow', 'Demo window')
self.rootWindow.addChildWindow(w)
return

# Initialize
def Initialize(self):
self.initializeOpenGL()
self.initializeHandlers()
self.initializePyCEGUI()
self.initializeDefaults()
self.initializeGUI()
return

# Handler: Display
def handlerDisplay(self):

# Injecting the time allows CEGUI to know how much time has passed, and
# use that to coordinate certain activities - fading, animation, tooltips,
# etc.
now = glutGet(GLUT_ELAPSED_TIME)
elapsed = (now - self.lastFrameTime) / 1000.0
self.lastFrameTime = now
self.updateFPS = self.updateFPS - elapsed
self.sys.injectTimePulse(elapsed)

# Actual rendering
# - `renderGUI` updates CEGUI's picture of the GUI.
# - `glutPostRedisplay` is what actually marks the window as needing to
# be redrawn by OpenGL.
glClear(GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT)
self.sys.renderGUI()
glutPostRedisplay()
glutSwapBuffers()
return

# Handler: Resize
# - `glViewport` modifies the OpenGL viewport to whatever the window size is.
def handlerResize(self, width, height):
glViewport(0, 0, width, height)
self.sys.notifyDisplaySizeChanged(PyCEGUI.Size(width, height))
return

# Handler: Keyboard
def handlerKeyboard(self, key, x, y):
self.sys.injectChar(ord(key))
return

# Handler: Mouse buttons
def handlerMouse(self, button, state, x, y):
if button == GLUT_LEFT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.LeftButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.LeftButton)
elif button == GLUT_RIGHT_BUTTON:
if state == GLUT_UP:
self.sys.injectMouseButtonUp(PyCEGUI.RightButton)
else:
self.sys.injectMouseButtonDown(PyCEGUI.RightButton)
return

# Handler: Mouse motion
def handlerMouseMotion(self, x, y):
self.sys.injectMousePosition(x, y)
return

# Run
def Run(self):
self.lastFrameTime = glutGet(GLUT_ELAPSED_TIME)
glutMainLoop()
return

# Main
def main():
app = Application()
app.Initialize()
app.Run()
return 0

# Guard
if __name__ == '__main__':
sys.exit(main())
</source>

== Demonstration ==
We can see that this works by running the application, and typing into the Editbox, as provided by the 'New Node' frame window.

User:Crond/sandbox

2011-06-18T20:09:45Z

Crond: /* Basic OpenGL */

{{VersionBadge|0.7}} {{VersionAtLeast|0.7.5}}
 
== 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: [http://pypi.python.org/pypi/PyCEGUI/0.7.5 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 [http://www.cegui.org.uk/docs/current 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 [http://freshmeat.net/projects/pyplusplus Py++] and [http://www.boost.org/doc/libs/1_46_1/libs/python/doc/ Boost.Python] - this allows rapid development of the bindings and easy maintenance. It may be a bit slower than [http://www.swig.org/ 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:

<source lang="python">
someObject = PyCEGUI.WindowManager.getSingleton().createWindow('TaharezLook/Listbox', 'someListbox')
someObject.randomAttribute = 'Toga! Toga!'
print(someObject.randomAttribute)
</source>

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.

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

Subscribing to listenerClass:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, listenerClass, 'methodInThatClass')
</source>

Subscribing to a free function:
<source lang="python">
wnd.subscribeEvent(PyCEGUI.Window.EventMouseEnters, PythonModule.freeFunction)
</source>

== 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:

<source lang="python">
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())
</source>

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:

<source lang="python">
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
</source>

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:

<source lang="python">
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()
</source>

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 [http://www.panda3d.org/forums/viewtopic.php?t=10814 these bindings].

== OpenGL bugs ==
If an Intel 915GM, 910GML, or similar chipset is used, it might be necessary to create/destroy a window before the display mode is initialized via OpenGL. The following illustrates:

<source lang="python">
glutInit()

# This will segfault the application
glutInitDisplayMode(0)
</source>

Instead, the following can be done to circumvent this problem:

<source lang="python">
glutInit()

# Kludge
glutDestroyWindow(glutCreateWindow(''))

# This will no longer segfault the application
glutInitDisplayMode(0)
</source>

Additional complications may arise via this chipset.

== Examples ==
=== Basic OpenGL ===
*A demonstration of a basic application using PyCEGUI and OpenGL can be found [[User:Crond/sandbox/openglExample|here]].
*A simple modification, which adds rudimentary keyboard support, can be found [[User:Crond/sandbox/openglKeyboardExample|here]].

=== Subscriptions ===
* A demonstration of subscribing to events in the context of a single class can be found [[User:Crond/sandbox/eventExample1|here]].
* A demonstration of subscribing to events in the context of multiple classes can be found [[User:Crond/sandbox/eventExample2|here]].
* A demonstration of subscribing to events using the Observer pattern can be found [[User:Crond/sandbox/eventExample3|here]].

=== todo: Multi-class example ===
See [[PyCEGUI/Example|here]].