Programming an IcedApp¶

Overview¶

`IcedApp`()	An interactive application.
`Element`	A displayable widget that can be used in `view()`.
`Message`	A message generated through user interaction.
`Settings`()	(Immutable) settings of the `IcedApp` application.
`WindowSettings`()	(Immutable) settings of the `IcedApp` window.

Details¶

class pyiced.IcedApp¶

An interactive application.

An application can execute asynchronous actions by returning Commands in some of its methods. A debug view can be toggled by pressing F12.

background_color()¶

Returns the background color of the application. Defaults to white.

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[Iterable[Union[Awaitable[Optional[object]], object, None]]]

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[Any]], Union[None, Any, NoReturn]]]) – 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

settings: pyiced.Settings = <pyiced.Settings object>¶

The initial settings of the program.

Only queried once.

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. The method call be must executed quite fast. Long running tasks should be executed asynchronously.

Any Command returned will be executed immediately in the background.

Parameters

msg (Union[Message | object]) – A message to handle. Generated either through user iteraction, or though an (asynchronous) pyiced.Command.
clipboard (Clipboard) – The OS’s inter-application message buffer. Can only be interacted with during this call to update(). Accessing it later or in another thread may crash the application.

Returns

The update invocation may return a list of coroutines for asynchronous message handling, e.g. to open a socket.

Return type

Optional[Commands]

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¶: A displayable widget that can be used in view().

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

logo¶

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¶

(Immutable) settings of the IcedApp application.

antialiasing: bool = True¶

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.

default_font: pyiced.Font = Font.DEFAULT¶

The font that will be used by default.

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

default_text_size: int = 20¶: The text size that will be used by default.

exit_on_close_request: bool = True¶: Whether the IcedApp should exit when the user requests the window to close (e.g. the user presses the close button).

window: pyiced.WindowSettings = <pyiced.WindowSettings object>¶: The window settings.

class pyiced.WindowSettings¶

(Immutable) settings of the IcedApp window.

always_on_top: bool = False¶: Whether the window will always be on top of other windows.

decorations: bool = True¶: Whether the window should have a border, a title bar, etc. or not.

icon: Optional[pyiced.Icon] = <pyiced.Icon object>¶: TODO

max_size: Optional[Tuple[int, int]] = None¶: The maximum size of the window.

min_size: Optional[Tuple[int, int]] = None¶: The minimum size of the window.

resizable: bool = True¶: Whether the window should be resizable or not.

size: Tuple[int, int] = (1024, 768)¶: Initial dimensions of the newly crated window.

transparent: bool = False¶: Whether the window should be transparent.

Type aliases¶

pyiced.Command¶: alias of Union[Awaitable[Optional[object]], object]

pyiced.Commands¶: alias of Iterable[Optional[Union[Awaitable[Optional[object]], object]]]