Programming an IcedApp

Overview

IcedApp()

Element

Message

A message generated through user interaction.

Settings()

WindowSettings()

Details

class pyiced.IcedApp
background_color()

Returns the background color of the application.

Return type

Optional[Color]

fullscreen()

True if the program should run in fullscreen mode.

The runtime will automatically transition your application if a new mode is returned.

Return type

bool

new()

Initialize the application.

You can return Commands if you need to perform some async action in the background on startup. This is useful if you want to load state from a file, perform an initial HTTP request, etc.

Return type

Optional[NewType()(Commands, Iterable[Optional[NewType()(Command, Union[Awaitable[Optional[object]], object])]])]

run(*, run=None)

Runs the application.

This method will take control of the current thread and will NOT return unless there is an error during startup.

It should probably be that last thing you call in your main function.

Parameters

run (Optional[Callable[[Awaitable], None]]) – Coroutine executor. Defaults to asyncio.run().

Return type

NoReturn

scale_factor()

Returns the scale factor of the application.

It can be used to dynamically control the size of the UI at runtime (i.e. zooming).

For instance, a scale factor of 2.0 will make widgets twice as big, while a scale factor of 0.5 will shrink them to half their size.

Return type

float

property settings: Optional[pyiced.Settings]

The initial settings of the program.

Once queried once.

Return type

Optional[Settings]

should_exit()

Returns whether the application should be terminated.

This will kill the Python instance, too.

Return type

bool

subscriptions()

Returns the event subscriptions for the current state of the application.

A subscription will be kept alive as long as you keep returning it, and the messages produced will be handled by update.

Return type

Optional[Iterable[Optional[Subscription]]]

title()

The current title of the application.

This title can be dynamic! The runtime will automatically update the title of your application when necessary.

Return type

str

update(msg, clipboard)

Handles a message and updates the state of the application.

This is where you define your update logic. All the messages, produced by either user interactions or commands, will be handled by this method.

Any Command returned will be executed immediately in the background.

Return type

Optional[NewType()(Commands, Iterable[Optional[NewType()(Command, Union[Awaitable[Optional[object]], object])]])]

abstract view()

Returns the widget to display in the application.

These widgets can produce messages based on user interaction.

Return type

Element

class pyiced.Element
class pyiced.Message

A message generated through user interaction.

Messages get passed to to update().

alt

The alt key was pressed / released.

Returns

  • True – Yes, the alt key was pressed or released.

  • False – No, the state of the alt key is unchanged.

  • None – Not a “keypress”, “keyrelease” or “modifierschanged” event.

Return type

Optional[bool]

amount

The scroll movement.

Returns

The horizontal and vertical amount. The unit can be determined by inspecting wheelscrolled.

None if not a scroll movement.

Return type

Optional[tuple[float, float]]

button

The button of a mouse event.

Returns

  • “left” – The left mouse button.

  • ”right” – The right mouse button.

  • ”middle” – The middle (wheel) button.

  • int – Another button.

  • None – Not a mouse event.

Return type

Union[str|int|None]

characterreceived

A unicode character was received.

Returns

The received, composed character. None if not a character event.

Return type

Optional[str]

control

The control key was pressed / released.

Returns

  • True – Yes, the control key was pressed or released.

  • False – No, the state of the control key is unchanged.

  • None – Not a “keypress”, “keyrelease” or “modifierschanged” event.

Return type

Optional[bool]

cursormoved

The mouse cursor was moved

Returns

Horizontal and vertical pixels, or None if cursor was not moved.

Return type

Optional[tuple[float, float]]

file

The path of the hovering or dropped file.

Returns

The path or none, if the Message is not a file action.

Return type

Optional[pathlib.Path]

finger

A unique identifier representing a finger on a touch interaction.

Returns

Identifier of the finger.

Return type

int

key_code

The name of the pressed or released key.

See iced_native::keyboard::KeyCode for the name of the keys.

Returns

The name of the key, or None if the not a key press or release.

Return type

Optional[str]

keyboard

The kind of the keyboard interaction.

Returns

  • None if not a Message(native="keyboard") interaction

  • ”keypressed” when a key was pushed down

  • ”keyreleased” when a key no more pushed down

  • ”characterreceived” when a key press + release generated a character

  • ”modifierschanged” when a modifier was pressed or released, e.g. shift

