Toga Python GUI Toolkit

Toga widgets are composed of three distinct internal layers. Understanding these layers helps in understanding how Toga abstracts platform-specific complexities into a single, consistent API.

1. Interface Layer: The public API defined in toga-core. This is what you use to build your application. It handles input validation, persistent value storage, and style/layout attributes.
2. Implementation Layer: The platform-specific representation (e.g., toga-cocoa for macOS, toga-gtk for Linux). It provides a private utility API to the Interface layer. Every interface widget has exactly one implementation widget, though not all interface widgets are available on all platforms.
3. Native Layer: The actual system widgets provided by the underlying toolkit (e.g., Gtk.Button). An implementation might use a single native widget or multiple native widgets combined into a single "primary" native widget to satisfy the Toga interface.

In Toga, every drawing operation performed on a Canvas is represented by a DrawingAction object. Each drawing method (like line_to()) has a corresponding DrawingAction subclass (like LineTo).

The drawing context is managed via state objects, which are subclasses of BaseState. The simplest is State. A canvas starts with a single initial state accessible via canvas.root_state. Each state maintains a drawing_actions list containing the operations performed within that state.

Caution: While you can interact with these actions directly to retroactively alter or reorder them, doing so bypasses the canvas's internal management. Avoid mixing direct DrawingAction manipulation with the canvas's built-in context managers to prevent unintuitive results.

import toga

canvas = toga.Canvas()

print(canvas.root_state)
# State()
print(canvas.root_state.drawing_actions)
# []

canvas.rect(0, 0, 10, 10)
canvas.stroke()

print(canvas.root_state.drawing_actions)
# [Rect(x=0, y=0, width=10, height=10),
#  Stroke(stroke_style=None, line_width=None, line_dash=None)]

Toga is an evolving project. When designing your application, be aware that some common GUI widgets are currently partially implemented or planned for future release.

Mobile Platform Workarounds

On mobile platforms (iOS/Android), certain complex widgets do not have native equivalents. You may need to use alternative patterns:

• Tables: Instead of a native Table, use DetailedList. You can treat the title and subtitle as your primary columns, and use row selection to navigate to a sub-page containing the full row details.
• Trees: Similar to Tables, mobile platforms lack a native Tree widget. Consider using a list-based approach or a composite widget that combines table scrolling with tree functionality.

Planned Widgets

The following widgets are identified in the roadmap for future implementation:

• Inputs: RadioButton, ComboBox, ColorInput, SearchInput, and DateTimeInput.
• Views: VideoView and PDFView.
• Containers: FormContainer (for key/value layouts) and NavigationContainer (for hierarchical navigation with 'back' button support).