tkmilan.mixin#

All the mixin classes, to be reused internally.

Functions

debuglog__state_set(widget)

Classes

`ContainerState`(swidgets, cwidgets, ...)	Full container state.
`ContainerWidget`(*[, gkeys])	Parent class of all containers.
`MenuWidget`(*[, gkeys])	Parent class of menu widgets
`MixinState`()	Mixin for all stateful widgets.
`MixinStateContainer`()	Mixin class for container widgets.
`MixinStateSingle`()	Mixin class for single widgets.
`MixinTraces`()	Mixin class for variable traces.
`MixinValidationSingle`()	Mixin class for widget validation, for single widgets.
`MixinWidget`(*[, gkeys])	Parent class of all widgets.
`ProxyWidget`(args, *kwargs)	Parent class of all proxy widgets.
`SingleWidget`(*[, gkeys])	Parent class of all single widgets.

class tkmilan.mixin.ContainerState(swidgets: Mapping[str, SingleWidget], cwidgets: Mapping[str, ContainerWidget | MenuWidget], variables: Mapping[str, Variable], wvariables: Mapping[str, Variable], vwidgets: Mapping[str, Sequence[str]], vid_upstream: Set[str], hswidgets: Set[SingleWidget], hcwidgets: Set[ContainerWidget])#

Bases: object

Full container state.

Parameters:

swidgets (Mapping[str, SingleWidget]) – Single Widgets
cwidgets (Mapping[str, ContainerWidget | MenuWidget]) – Container or Menu Widgets
variables (Mapping[str, Variable]) – Attached Variables
wvariables (Mapping[str, Variable]) – Mapping VariableID -> Variable object
vwidgets (Mapping[str, Sequence[str]]) – Mapping VariableID -> Widget Name list
vid_upstream (Set[str]) – Set of upstream VariableID
hswidgets (Set[SingleWidget]) – Helper Single Widgets. Technically not considered as “state”, only matters for tracing purposes. Includes widgets that might be ignored using ignoreContainerState, check this when using if this is not intended.
hcwidgets (Set[ContainerWidget]) – Helper Container Widgets. Technically not considered as “state”, only matters for tracing purposes.

class tkmilan.mixin.ContainerWidget(*, gkeys: Iterable[str] | None = None)#

Bases: MixinWidget, MixinStateContainer, MixinTraces

Parent class of all containers.

gvar(name: str) → Variable#

Get a variable attached to this container, by name.

Fails if it does not exist.

Parameters:: name (str) – The variable name to search for.

See also

var: Attach a non-Spec variable to this container, with a name.
varSpec: Attach a Spec variable to this container, with a name.

init_container(*args, layout: str | None = '', **kwargs) → None#

Setup all the container stuff.

Includes: - Variable settings - Sub-Widget settings - Layout - Traces (from MixinTraces) - Defaults

pad_container(pad: int, *, recursive: bool = True, _level: int = 0) → None#

Pad this container widget, recursively.

This requires more than a simple blind application of padding to all widgets. It will also take into account containers with a single widget, layout_padable (skipping unsupported containers), and proxy widgets. Guarantee the padding distance between widgets and the container is pad.

In particular, this will pad all widgets on the right/bottom, and also pad the left/top widgets on the left/top grid location, creating uniform padding in all directions.

The padding configuration will be applied recursively by default, see recursive to disable this.

Parameters:

pad (int) – The padding distance, in pixels. See above for details on how this applied.
recursive (bool) – Apply the same padding to child containers. Enabled by default.

See also

See RootWindow’ rpad for automatic application to all widgets, down from the root window.

pgrid(*children: None | str | MixinWidget, row: bool = True, column: bool = True, _internal: bool = False, sticky: None | CP | Sticky = None, **arguments: Any) → None#

Configure the grid rows and columns for the given widgets.

For widgets that span more than one row or column, the settings are changed for all rows or columns.

Parameters:

