Module vpe.ui

User interface components.

This is still being developed. The API and behaviour is likely to change.

BoolField

class vpe.ui.BoolField(...)
BoolField(
    *,
    lidx,
    cidx,
    prefix='',
    suffix='',
    prefix_width=0,
    suffix_width=0,
    value_width=6,
    opt_var=None,
    **kwargs)

A field displaying a boolean value.

Methods

increment(_step: int)bool

Increment this field’s value by a given step.

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

fields

The fields within this panel. A mapping from name to Field.

first_field_idx

The global index of the first field in this panel.

selectable_fields

A mapping from global field index to Field instance.

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.

CurPrev

class vpe.ui.CurPrev(value)

An value that knows its previous value.

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_rangeTuple[int, int]

The range of columns occupied by this field.

property full_widthint

The full width occupied by this field.

property prefix_fmt_widthint

The width of this field’s formatted prefix.

property suffix_fmt_widthint

The width of this field’s formatted suffix.

property val_extentTuple[int, int]

The extent of this field’s value.

Returns

A tuple of cnum, width.

property valuetyping.Any

The field’s current value.

property value_fmt_widthint

The width of this field’s formatted value.

property value_str

Format the value as a string.

property value_widthint

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.

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.