Getting Started — PyGObject

Skip to main content
`Ctrl`+`K`

# Getting Started

This section will give you a first contact with GTK, explaining each line of code.

See also

Getting Started with GTK in the GTK documentation.

## Basic Example

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

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7def on_activate(app):
     8    # Create window
     9    win = Gtk.ApplicationWindow(application=app)
    10    win.present()
    11
    12
    13# Create a new application
    14app = Gtk.Application(application_id="com.example.App")
    15app.connect("activate", on_activate)
    16
    17# Run the application
    18app.run(None)

We will now explain each line of the example.

    import gi

    gi.require_version("Gtk", "4.0")
    from gi.repository import Gtk

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 GTK4 and not any other version of the library, which is the purpose of the statement `gi.require_version('Gtk', '4.0')`.

    app = Gtk.Application(application_id="com.example.App")
    app.connect("activate", on_activate)

Now we create an application. The `application_id` argument is needed as method of identifying your application to the system, if you do not know what to set please check this tutorial.

We are also connecting to the application’s `activate` event, where we will create the window.

    def on_activate(app):
        win = Gtk.ApplicationWindow(application=app)
        win.present()

In the `on_activate` callback we will create an empty window, and then display it using the `Gtk.Window.present()` method.

    app.run(None)

Finally, we start the application using the `Gio.Application.run()` method.

### Minimal Example without GtkApplication

In GTK 4, if you don’t want to use `Gtk.Application` you can use this replacement that will iterate the default main loop until all windows have been closed:

Attention

Doing this is only useful for very specific use cases like tests. For app development you should always use `Gtk.Application`.

    import gi
    gi.require_version('Gtk', '4.0')
    from gi.repository import GLib, Gtk

    win = Gtk.Window()
    win.present()

    while (len(Gtk.Window.get_toplevels()) > 0):
        GLib.MainContext.default().iteration(True)

## Extended Example

For something a little more useful, here’s the PyGObject version of the classic “Hello World” program.

     1import gi
     2
     3gi.require_version("Gtk", "4.0")
     4from gi.repository import Gtk
     5
     6
     7class MyWindow(Gtk.ApplicationWindow):
     8    def __init__(self, **kargs):
     9        super().__init__(**kargs, title="Hello World")
    10
    11        self.button = Gtk.Button(label="Click Here")
    12        self.button.connect("clicked", self.on_button_clicked)
    13        self.set_child(self.button)
    14
    15    def on_button_clicked(self, _widget):
    16        self.close()
    17
    18
    19def on_activate(app):
    20    # Create window
    21    win = MyWindow(application=app)
    22    win.present()
    23
    24
    25app = Gtk.Application(application_id="com.example.App")
    26app.connect("activate", on_activate)
    27
    28app.run(None)

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

See also

For more info about subclassing read GObject Subclassing.

    class MyWindow(Gtk.ApplicationWindow):

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. Note that we are also receiving and passing `**kargs`, so we can redirect other arguments passed on `MyWindow` construction to the base class.

        def __init__(self, **kargs):
            super().__init__(**kargs, title="Hello World")

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.

            self.button = Gtk.Button(label="Click Here")
            self.button.connect("clicked", self.on_button_clicked)
            self.set_child(self.button)

Accordingly, the method on_button_clicked will be called if you click on the button. In this example we are using the method to print `Hello World` and calling the window `Gtk.Window.close()` method to close the window.

        def on_button_clicked(self, _widget):
            self.close()

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