children (None | str | MixinWidget) – Widgets to consider. Accepts the widget objects, or strings (searches widgets for the corresponding object). Accepts and skips None values (useful for conditional widgets). All widgets must be direct children of this widget.
row (bool) – Configure the rows. Defaults to True.
column (bool) – Configure the columns. Defaults to True.
arguments (Any) – Arguments passed to the configuration functions: columnconfigure / rowconfigure.

Other arguments are passed to each individual widget, using cgrid:

Parameters:: sticky (None | CP | Sticky) – Configure the sticky grid settings. Accepts a CP object (see model.CP_S), or a model.Sticky directly. When set to None, nothing is changed. Defaults to None.

See also

See cgrid for a similar function that takes only the individual settings, and works on the widget itself.

Note

To configure only rows or columns, see pgrid_r and pgrid_c for a more ergonomic API. See also pgrid_all to act on all children.

Warning

Make sure to include proxied widgets as children (MixinWidget.wproxy), there is a warning on debug mode, but this might change in the future.

pgrid_all(**arguments: Any) → None#

Wraps pgrid, acting on all child widgets.

See pgrid.

pgrid_c(*children: str | MixinWidget, **arguments: Any) → None#

Wraps pgrid, acting only on columns.

See pgrid, sets only column to True.

pgrid_r(*children: str | MixinWidget, **arguments: Any) → None#

Wraps pgrid, acting only on rows.

See pgrid, sets only row to True.

set_gui_state(state: GuiState | None = None, _sub: bool = True, **kwargs) → GuiState#

Set GUI State for itself, and optionally, for all sub-widgets.

Warning

Don’t use this directly, unless you really know what you are doing.

Parameters:: _sub (bool) – Automatically run set_gui_substate with the same model.GuiState object. Defaults to True. Useful only for implementing special containers.

See also

MixinWidget.gstate: Property changed for all sub-widgets.

set_gui_substate(state: GuiState) → None#

Set GUI State for all sub-widgets.

Warning

Don’t use this directly, unless you really know what you are doing.

Note

To control the GUI subwidget handling, this function can be redefined (using extra care), using something like this:

def set_gui_substate(self, state: tkmilan.model.GuiState):
    if self.some_condition is True:
        # Manipulate the `model.GuiState` object
        state.enabled = False
    super().set_gui_substate(state)

See also

MixinWidget.gstate: Property changed for all sub-widgets.

setup_adefaults() → None#

Runs after all widgets are stable.

Avoid changing state on this function.

Note

Available for subclass redefinition.

See also

setup_defaults: Run code right after this widget is setup, before all widgets are stable.

setup_container_layout(olayout: str | None) → None#

“Internal” alternative to setup_layout.

This is mostly useful for complex widgets, to keep the convenience of the existing setup_layout call for the final instances, but allow for class-level adjustments.

This runs just before setup_layout.

Warning

Don’t use this directly, unless you know what you doing. Use setup_layout.

Parameters:: olayout (str | None) – This is string originally used for layout. See self.layout for the processed version.

Note

Available for subclass redefinition, mostly for complex widgets.

setup_defaults() → None#

Runs after the widget is completely setup.

Note this runs before the parent widget is complete ready.

Useful to set default values. Do not configure layout-related settings here, see setup_layout.

Note

Available for subclass redefinition.

See also

setup_adefaults: Run code after all widgets are stable (including parent widgets in the tree).

setup_gstate_valid(*, nowarn: bool = False, childMatch: Iterable[SingleWidget] = (), childSkip: Iterable[SingleWidget] = ()) → None#

Configure setting the model.GuiState valid parameter for this GUI.

Since this is still a “hack”, it’s not enabled automatically nor in a nice declarative way. This might interact with other features, it is only a preview for now.

This is not recursive, child containers DO NOT inherit this setting. There’s no support for child containers anyway, make sure to use this only for simple containers, no nesting.

To setup this, call this function inside the widgets’ setup_defaults function, before other widget state changes. This uses trace internally, so that’s another feature that might not work perfectly.

Use the nowarn parameter if you confirmed it works properly, to avoid a spurious warning. This is not the default, make sure you really test this properly.

Use the childMatch parameter to “tie” the container valid state to those child single widgets. This should include any child labels, that should be ignored when calculating the new state, but set with the container state. childSkip will avoid setting the state on those widgets.

