Module vpe.ui¶
User interface components.
This is still being developed. The API and behaviour is likely to change.
BoolField¶
ChoiceField¶
-
class
vpe.ui.
ChoiceField
(values=(), opt_var=None, **kwargs)¶ A field holding one of a list of choices.
Parameters
- values
A sequence of permitted values for the field.
Attributes
-
values
¶ A sequence of permitted values for the field.
Methods
-
increment
(step: int)¶ Increment this field’s value by a given step.
ConfigPanel¶
-
class
vpe.ui.
ConfigPanel
(fields)¶ A panel that displays configuration values.
Parameters
- fields
The fields within this panel. A mapping from name to
Field
.
Attributes
Methods
-
apply_syntax
()¶ Apply syntax highlighting for this panel.
This is only called when the panel’s
start_lidx
is correctly set.
-
get_field_by_idx
(index: int)¶ Get the editable field with a given index.
-
index_fields
(start_idx: int)¶ Set up the mapping from field index to field.
-
on_format_contents
()¶ Refresh to formatted lines for this panel.
-
select_field
(index: int)¶ Select a specific field.
ConfigPanelBuffer¶
-
class
vpe.ui.
ConfigPanelBuffer
(*args, **kwargs)¶ A
PanelViewBuffer
thats supports configuration panels.This tracks instances of
ConfigPanel
and sets up key mappings to navigate and modify the fields within them.Methods
-
config_panels
() → Iterator[ConfigPanel]¶ Interate over all the configuration panels.
-
edit_field
()¶ Allow the user to edit the value of a field.
-
get_field_by_idx
(index: int)¶ Get the editable field with a given index.
-
inc_field
(step: int)¶ Increment the value in a field.
Parameters
- step: int
Value to change the field by. May be a negative value.
-
move_field
(step: int = 0)¶ Move to a different field.
Parameters
- step: int
Increment for the field index.
-
on_change
()¶ Perform common processing when value is changed.
This is intended to be over-ridden by subclasses.
-
on_reindex
()¶ Perform special processing when line reindexing has occurred.
-
on_selected_field_change
()¶ Perform common processing when the selecetd field is changed.
This is intended to be over-ridden by subclasses.
-
on_updates_applied
(changes_occurred: bool)¶ Perform special processing when buffer has been refreshed.
When this is invoked, this buffer may not be in the active window and my even be hidden.
-
Field¶
-
class
vpe.ui.
Field
(...)¶ Field( *, lidx, cidx, prefix='', suffix='', prefix_width=0, suffix_width=0, value_width=6, opt_var=None, **kwargs)
Base class for a field within a
ConfigPanel
.A field consists of 3 parts; prefix, value and suffix. They are laid out like this (in this example the prefix and value are left justified and the suffix is right justified).
| prefix value suffix | : :: :: : | : :: :<---------> suffix_fmt_width | <---------->: : : prefix_fmt_width | : <--------> : val_extent[1] / value_width | <-------------------------------> full_width ^ ^ ^ : : `-------------------- val_extent[0] : `-------------------------------- cidx `---------------------------------------- <buffer column zero>
Note that full_width == prefix_fmt_width + value_width + suffix_fmt_width.
Parameters
- lidx
The line index within the panel.
- cidx
The column index within the panel.
- prefix
The label displayed before the field.
- suffix
The label displayed after the field.
- prefix_width
The width spec for the prefix. If not provided then this defaults to the width of the prefix + 1. If set to a negative number, the prefix is right justified.
- suffix_width
The width spec for the prefix. It follows the same pattern as the prefix_width.
- value_width
The width spec for the value. It follows the same pattern as the prefix_width.
Attributes
-
cidx
¶ The column index within the panel.
-
lidx
¶ The line index within the panel.
-
prefix
¶ The label displayed before the field.
-
prefix_width
¶ The width spec for the prefix. If not provided then this defaults to the width of the prefix + 1. If set to a negative number, the prefix is right justified.
-
suffix
¶ The label displayed after the field.
-
suffix_width
¶ The width spec for the prefix. It follows the same pattern as the prefix_width.
Properties
-
property
column_range
→ Tuple[int, int]¶ The range of columns occupied by this field.
-
property
full_width
→ int¶ The full width occupied by this field.
-
property
prefix_fmt_width
→ int¶ The width of this field’s formatted prefix.
-
property
suffix_fmt_width
→ int¶ The width of this field’s formatted suffix.
-
property
val_extent
→ Tuple[int, int]¶ The extent of this field’s value.
- Returns
A tuple of cnum, width.
-
property
value
→ typing.Any¶ The field’s current value.
-
property
value_fmt_width
→ int¶ The width of this field’s formatted value.
-
property
value_str
¶ Format the value as a string.
-
property
value_width
→ int¶ The width used to display the field’s value.
Methods
-
text
() → str¶ Format the full text of the field.
Static methods
-
static
edit_value
() → bool¶ Allow the user to edit the value of a field.
This typically needs to be over-ridden by subclasses.
Return value
True if the value was modified.
-
static
increment
(_step: int) → bool¶ Increment this field’s value by a given step.
This typically needs to be over-ridden by subclasses.
Return value
True if the value was modified.
FieldVar¶
-
class
vpe.ui.
FieldVar
(_var)¶ A value that is displayed by a Field.
This class defines the protocol that a
Field
uses to access its underlying value.Properties
-
property
value
¶ “The current value for this variable.
Methods
-
__init__
(_var)¶ Initialisation.
-
set
(value: typing.Any) → str¶ Try to set this option’s value.
Return value
A string describing why the attempt failed. An empty string if the value was set. This basic wrapper always returns an empty string.
-
values
() → List[typing.Any]¶ Return a set of the valid values for this field.
Return value
A list of the valid values. An empty list means that this field’s range of values is not defined using a set.
-
property
IntField¶
-
class
vpe.ui.
IntField
(...)¶ IntField( *, lidx, cidx, prefix='', suffix='', prefix_width=0, suffix_width=0, value_width=6, opt_var=None, **kwargs)
A field displaying an integer value.
Methods
-
edit_value
() → bool¶ Allow the user to edit the value of a field.
Return value
True if the value was modified.
-
format_str¶
-
vpe.ui.
format_str
(s: str, width: int) → str¶ Format a string within a given field width.
The string is truncated (if necessary) to the width and then left or right justified within the width. A width of zero results in an empty string.
Parameters
- s: str
The string to justify.
- width: int
The field width. Postive values mean left justified, negative mean right justified.