App

The sketch lifecycle and the window.

App

App()

Base class for a Kiln sketch.

Subclass it and override the lifecycle methods (setup, update, draw, exit) and any event callbacks you need, then pass an instance to kiln.run. Every method is a no-op by default. The mouse position is kiln.mouse.x and kiln.mouse.y.

Methods

Name	Description
draw	Called every frame to draw.
exit	Called once when the app stops, however it stops.
files_dropped	Called when files are dropped on the window.
key_pressed	Called when a key is pressed.
key_pressed_event	Called with the full record of a key press.
key_released	Called when a key is released.
key_released_event	Called with the full record of a key release.
mouse_dragged	Called when the mouse moves with a button held.
mouse_dragged_event	Called with the full record of a drag.
mouse_entered	Called when the mouse enters the window.
mouse_exited	Called when the mouse leaves the window.
mouse_moved	Called when the mouse moves with no button held.
mouse_moved_event	Called with the full record of a mouse move.
mouse_pressed	Called when a mouse button is pressed.
mouse_pressed_event	Called with the full record of a press.
mouse_released	Called when a mouse button is released.
mouse_released_event	Called with the full record of a release.
mouse_scrolled	Called on scroll-wheel or trackpad scroll.
mouse_scrolled_event	Called with the full record of a scroll.
setup	Called once, after the window opens.
update	Called every frame before draw.
window_resized	Called after the window is resized.

draw

App.draw()

Called every frame to draw.

exit

App.exit()

Called once when the app stops, however it stops.

It also runs when setup, update or draw raises, and on Ctrl-C.

files_dropped

App.files_dropped(info)

Called when files are dropped on the window.

Parameters

Name	Type	Description	Default
info	DropInfo	The dropped file paths and drop position.	required

key_pressed

App.key_pressed(key)

Called when a key is pressed.

Parameters

Name	Type	Description	Default
key	int	The key code.	required

key_pressed_event

App.key_pressed_event(event)

Called with the full record of a key press.

Override it to see modifiers and scancodes. The default calls key_pressed(event.key).

Parameters

Name	Type	Description	Default
event	KeyEvent	The key event.	required

key_released

App.key_released(key)

Called when a key is released.

Parameters

Name	Type	Description	Default
key	int	The key code.	required

key_released_event

App.key_released_event(event)

Called with the full record of a key release.

The default calls key_released(event.key).

Parameters

Name	Type	Description	Default
event	KeyEvent	The key event.	required

mouse_dragged

App.mouse_dragged(x, y, button)

Called when the mouse moves with a button held.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required
button	int	The button held.	required

mouse_dragged_event

App.mouse_dragged_event(event)

Called with the full record of a drag.

The default calls mouse_dragged(event.x, event.y, event.button).

Parameters

Name	Type	Description	Default
event	MouseEvent	The mouse event.	required

mouse_entered

App.mouse_entered(x, y)

Called when the mouse enters the window.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required

mouse_exited

App.mouse_exited(x, y)

Called when the mouse leaves the window.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required

mouse_moved

App.mouse_moved(x, y)

Called when the mouse moves with no button held.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required

mouse_moved_event

App.mouse_moved_event(event)

Called with the full record of a mouse move.

The default calls mouse_moved(event.x, event.y).

Parameters

Name	Type	Description	Default
event	MouseEvent	The mouse event.	required

mouse_pressed

App.mouse_pressed(x, y, button)

Called when a mouse button is pressed.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required
button	int	The button pressed.	required

mouse_pressed_event

App.mouse_pressed_event(event)

Called with the full record of a press.

The default calls mouse_pressed(event.x, event.y, event.button).

Parameters

Name	Type	Description	Default
event	MouseEvent	The mouse event.	required

mouse_released

App.mouse_released(x, y, button)

Called when a mouse button is released.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required
button	int	The button released.	required

mouse_released_event

App.mouse_released_event(event)

Called with the full record of a release.

The default calls mouse_released(event.x, event.y, event.button).

Parameters

Name	Type	Description	Default
event	MouseEvent	The mouse event.	required

mouse_scrolled

App.mouse_scrolled(x, y, scroll_x, scroll_y)

Called on scroll-wheel or trackpad scroll.

Parameters

Name	Type	Description	Default
x	float	Mouse x in window points.	required
y	float	Mouse y in window points.	required
scroll_x	float	Horizontal scroll amount.	required
scroll_y	float	Vertical scroll amount.	required

mouse_scrolled_event

App.mouse_scrolled_event(event)

Called with the full record of a scroll.

The default calls mouse_scrolled(event.x, event.y, event.scroll_x, event.scroll_y).

Parameters

Name	Type	Description	Default
event	MouseEvent	The mouse event.	required

setup

App.setup()

Called once, after the window opens.

update

App.update()

Called every frame before draw.

window_resized

App.window_resized(w, h)

Called after the window is resized.

Parameters

Name	Type	Description	Default
w	int	New window width in points.	required
h	int	New window height in points.	required

run

run(
    app,
    width=1024,
    height=768,
    *,
    title='kiln',
    fullscreen=False,
    vsync=True,
    fps=None,
    frames=None,
    background=None,
    auto_clear=True,
    exit_on_escape=None,
)

Opens a window and runs app until the window closes.

Pressing ESC closes the window. app.exit() runs when the loop ends, including on an exception or Ctrl-C, and the window is always closed. Ctrl-C then prints one line to stderr and run returns, with no traceback; any other exception propagates.

Parameters

Name	Type	Description	Default
app	App	The sketch to run.	required
width	int	Window width in points (logical pixels).	1024
height	int	Window height in points (logical pixels).	768
title	str	Window title.	'kiln'
fullscreen	bool	Open fullscreen on the primary monitor.	False
vsync	bool	Synchronise buffer swaps with the display refresh.	True
fps	float | None	The target frame rate, kiln.clock.target_fps; 0 means no limit. None keeps the current target (none unless set before).	None
frames	int | None	Stop after this many frames (Kiln-specific; handy for scripts, demos and smoke tests). None runs until the window closes.	None
background	ColorLike | None	The colour of the automatic clear, kiln.window.background (any colour fill takes); None keeps the default, gray 60.	None
auto_clear	bool	Whether each frame starts with a clear to the background, kiln.window.auto_clear.	True
exit_on_escape	bool | None	Whether ESC closes the window, kiln.window.exit_on_escape; None keeps the current setting (on unless set before).	None

Each keyword (frames aside) is the starting value of the kiln.window or kiln.clock property of the same name, fps that of kiln.clock.target_fps; setup and later code change them through those properties: kiln.window.title = "...".

Raises

Name	Type	Description
	RuntimeError	No OpenGL 4.1 core context is available (no GUI session).