Warning

This is not fully baked, but can be used carefully, with extra testing.

setup_layout(layout: str | None) → None#

Useful for manual adjustments to the automatic layout.

This runs after all automatic layout settings are configured.

Parameters:: layout (str | None) – This is the processed version of the layout string.

Note

Available for subclass redefinition.

setup_state(**kwargs) → Mapping[str, WidgetDynamicState]#

Define an object that will be cached forever.

This can have a static object, or a dynamic callable.

See MixinState.wstate_static, stateSetup.

setup_widgets(*args, **kwargs) → Mapping[str, MixinWidget] | None#

Define the sub widgets here.

Return a dict for a custom mapping, or None for automatic mapping.

trace(*args, trace_vupstream: Set[str] | None = None, **kwargs: Any) → str#

Trace the variable associated to the current widget.

The underlying function is tkmilan.var.trace, check it for more detailed documentation.

Parameters:

function – The callback function.
trace_name – A name for the trace reference. Must be unique for the widget. Optional, uses an automatic name otherwise.
kwargs (Any) – Passed to the tkmilan.var.trace function.

See also

Use atrace to combine a trace with a model.TimeoutIdle. Use tracev to consider the named container variable.

var(cls: Type[Variable], *, value: Any | None = None, name: str | None = None, vname: str | None = None) → Variable#

“Attach” a new variable to this container.

Parameters:

cls (Type[Variable]) – The variable class.
name (str | None) – The variable name, on the widget namespace. Optional, defaults to vname.
value (Any | None) – The default value. Optional, defaults to None.
vname (str | None) – The variable name, on the global namespace. Optional, defaults to an autogenerated name.

See also

varSpec: Attach a Spec variable to this container, with a name.
gvar: Access the variable by name.

Note

The vname is defined in a global namespace, common to the entire application. This can be used to define common variables across different widgets, but this is not default behaviour since it violates the principle of least surprise.

varSpec(cls: Type[Spec], spec: Any, *, name: str | None = None, vname: str | None = None) → Spec#

“Attach” a new specified variable to this container.

Parameters:

cls (Type[Spec]) – The variable class.
name (str | None) – The variable name, on the widget namespace. Optional, defaults to vname.
spec (Any) – The specification to creating the new variable.
vname (str | None) – The variable name, on the global namespace. Optional, defaults to an autogenerated name.

See also

var: Attach a non-Spec variable to this container, with a name.
gvar: Access the variable by name.

Note

widgets_class(*classes: Type[MixinWidget]) → Iterable[MixinWidget]#

Filter widgets by type.

Filter all child widgets by type. Very useful to apply settings to a subset of all child widgets.

Consider proxy widgets, do the right thing.

Parameters:: classes (Type[MixinWidget]) – Widget Types, as classes.

See also

See widgets_rclass to filter recursively. See widgets_except to reverse filter child widgets.

widgets_except(*widgets: str | MixinWidget) → Iterable[MixinWidget]#

Reverse-filter widgets by instance.

Filter all child widgets by inverting a given list, i.e. produce all other widgets. Supports strings. Very useful to apply settings to a subset of all child widgets.

Consider proxy widgets, do the right thing.

Parameters:: widgets (str | MixinWidget) – Skip these widget objects or strings (searches widgets for the corresponding object). All widgets must be direct children of this widget.

See also

See widgets_class to filter child widgets by class. See widgets_except for the direct filter.

widgets_only(*widgets: str | MixinWidget) → Iterable[MixinWidget]#

Filter widgets by name.

Filter all child widget by producing the given widgets. Supports strings.

Consider proxy widgets, do the right thing.

Parameters:: widgets (str | MixinWidget) – Include these widget objects or strings (searches widgets for the corresponding object). All widgets must be direct children of this widget.

See also

See widgets_except for the inverted filter.

Note

This seems worthless, but can be very useful to gather a list of child widgets when setup_widgets returns a mapping, just give the string keys.

widgets_rclass(*classes: Type[MixinWidget]) → Iterable[MixinWidget]#

Filter widgets by type, recursively.

