.. _introduction:

Getting Started
===============

Simple Example
--------------

To start with our tutorial we create the simplest program possible.
This program will create an empty 200 x 200 pixel window.

.. image:: ../images/simple_example.png

.. literalinclude:: ../examples/simple_example.py
    :linenos:

We will now explain each line of the example.

.. literalinclude:: ../examples/simple_example.py
    :lines: 1-4

In the beginning, we have to import the Gtk module to be able to
access GTK+'s classes and functions.
Since a user's system can have multiple versions of GTK+ installed at the same,
we want to make sure that when we import Gtk that it refers to GTK+ 3
and not any other version of the library, which is the purpose
of the statement ``gi.require_version('Gtk', '3.0')``.

The next line creates an empty window.

.. literalinclude:: ../examples/simple_example.py
    :lines: 6

Followed by connecting to the window's delete event to ensure that the
application is terminated if we click on the *x* to close the window.

.. literalinclude:: ../examples/simple_example.py
    :lines: 7

In the next step we display the window.

.. literalinclude:: ../examples/simple_example.py
    :lines: 8

Finally, we start the GTK+ processing loop which we quit when the window is
closed (see line 6).

.. literalinclude:: ../examples/simple_example.py
    :lines: 9

To run the program, open a terminal, change to the directory of the file, and
enter::

    python simple_example.py

Extended Example
----------------
For something a little more useful, here's the PyGObject version of the classic
"Hello World" program.

.. image:: ../images/extended_example.png

.. literalinclude:: ../examples/extended_example.py
    :linenos:

This example differs from the simple example as we sub-class :class:`Gtk.Window` to define our own
:class:`MyWindow` class.

.. literalinclude:: ../examples/extended_example.py
    :lines: 7

In the class's constructor we have to call the constructor of the super class. In addition,
we tell it to set the value of the property `title` to `Hello World`.

.. literalinclude:: ../examples/extended_example.py
    :lines: 9

The next three lines are used to create a button widget, connect to its `clicked` signal and
add it as child to the top-level window.

.. literalinclude:: ../examples/extended_example.py
    :lines: 11-13

Accordingly, the method :meth:`on_button_clicked` will be called if you click on the button.

.. literalinclude:: ../examples/extended_example.py
    :lines: 15-16

The last block, outside of the class, is very similar to the simple example above,
but instead of creating an instance of the generic :class:`Gtk.Window` class, we create
an instance of :class:`MyWindow`.