Return type

Optional[str]

kind

The kind of the native message.

Returns

  • “mouse” for mouse interactions, e.g. mouse clicking

  • ”window” for window interactions, e.g. resizing

  • ”keyboard” for keyboard interactions, e.g. key presses

  • ”touch” for touch interactions (impossible?)

Return type

str

The “logo” key was pressed / released.

The logo key is the windows key, command key, etc.

Returns

  • True – Yes, the “logo” key was pressed or released.

  • False – No, the state of the “logo” key is unchanged.

  • None – Not a “keypress”, “keyrelease” or “modifierschanged” event.

Return type

Optional[bool]

mouse

A mouse event.

Returns

  • “cursorentered” – The mouse cursor entered the window.

  • ”cursorleft” – The mouse cursor left the window.

  • ”cursormoved” – The mouse cursor was moved

  • ”buttonpressed” – A mouse button was pressed.

  • ”buttonreleased” – A mouse button was released.

  • ”wheelscrolled” – The mouse wheel was scrolled.

  • None – Not a mouse event.

Return type

Optional[str]

position

A 2D point for the touch interaction.

Returns

A 2D point

Return type

tuple[float, float]

resized

The new size of the window.

Returns

The width and height in pixels or null, if it’s not a resize action.

Return type

Optional[tuple(int, int)]

shift

The shift key was pressed / released.

Returns

  • True – Yes, the shift key was pressed or released.

  • False – No, the state of the shift key is unchanged.

  • None – Not a “keypress”, “keyrelease” or “modifierschanged” event.

Return type

Optional[bool]

touch

A touch interaction.

Returns

  • “fingerpressed” – A touch interaction was started.

  • ”fingermoved” – An on-going touch interaction was moved.

  • ”fingerlifted” – A touch interaction was ended.

  • ”fingerlost” – A touch interaction was canceled.

  • None – Not a touch interaction.

Return type

Optional[str]

wheelscrolled

The unit of the scroll movement.

Returns

  • “lines” – Counting in lines / columns.

  • ”pixels” – Counting in pixels.

  • None – Not a scroll movement.

Return type

Optional[str]

window

The kind of the window message.

Returns

  • “resized” – The window was resized.

  • ”closerequested” – The window close button was clicked.

  • ”focused” – The window was focus.

  • ”unfocused” – The focus left the window.

  • ”filehovered” – A file is hovering the window. A selection of multiple files cause multiple messages.

  • ”filedropped” – A file was dropped on the window. A selection of multiple files cause multiple messages.

  • ”fileshoveredleft” – The cursor the with hovering file(s) left the window.

  • None – Not a window message.

Return type

Optional[str]

class pyiced.Settings
property antialiasing: bool

If set to true, the renderer will try to perform antialiasing for some primitives.

Enabling it can produce a smoother result in some widgets, like the Canvas, at a performance cost.

Return type

bool

property default_font: Optional[pyiced.Font]

The font that will be used by default.

If None or Font.DEFAULT is provided, a default system font will be chosen.

Return type

Optional[Font]

property default_text_size: int

The text size that will be used by default.

Return type

int

property exit_on_close_request: bool

Whether the IcedApp should exit when the user requests the window to close (e.g. the user presses the close button).

Return type

bool

property window: Optional[pyiced.WindowSettings]

The window settings.

Return type

Optional[WindowSettings]

class pyiced.WindowSettings
property always_on_top: bool

Whether the window will always be on top of other windows.

Return type

bool

property decorations: bool

Whether the window should have a border, a title bar, etc. or not.

Return type

bool

property max_size: Optional[Tuple[int, int]]

The maximum size of the window.

Return type

Optional[Tuple[int, int]]

property min_size: Optional[Tuple[int, int]]

The minimum size of the window.

Return type

Optional[Tuple[int, int]]

property resizable: bool

Whether the window should be resizable or not.

Return type

bool

property size: Tuple[int, int]

Dimensions of the newly crated window.

Return type

Tuple[int, int]

property transparent: bool

Whether the window should be transparent.

Return type

bool

Type aliases

pyiced.Command

Union[Awaitable[Optional[object]] | object]

pyiced.Commands

Iterable[Optional[Command]]