Filter all child widgets by type, including children of child containers. Very useful to apply settings to a subset of all child widgets, on recursive containers.

Consider proxy widgets, do the right thing.

Parameters:: classes (Type[MixinWidget]) – Widget Types, as classes.

See also

See widgets_class to filter only for the current children.

wimage(key: str) → Image | None#

Wraper for RootWindow.wimage.

property gsize: GridSize#

GUI grid size (according to the current child widgets).

Follow MixinWidget.ignoreContainerLayout setting.

layout: str | None = ''#: Store the processed layout

layout_autoadjust: bool = False#

Should this container have its child widgets automatically adjusted, based on their types.

This adjusts child widgets based on its type in specific ways.

Currently implemented adjustments:

Separator: Set weight=0 to all rows/columns containing this type, based on its orientation.

Note

This has important performance implications, so it is disabled by default. The widgets that can be adjusted are flagged as a warning on debug mode, so they can be manually toggled.

layout_autogrow: bool = True#

Should this container have its child columns and rows grow automatically.

This is equivalent to configuring the grid with the option weight=1.

layout_autohide: bool = True#

Should this container have its child with ignoreContainerLayout removed from the grid.

Enabled by default, do not change this unless there are any problems.

layout_expand: bool = True#

Should this container expand to fill the space on the parent widget.

Note this affects the parent grid, not the child grid on this container.

layout_padable: bool = True#

Should this container’s children be automatically padded, when requested.

Most containers behave well when padding children, but some are problematic, mark those at class level (set layout_padable = False).

See ContainerWidget.pad_container.

widgets: Mapping[str, MixinWidget]#

Store mapping between widget name and widget object.

See setup_widgets.

class tkmilan.mixin.MenuWidget(*, gkeys: Iterable[str] | None = None)#

Bases: MixinWidget, MixinStateContainer, MixinTraces

Parent class of menu widgets

init_menu(cspec: Tuple[MenuElement, ...], *, pvariables: Mapping[str, Variable] | None = None)#

Setup all the menu stuff.

Includes: - Variable settings - Traces (from MixinTraces)

setup_state(**kwargs) → Mapping[str, WidgetDynamicState]#

Define an object that will be cached forever.

This can have a static object, or a dynamic callable.

See MixinState.wstate_static, stateSetup.

trace(*args, trace_vupstream: Set[str] | None = None, **kwargs: Any) → str#

Trace the variable associated to the current widget.

The underlying function is tkmilan.var.trace, check it for more detailed documentation.

Parameters:

function – The callback function.
trace_name – A name for the trace reference. Must be unique for the widget. Optional, uses an automatic name otherwise.
kwargs (Any) – Passed to the tkmilan.var.trace function.

See also

Use atrace to combine a trace with a model.TimeoutIdle. Use tracev to consider the named container variable.

wimage(key: str) → Image | None#

Wraper for RootWindow.wimage.

cspec: Tuple[MenuElement, ...]#: Store the children specification

class tkmilan.mixin.MixinState#

Bases: object

Mixin for all stateful widgets.

setup_state()#

Define an object that will be cached forever.

This can have a static object, or a dynamic callable.

See MixinState.wstate_static, stateSetup.

state_get(**kwargs)#

Define how to get the widget state.

The kwargs are only passed for Dynamic State widgets

state_set(state, substate: bool, **kwargs)#

Define how to set the widget state.

The kwargs are only passed for Dynamic State widgets

isNoneable: bool | None = None#

Define if a None result leads to skipping this widget on the state result.

This applies to both static and dynamic state calculations. Defaults to None, so that it can be overriden by subclasses.

For dynamic calculations, the results for some widgets might vary depending on where the root state starts, so they will be unpredictable. When the state is taken as a whole (the simple usage), it is predictable.

Note

The default None value for this variable is invalid. The subclass must define this.

property stateSetup#

Obtain the state setup.

This takes into account the wstate_static flag, producing a static object or a callable.

This should always be used, MixinState.setup_state is only a definition.

property wstate#: Widget State

wstate_static: bool = True#

