> For the complete documentation index, see [llms.txt](https://bharatkalluri.gitbook.io/gnome-developer-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bharatkalluri.gitbook.io/gnome-developer-handbook/writing-apps-using-python/understanding-widgets-layouts-and-templates.md).

# Understanding Widgets, Layouts & Templates

Widgets are one of the most atomic components for GNOME. Everything you see on the screen in a GTK application is a widget. To create an application, we place a couple of widgets in a layout. 

`Button`, `Image`, `TextView`, `DrawingArea` are some examples of widgets. `Box` and `Grid` are some examples of Layouts.

Let us have a look at what `window.ui`, Right click on `window.ui` and click on `Open in` > `UI desiginer`. This is what we have as of now

![The default hello world template](/files/-MCwyXYD0yzjnQmRGfP5)

The absolute parent component here is the `Application window` . Inside the application window, there is a `HeaderBar` component and a `label` component.  The `label` component has a ID of `label`. ID is important as it serves as a pointer later on while writing code. 

Let us have a look at what `window.py` contains

```
from gi.repository import Gtk


@Gtk.Template(resource_path='/com/yourusername/splash/window.ui')
class SplashWindow(Gtk.ApplicationWindow):
    __gtype_name__ = 'SplashWindow'

    label = Gtk.Template.Child()

    def __init__(self, **kwargs):
        super().__init__(**kwargs)
```

The `SplashWindow` sub-classes `Gtk.ApplicationWindow` (Since the absolute parent component in the template is a `Gtk.ApplicationWindow`). The rule of thumb is that per template file, there will be one python class which sub-classes the absolute parent GTK type. The `__gtype_name__` of the class should be the same as the ID of the parent component.

`Gtk.Template.Child()` is used to retrieve the widget whose ID is the same as the variable name. In our case, the label widget's ID is `label`. So label will be a widget whose class will be `Gtk.Label`. 

This is the basic premise of templates in python.

### Customizing the UI layout

Now that we understand the basics, we won't be needing any layouts since the UI for the application is very simple. Let us go back to the designer view for `window.ui` and 

* Remove the `Gtk.Label` and replace the label widget with `Gtk.Image`. Set the ID of the component to `wallpaper_container`.
* Click on the headerbar and change the text from "Hello World" to "Splash". Make sure the ID of header bar is set to `header_bar` 
* In the options side bar when clicked on `header_bar` , change the last option (`Number of Items`) from 0 to 1. There will be an empty space which pops up to the left of the title of the header bar. Double click on the empty space and select `Gtk.Button` . 
* Set the ID of `Gtk.Button` to `shuffle_button` . Also set the text of the button to `Shuffle`

![The modified version of the template](/files/-MCx7TaVVI6t0sRyfXoj)

Let us add a menu button, later we can add a pop over menu which will contain an `about` button. On click will show the about dialog.

Let's get back to editing `window.ui` . Click on the header bar and in the properties sidebar, increment `Number of items` from 1 to 2. You will see a new blank space pop up.

![Creating space for the menu button](/files/-MD0TkoZ9mQ1wnY9hQ8-)

Double click on empty space and add a `Gtk.MenuButton`. Go to the properties sidebar of the `Gtk.MenuButton` and set the ID of the button to `menu_button`. 

Double click and add `Gtk.Image`. In the properties sidebar, Set the ID to `open_menu_icon` and Icon name to `open-menu-symbolic`. 

![Setting the menu icon on the button](/files/-MD0UF_aj0VJhA4e8Uwv)

Let us move the menu button to the other end. Having two buttons on the same side of the header bar is not good design. Click on the Menu button and go to the second tab in the properties sidebar (named `child container properties`). There is an option called `Pack Type`. This decides which side the widgets align. Change the `Pack Type` to `End`. You can see that the menu moved to the right end of the header bar.

![Packing the button to the end](/files/-MD0FlkMOBqRGkxbOyIF)

Let us add a loading spinner as well. So that whenever we are loading an wallpaper from the internet, we can use the spinner to indicate work being done on the background. Go back to the header bar and increment the Number of items to 3. Now again, double click on the empty space and add a Gtk.Spinner. On the properties side bar, set the ID to loading\_spinner.

![Adding the spinner](/files/-MD0VUrzzXpEFM-um6Eg)

Looks good! Let us jump back to code and make use of this template as a base and build on top of it.

> Do not forget to save and commit these changes to your git repository! 


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://bharatkalluri.gitbook.io/gnome-developer-handbook/writing-apps-using-python/understanding-widgets-layouts-and-templates.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.