Set Window Size, Title and Icons: Using Window Classes in Kivy

This section introduces how to set window-related settings such as window size settings and title settings for Kivy applications that may be used frequently, as well as a sample using events of the Window class.

Screen Settings

Kivy recommends creating only one application screen. One is fine, since it is possible to switch screen views and display pop-up windows within the application screen.

To set window size, title, etc., use Window or App class.

kivy.core.window
kivy.app

Here are some commonly used settings

from kivy.core.window import Window
from kivy.app import App

# Set window size
#Window.size = (500, 500)
Window.system_size = (500, 500)

# Set minimum window size.
Window.minimum_width = 300
Window.minimum_height = 300

# Set icon in Window class.
# Window.set_icon('./icons/test-icon001.png')

# Set to full screen mode.
#Window.fullscreen = True

# Start with the window maximized.
# Window.maximize()

# Set background color.
Window.clearcolor = (0, 0, 1, 1)  # 青 (R, G, B, A)

# Set window position.
Window.left = 100
Window.top = 50

class WindowSettings1(App):
    def build(self):
        # Set application title.
        self.title = 'TestTitle'
        # Set icon in App class.
        self.icon = './icons/test-icon002.ico'
        return None

if __name__ == '__main__':
    WindowSettings1().run()

Set the Window Size Settings

Set the size of the window when it is started. There are two methods to change the size: the size method and the system_size method. if you set a value smaller than Window.minimum_width and Window.minimum_height, this size will be applied. It is recommended not to set a value smaller than this size.

Size Method

Calculated in logical size. Specify the width and height.

# Set window size (width, height).
Window.size = (800, 600)

system_size Method

Calculated by physical size. Specify width and height.

# Set window size (width, height).
Window.system_size = (300, 300)

Difference Between Window.size and Window.system_size

Window.size gets the logical size (scaled value) and Window.system_size gets the actual physical size (value in pixels), and the values are different.

• Window.size: logical size
• Window.system_size: physical size

For example, Kivy’s logical size of 300 is 525 in physical size. A sample code to check this is presented in the last section of this article.

Logical size ( logical size)
This is a scaled value based on DPI (Dot Density) and is used internally in Kivy to draw.

Physical size
The size of the window on the display in pixels where the window is actually drawn.

Setting the Title of the Title Bar

Sets the title of the window’s title bar. This method is provided in the Window class, but this did not work.

# This does not work.
Window.set_title('TestTitle')

Use the title method of the App class instead; it would be better to define it within build().

self.title = 'TestTitle'

Setting an Icon for the Title Bar

There are two ways to set an icon for the window title bar: in the Window class or in the App class.

Setting in the Window Class

Specify the path to the image file. Enter the file extension as well.

Window.set_icon('. /icons/test-icon001.png')

Set in the App Class

Similarly, specify the path to the image file.

self.icon = '. /icons/test-icon006.ico'

Available File Formats and Optimal Sizes

Image file formats supported by Kivy can be used.

• PNG
• JPEG
• GIF
• BMP
• ICO
• SVG

The official website lists the following as the optimal image sizes. This is old information, so it is uncertain, but 1:1 seems to be the correct size. I tried the above image format at 1024×1024 and had no problem. (This is too large for an icon. Perhaps 256×256 would be large enough.)

For GNU/Linux and Mac OSX, 256×256 or 1024×1024 is recommended; for Windows 7, 32×32 or smaller; for Windows 8, 256×256 or smaller. At least on Windows 8, 256×256 will work, but it will be reduced in size and will not look as good as a 32×32 icon.

Setting the Minimum Window Size

To set the minimum window size, do the following The unit is probably physical size (pixels).

# Set window width.
Window.minimum_height = 600

# Set the height of the window.
Window.minimum_width = 500

Note that both minimum_height and minimum_width must be set for this to work.

Start With Window Maximized

Starts with the window size maximized.

Window.maximize()

If you define this, you may not want to define Window.size. (It is not an error).

Starts Up in Full Screen Mode

Starts up in full screen mode, which can be True, False, or auto.

Window.fullscreen = True

Set Window Position