Define if the MixinState.setup_state cache is static. or a callable for dynamic calculations.

See stateSetup.

class tkmilan.mixin.MixinStateContainer#

Bases: MixinState

Mixin class for container widgets.

To ignore a container state, define this on the subclass:

def setup_state(self, **kwargs):
    return {}

Note

When subclassing this, define MixinState.setup_state to return a dictionary mapping subwidget identifier to WidgetDynamicState.

state_get(*, vid_upstream: Set[str] | None = None, **kwargs) → Any#

Define how to get the widget state.

The kwargs are only passed for Dynamic State widgets

state_set(state, substate, *, vid_upstream: Set[str] | None = None, **kwargs) → None#

Define how to set the widget state.

The kwargs are only passed for Dynamic State widgets

wstate_menu: str | None = None#

Save the attached Menu state as a regular container element, with this key. When None, the state is not part of this container state.

This only makes sense for the RootWindow, other containers should not have child menus.

wstate_single: None | bool | str = None#

Mark the container state as “single”, including only the state for this child. The value should be a string indicating the state key.

True means the only existing key should be considered. This should be used only when the key name is dynamic and cannot be statically determined.

Should only be enabled where there is a single child element, this is verified when getting the value. Use MixinWidget.ignoreContainerState to ignore other widgets.

This creates no performance improvements, it is only useful to simplify the state.

Note

To skip the warning about a container with a single widget on debug binaries, mark the widget class with wstate_single = False. This works exactly as the default None, without the warning.

wstate_single_wstate: bool = False#

When the container state is “single”, particularly setting wstate_single=True, mark the state as correctly empty, so the parent function can turn a WState/WStateR into a single element.

Should only be enabled where wstate_single is set to True and there are no child elements, this is verified when getting the value.

wstate_static: bool = False#

Define if the MixinState.setup_state cache is static. or a callable for dynamic calculations.

See stateSetup.

class tkmilan.mixin.MixinStateSingle#

Bases: MixinState

Mixin class for single widgets.

Note

When subclassing this, define MixinState.setup_state to return the variable containing the widget state.

state_get(**kwargs)#

Define how to get the widget state.

The kwargs are only passed for Dynamic State widgets

state_set(state, substate: bool, **kwargs)#

Define how to set the widget state.

The kwargs are only passed for Dynamic State widgets

wstate_static: bool = True#

Define if the MixinState.setup_state cache is static. or a callable for dynamic calculations.

See stateSetup.

class tkmilan.mixin.MixinTraces#

Bases: object

Mixin class for variable traces.

atrace(function: Callable, **kwargs: Any) → str#

Trace the variable associated to the current widget, but run the callback when there’s nothing else to do.

This is an efficient way of combining trace with a model.TimeoutIdle. Useful if the tracing call runs too soon and needs to be delayed by the minimum amount of time possible.

Parameters:

function (Callable) – The callback function.
kwargs (Any) – Passed to trace function.

trace(function: Callable, *, trace_name: str | None = None, **kwargs: Any) → str#

Trace the variable associated to the current widget.

The underlying function is tkmilan.var.trace, check it for more detailed documentation.

Parameters:

function (Callable) – The callback function.
trace_name (str | None) – A name for the trace reference. Must be unique for the widget. Optional, uses an automatic name otherwise.
kwargs (Any) – Passed to the tkmilan.var.trace function.

See also

Use atrace to combine a trace with a model.TimeoutIdle. Use tracev to consider the named container variable.

tracev(vname: str, function: Callable, *, trace_name: str | None = None, **kwargs: Any) → str#

Trace the named variable attached to the current container widget.

The underlying function is tkmilan.var.trace, check it for more detailed documentation.

See also

Use trace to consider the current widget variable instead.

class tkmilan.mixin.MixinValidationSingle#

Bases: object

Mixin class for widget validation, for single widgets.

doValidation(n=None, i=None, t=None) → None#

Force widget Post-Validation.

Wraps the upstream function with optional arguments, to be used directly on trace, Binding, etc.

All arguments are ignored.

eSet(label: str) → Callable[[...], None]#

Return an event function to set the state a certain label.

