How to use EmbeddedPyQt
=======================


Calling Python from C++
------------------------

The method ``EmbeddedPyQt::execute`` emits a signal
``excecutionRequested(QString command, bool globalContext)``
which is connected to the Python interpreter. 

.. code-block:: c

 embpyqt->execute("embpyqt_console.Visible = True", true);
 

If the second parameter is true then the command will be executed in a
global context. Else the call will be executed in a new context.

To execute a complete script you could use Python's execfile function:

.. code-block:: c

 embpyqt->execute("execfile('myscript.py')", false);


Or you import the script as a module

.. code-block:: c

 embpyqt->execute("import myscript", false);


But beware that a module will be only imported once.

To pass complex parameters (e.g. QObject instances) to Python the best
way is to create a signal. Then load a script into the global context
and connect the C++ signal with your Python callback. After that you can
emit the signal.


Using C++ from Python
---------------------

Python can connect to existing C++ signals and is able to modify the
user interface. All available classes and instances are availale in
the global context. With a *fresh* context you have to import the names
from the embeddedpyqt package.

.. code-block:: python

  from embeddedpyqt import *
  embpyqt_console.Visible = True
  test = Test()        # available in to demo app
  print test.calc(1,2) # should return 3 
  embpyqt_console.WindowTitle = "Done"
 

Differences to sip
------------------

Because the bindings are dynamically created they behave not like sip
bindings. The classes are created on-the-fly with Python meta
programming. 

Using the descriptor protocol it is possible to support
properties natively (without using property/setProperty). 
To prevent name clashes between properties and their getter methods
the property name always starts with a captital letter.
So while you would do the following with PyQt objects

.. code-block:: python

   old_title = dlg.windowTitle()
   dlg.setWindowTitle(old_title + "*")
   
You now can write

.. code-block:: python

   dlg.WindowTitle = dlg.WindowTitle + "*"

The idea is to provide a really simple scripting api for the end user.

Additionally -like QtScript- a child object can be accessed like an attribute if
the child has a object name.

**Known limitations**:

  * a little bit slower than sip
  * currently sub-classing is not really working and untested
  * explicit garbage collection handling might be needed for some objects
  * exception handling not fully tested and undocumented
  * creating a new QApplication instance will stop your app from working, please use qApp or QCoreApplication.instance() instead


.. hint::

  The underlying QObject of every wrapped class is available as an attribute 
  called ``_qt``.