# PyGTK Shell 1.90.1 Tutorial

Felix Rabe
`<public@felixrabe.textdriven.com>`

Install PyGTK Shell if you have not already, then read on. Sufficient knowledge of Python and PyGTK is assumed.

## Hello World

The Hello World example looks like this:

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

Example: 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 1.90.1 allows direct user interaction from a running PyGTK program. Its function is similar to the "Python Console" provided by GEdit and Rhythmbox, but it does it in a more minimal way. A more sophisticated console should get included before release 2.0.

Example: 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 contact me.