Returns:: Return a function that can be attached to a Binding, trace, or even called directly.
Return type:: Callable[[…], None]

eSetValue(value: Any) → Callable[[...], None]#

Wraper for eSet, to set a value instead.

Requires the widget to have a specificed variable.

putTooltip(tooltipClass: Union[bool, Type[Tooltip]] = True, **tt_kwargs) → MixinValidationSingle#

Setup the tooltip object for the validation settings on itself.

This creates the Tooltip object according to the settings, attached to the current widget. See VSettings for tooltip related settings. The widget must setup the validation already, but must not define an existing tooltip object (parameter tt).

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).putTooltip(...)

This is usually called “method chaining”, or “fluent interface”.

Parameters:

tooltipClass (Union[bool, Type[Tooltip]]) –

The class to instance as the tooltip object. Must be a Tooltip, or True to use TooltipValidation.

Defaults to True.

All other keyword arguments are passed to the Tooltip creation.

Note

This is incompatible with attachTooltip, do not mix them on the same widget.

setDefault() → None#

Set the current state to the default label.

setup_validation(vstate: VState, vwhy: VWhy | None = None) → bool | None#

Define the “natural” widget validation, checking the state validation.

Some widgets might have a different “natural” widget validation function.

When this does not apply, use fn.validation_pass.

class tkmilan.mixin.MixinWidget(*, gkeys: Iterable[str] | None = None)#

Bases: object

Parent class of all widgets.

Parameters:: gkeys (Iterable[str] | None) – Append widget-specific model.GuiState keys to common list model.GUI_STATES_common.

_bindings: MutableMapping[str, Binding]#: Store all widget Binding objects, keyed by name (see binding).

_tidles: MutableMapping[str, TimeoutIdle]#: Store some widget TimeoutIdle objects, keyed by name (see tidle).

attachTooltip(tooltipClass: Optional[Type[Tooltip]] = None, **tt_kwargs)#

Setup a tooltip object for the current widget.

This creates a basic Tooltip object according to the given arguments, attached to the current widget. Saves the tooltip object in tt.

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).attachTooltip(...)

This is usually called “method chaining”, or “fluent interface”.

Parameters:

tooltipClass (Optional[Type[Tooltip]]) –

The class to instance as the tooltip object. Must be a Tooltip, or None to use TooltipSingleStatic.

Defaults to True.

All other keyword arguments are passed to the Tooltip creation.

Note

This is not to be confused with the validation tooltips, see putTooltip. This is incompatible with putTooltip, do not mix them on the same widget.

binding(sequence: str, *args, key: str | None = None, immediate: bool = True, **kwargs) → Binding#

Create a model.Binding for this widget.

Stores all widget bindings on a per-instance dictionary, for later usage. Note that all dictionary keys must be different. For the same bindings on a single widget, this requires passing the key argument.

See the Tk bind documentation.

Parameters:

key (str | None) – Optional. Defaults to the sequence itself. Useful to support multiple bindings on the same sequence.
immediate (bool) – Passed to the upstream object, default to enabling the binding on creation. This is the opposite from upstream.

All other arguments are passed to the model.Binding object.

cgrid(*, sticky: Sticky, **kwargs) → None#

Configure parent widget grid settings.

There is no Python documentation, see Tk grid configure documentation.

Parameters:: sticky (Sticky) – Configure the sticky grid settings.

All other arguments are passed to the upstream grid function.

See also

See pgrid for a simular function that works on the parent container widget.

Note

This function can replace:

w.grid(sticky=tkmilan.tk.NSEW)

with:

w.cgrid(sticky=tkmilan.S.ALL)

galternate_toggle(_arg1: Any | None = None, _arg2: Any | None = None, _arg3: Any | None = None)#

Toggle the alternate model.GuiState state, if available.

Equivalent to self.alternate = model.GuiState(enabled=not self.gstate.alternate).

For performance reasons, the validation for alternate state is only done on debug mode.

Parameters:

_arg1 (Any | None) – Unused, included for API compatibility with Tk events
_arg2 (Any | None) – Unused, included for API compatibility with Tk traces
_arg3 (Any | None) – Unused, included for API compatibility with Tk event loop.