Enables the window to be positioned at the specified OS coordinates when launched. The upper left corner of the application screen will be placed at the specified coordinates, which are [x(horizontal axis): 0, y(vertical axis): 0].

Window.left = 100 # x-coordinate
Window.top = 50 # y-coordinate

Set Screen Color

Set the background color of the screen. Note that this setting is meaningless if the screen is filled with widgets. The color is specified in RGBA. Transparency does not work here.

Window.clearcolor = (0, 0, 1, 1) # Blue (R, G, B, A)

RGBA is explained in the following page

Controlling Window Resizing

I could not find a method to resize the window; there is a “resizable” setting in Config.ini, so I tried setting it in Config.set, but it did not work.

However, it is possible to control the screen shrinkage. As shown below, setting minimum_width and minimum_height to the same value as the window size will prevent it from shrinking. However, the user can make it larger than this size.

# Window sizing.
Window.size = (1000, 600)

# Set the minimum size of the window.
Window.minimum_width = 1000
Window.minimum_height = 600

Using Window Class Events

The Window class has many events that control the window. Some of them are listed below.

• on_key_down: An event that occurs when a key on the keyboard is pressed.
• on_key_up: Event that occurs when a key on the keyboard is released
• on_rotate: Event that occurs when the screen is rotated
• on_close: Event that occurs when the screen is closed
• on_cursor_enter: Event that occurs when the cursor hits the screen
• on_cursor_leave: An event that occurs when the cursor moves out of the screen
• on_minimize: Event that occurs when the screen is minimized
• on_maximize: Event that occurs when the screen is maximized
• on_restore: Event that occurs when the screen is activated after it has been minimized
• on_hide: Event that occurs when the screen is hidden
• on_show: Event that occurs when the screen is shown
• on_keyboard: Event that occurs when the keyboard is used for input
• on_key_down: Event that occurs when a key on the keyboard is pressed
• on_key_up: Event that occurs when a key on the keyboard is pressed and released.
• on_drop_begin: Event that occurs just before text or file is dropped in the screen.
• on_drop_file: Event that occurs when a file is dropped in the screen
• on_drop_text: Event that occurs when text is dropped in the screen
• on_drop_end: Event that occurs when a text or file is dropped in the screen.
• on_textedit: Event that occurs when text is entered with an IME

---

Displaying window.size and window.system_size Using on_resize

This is a sample code to check Window.size and Window.system_size using the on_resize event of the Window class event.

The on_resize event is fired when the window is resized.

window_event1.py

from kivy.app import App
from kivy.core.window import Window

Window.system_size = (300,300)
    
class WindowEvent1(App):
    def __init__(self, **kwargs):
        super().__init__(**kwargs)

        # on_resizeイベントをバインド
        Window.bind(on_resize=self.on_resize)

    def on_resize(self, instance, width, height):
        physical_size = Window.system_size
        self.root.ids.label.text = (
            f"Window resized to:\n"
            f"Logical size: {width} x {height}\n"
            f"Physical size: {physical_size}"
        )

if __name__ == "__main__":
    WindowEvent1().run()

windowevent1.kv

BoxLayout:
    orientation: 'vertical'

    Label:
        id: label
        text: ''

This code gets the “Logical size” and “Physical size” when the window is resized, and changes the text.

Code Explanation

Window.system_size = (300,300)

Defines the screen size at startup as physical size

BoxLayout:

In the kv file, a BoxLayout widget is specified as the root element. This will be the root widget.

 # Bind the on_resize event.
 Window.bind(on_resize=self.on_resize)

The bind method ties the overridden on_resize method to the on_resize event.

 # How to write bind
 Window.bind(event_name=callback_function)

• event_name: Name of the event. In this case, on_resize.
• callback_function: Function to execute when the event occurs. In this example, self.on_resize.

The on_resize method is called when the on_resize event occurs.

def on_resize(self, instance, width, height):

Override the on_resize method. The argument is (instance, width, height).

• instance: The object that fired the event (in this case, Window )
• width: The width of the new window is retrieved.
• height: The height of the new window is retrieved.

The width and height taken by the on_resize method were logical sizes.