PyGTK Shell {version} Tutorial
==============================
Felix Rabe <public@felixrabe.textdriven.com>

link:install.html[Install] PyGTK Shell if you have not already, then read
on.  Sufficient knowledge of http://www.python.org/[Python] and
http://www.pygtk.org/[PyGTK] is assumed.

Hello World
-----------

The Hello World example looks like this:

.hello_world_pygtkshell.py
-------------------------------------
#!/usr/bin/env python
from PyGTKShell.API import *
Window()(Label("Hello, World!"))
gtk.main()
-------------------------------------

You can even run it as a single (if a bit long) line that you can
run from a command line:

-------------------------------------
$ python -c 'from PyGTKShell.API import *; Window()(Label("Hello, World!")); gtk.main()'
-------------------------------------

Whereas with PyGTK you would have to write it that way -- which does
even a bit less than the code above, but it is sufficiently equivalent:

.hello_world_gtk.py
-------------------------------------
#!/usr/bin/env python
import gtk
w = gtk.Window()
w.connect("destroy", gtk.main_quit)
l = gtk.Label("Hello, World!")
w.add(l)
w.show_all()
gtk.main()
-------------------------------------

Getting a RawConsole on your screen
-----------------------------------

The `RawConsole` class (and its derivatives) is the way PyGTK Shell
{version} allows direct user interaction from a running PyGTK program.
Its function is similar to the "Python Console" provided by
http://www.gedit.org/[GEdit] and http://www.rhythmbox.org/[Rhythmbox],
but it does it in a more minimal way.  A more sophisticated console
should get included before release 2.0.

.pygtk_rawconsole.py
-------------------------------------
#!/usr/bin/env python
from PyGTKShell.RawConsole import *  # imports all of API as well
w = Window()
w.set_title("PyGTK Shell Console")
w(RawConsoleWithIntro())  # special subclass of RawConsole
w.set_default_size(600, 500)
gtk.main()
-------------------------------------

This gives you a minimalistic console to work with.  In the upper part,
you can enter Python code to be executed by pressing either
'F5' or 'Ctrl+E'.
Apart from `__builtins__`, the `console` object is available
in the namespace by default, which is the
`RawConsole` (or subclass) instance.

As you get more comfortable with it,
you can safely replace `RawConsoleWithIntro` above with `RawConsole` or
`RawConsoleCenterInit`.  All of them define the same namespace,
but the latter two do not run an example script on instantiation.

Running the above script as-is, you see everything that
the `PyGTKShell.API` module provides.  Mostly, the module
consists of PyGTK-derived classes that have the same names as,
and are easier to use than, their counterparts from the `gtk` module.
This means that if a class from the `gtk` module is not yet explicitly
included in `PyGTKShell.API`, you can nonetheless use it from
the `gtk` module.  The `gtk`, `gobject` and `pango` modules get
included by the API module as well, as you might have guessed
from the `gtk.main()` call above.

Getting into the details
------------------------

An other large sum of classes with a name ending in `...Mixin` can
be found in the `PyGTKShell.Mixins` module.
They are responsible for making the classes from `PyGTKShell.API`
behave differently from those in `gtk`.  Each behavior is implemented
by a separate mixin, which has so far paid off in keeping the code
modular and maintainable.

There are Python docstrings that describe each class in PyGTK Shell,
which should be sufficient to gain the
necessary understanding when reading the code.
In the future, a more concise reference manual will be built based on
those strings, but in the meantime, you should be able to find your way
around the still very small codebase.

If you encounter any difficulties, feel free to
mailto:public@felixrabe.textdriven.com[contact me].