genabled(state: bool | None)#

Manipulate the GuiState enabled state.

Equivalent to self.gstate = model.GuiState(enabled=state).

Parameters:: state (bool | None) – The enabled state.

genabled_toggle(_arg1: Any | None = None, _arg2: Any | None = None, _arg3: Any | None = None)#

Toggle the GuiState enabled state.

Equivalent to self.gstate = model.GuiState(enabled=not self.gstate.enabled).

Parameters:

_arg1 (Any | None) – Unused, included for API compatibility with Tk events
_arg2 (Any | None) – Unused, included for API compatibility with Tk traces
_arg3 (Any | None) – Unused, included for API compatibility with Tk event loop.

putAuto(value: bool | None = False) → MixinWidget#

Set the isAuto marker on itself.

See MixinWidget.isAuto for more information on the possible values. Defaults to False.

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).putAuto()      # No GUI  No State
    self.w1 = Widget(self, ...).putAuto(None)  # No GUI Yes State

This is usually called “method chaining”, or “fluent interface”.

putHelper(value: bool = True) → MixinWidget#

DEPRECATED. See putAuto.

putIgnoreLayout(value: bool = True) → MixinWidget#

Set the ignoreContainerLayout marker on itself.

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).putIgnoreLayout()

This is usually called “method chaining”, or “fluent interface”.

putIgnoreState(value: bool = True) → MixinWidget#

Set the ignoreContainerState marker on itself.

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).putIgnoreState()

This is usually called “method chaining”, or “fluent interface”.

putIgnoreTrace(value: bool = True) → MixinWidget#

Set the ignoreContainerTrace marker on itself.

This is designed to be used inside the setup_widgets function, like this:

def setup_widgets(self, ...):
    self.w1 = Widget(self, ...).putIgnoreTrace()

This is usually called “method chaining”, or “fluent interface”.

setup_grid(fmt: str | GridCoordinates, **kwargs) → None#

Configure the grid for the current widget.

fmt can be given as a model.GridCoordinates, or as a single str, to be parsed by model.GridCoordinates.parse.

Parameters:

fmt (str | GridCoordinates) – The grid configuration format. Specified above.
kwargs – Passed upstream

See also

wgrid: Get the current widget grid coordinates.

tidle(action: Callable, *args, key: str | None = None, **kwargs) → TimeoutIdle#

Create a model.TimeoutIdle for this widget.

Stores all idle timeouts created using this function on a per-instance dictionary, for later usage. If the action is not a “real” function, this requires passing the key argument.

Parameters:: key (str | None) – Optional. Defaults to the action name.

All other arguments are passed to model.TimeoutIdle object.

wgeometry(*, size: bool = True, s_requested: bool = False) → WidgetGeometry#

Get the widget geometry information.

Parameters:

size (bool) – Consider the widget size, width and height. Considered by default.
s_requested (bool) – When calculating the size, use the requested size. Unset by default.

Returns:

Return a model.WidgetGeometry object with the widget information.

Return type:

WidgetGeometry

wroot_search() → RootWindow#

Alternative to wroot that crawls the widget tree.

Use the wparent proprety.

See also

wroot: Simpler alternative to this function, crawling the widget tree. Requires all widgets to be stable.

wsize(*, requested: bool = False) → PixelSize#

Get the widget size.

Each widget has several “sizes”.

The default is the actual size. This is the current size of the widget. Note that this size can be 1 pixel for height and width, when the widget is first created (see “requested size” for an alternative).
The requested size (controlled by requested) is the “natural” size of the widget, requested to the window manager. This should be stable, but it might not be the real size. It is available as soon as the widget is created.

See upstream winfo documentation.

Parameters:: requested (bool) – When calculating the size, use the requested size. Unset by default.
Returns:: Return a model.PixelSize object with the widget size.
Return type:: PixelSize

gkeys: FrozenSet[str]#: The supported model.GuiState keys.

property gstate: GuiState#: GUI State

ignoreContainerLayout: bool = False#: Ignore this widget when performing automatic layout.

See also

See putIgnoreLayout for an ergonomic way to set this on child widgets.

ignoreContainerState: bool = False#: Ignore this widget’s state when included on a container.

See also

See putIgnoreState for an ergonomic way to set this on child widgets.

ignoreContainerTrace: bool = False#: When this widget is included on a container, do not consider it for tracing purposes.

See also

See putIgnoreTrace for an ergonomic way to set this on child widgets.

isAuto: bool | None#

Marker that tracks the automatic state setup.

One of the following values:

True: Include on automatic widget and GUI states. Default.
False: No automatic widget state, but keep in on the GUI state. This makes the widget stateless, but it still participates in the automatic GUI state changes. Very useful for helper containers.
None: No automatic widget nor GUI states. This makes the widget basically invisible.

Note

This was called isHelper in older versions. Turn all isHelper=False into isAuto=False (unless you have a good reason to isolate GUI state).

See also

See putAuto for an ergonomic way to set this on child widgets.

proxee: Optional[MixinWidget] = None#: Link to the corresponding proxied widget, if exists.

See also

The base ProxyWidget class.

property size_screen: PixelSize#

The screen size.

This is a global property, but it’s available in every widget.

property size_vroot: PixelSize#

The VirtualRoot size.

This is a global property, but it’s available in every widget.

styleID: str | None = None#: StyleID for this widget. See RootWindow.styleIDs.

tt: Optional[Tooltip] = None#

The simply attached tooltip.

It is possible to attach multiple tooltips, but that is usually rare. This should only be modified by the attachTooltip function.

See also

The related attachTooltip function.

property wgrid: GridCoordinates | None#

Get the widget grid coordinates, if the widget is visible.

Returns:

Return a model.GridCoordinates object with the widget information. If the wiget was hidden, return None.

This is also available for the root widget (wroot) for completeness, but that doesn’t really correspond to any grid, return None.

This is also available for SecondaryWindow widgets, but it does not support any kind of grid, return None.

See also

setup_grid: Change the widget grid coordinates.

wparent: Optional[MixinWidget] = None#: A reference to the parent widget.

wproxy: Optional[MixinWidget] = None#: Link to the corresponding proxy widget, if exists.

See also

The base ProxyWidget class.

property wroot: RootWindow#

Get the root widget, directly.

Does not use the wparent property to crawl the widget tree to the top, so that it might be called before that setup is done (during setup of lower widgets, for example).

property wview: WidgetView | None#

Get the widget view information.

Returns:: Return a model.WidgetView object with the view information, if the widget supports scrolling in at least one axis. If the widget does not support scrolling, returns None.

class tkmilan.mixin.ProxyWidget(*args, **kwargs)#

Bases: SingleWidget

Parent class of all proxy widgets. Special case of SingleWidget.

This is implemented as a class initializer that sets up the wproxy/proxee references, and returns the child instance.

Note that creating an instance of this type will return the child widget instance, not the proxy object. The rest of the library is aware of this. The ProxyWidget object is available on the wproxy value.

Note

When implementing subclasses, take care not to alias any children argument with proxy arguments. Use a per-class prefix, or proxy prefix for common arguments. See ScrolledWidget for an example (note scroll*` and ``proxyStyleID arguments).

See also

Check the Python documentation for the difference between object.__new__ and object.__init__.

class tkmilan.mixin.SingleWidget(*, gkeys: Iterable[str] | None = None)#

Bases: MixinWidget, MixinStateSingle, MixinTraces

Parent class of all single widgets.

init_single(vspec: None | Variable | VSpec = None, gkeys: Iterable[str] | None = None) → None#

Setup all single widget stuff.

Includes:

Variable settings (Supports creating new variables)
tkmilan.mixin.MixinState.isNoneable calculation

setup_state()#

Define an object that will be cached forever.

This can have a static object, or a dynamic callable.

See MixinState.wstate_static, stateSetup.

wimage(key: str) → Image | None#

Wraper for RootWindow.wimage.

layout_padable: bool = True#

Should this widget be automatically padded, when requested.

See ContainerWidget.pad_container.