API documentation (autogenerated)

ascii_designer package

From ascii_designer you can directly import:

• The AutoFrame class
• The set_toolkit function.

ascii_designer.autoframe module

Warning

module ‘ascii_designer.autoframe’ undocumented

class ascii_designer.autoframe.AutoFrame

class name is converted to title. Override with f_title.

Body definition with f_body.

To create own widgets or customize the autocreated ones, override f_build.

Get at the created controls using AutoFrame[key].

close(), exit(), quit() provided for convenience.

Functions with same name as a control are autobound to the default handler (click or changed).

Attributes are autobound to the control value (get/set), except if they are explicitly overwritten.

close()

Close the window.

This is also called when the window is closed using the x button. Be sure to call super().close() or your window won’t close.

exit()

f_add_widgets(parent, sliced_grid=None, body=None, offset_row=0, offset_col=0, autoframe=None)

f_build(parent, body=None)

f_build_menu(parent, menu=None)

Builds the menu from the given menu definition.

Menu definition is a list which can (currently) contain actions and submenus.

An Action is simply a string, which is converted to an identifier following the same rules as the other widgets. It triggers the self. method named as the identifier. The method must be defined.

A submenu is created by a string ending in “>”, followed by an item which is itself a list (the submenu content).

Example

>>> menu = [
        'File >', ['Open', 'Save', 'Quit'],
        'Help >', ['About'],
    ]
>>> autoframe.f_build_menu(autoframe.f_controls(''), menu)

f_show()

Bring the frame on the screen.

quit()

ascii_designer.ascii_slice module

Functions to slice up a fixed-column-width ASCII grid.

slice_grid splits up lines according to a header row with | separators.

merged_cells iterates over this grid and returns merge areas.

Columns are merged if there is something different from | or space below the separator in the header row.

Rows are merged by prefixing the cells with {. The symbols must be in the same text column.

ascii_designer.ascii_slice.slice_grid(grid_text)

slice a grid up by the first (nonempty) row.

Before slicing, empty lines before/after are removed, and the text is dedented.

The first row is split by | characters. The first column can contain a | character or not.

Returns a SlicedGrid with Properties:

• column_heads: the split up parts of the first line (not including the separators).
• body_lines: list of following lines; each item is a list of strings, where each string is the grid “cell” including the preceding separator column. I.e. if you join the cell list without separator, you regain the text line.

class ascii_designer.ascii_slice.SlicedGrid(column_heads=NOTHING, body_lines=NOTHING)

Warning

class ‘ascii_designer.ascii_slice.SlicedGrid’ undocumented

ascii_designer.ascii_slice.merged_cells(sliced_grid)

Generator: takes the sliced grid, and returns merged cells one by one.

Cells are merged by the following logic:

• If the first character of a (stripped) cell is ‘{‘, cells of the following row(s) are merged while they also start with ‘{‘ in the same column.
• Then, columns are merged if the following (column’s) cell starts neither with space nor with ‘|’.

Yields MCell instances with:

• row, col: cell position (int, 0-based)
• rowspan, colspan: spanned rows/cols, at least 1
• text: merged area text, as sliced out from the text editor; not including the leading ‘{‘; “ragged” linebreaks retained.

Iteration order is row-wise.

Merge areas must not overlap. (However this should rarely happen on accident).

Note: If you need two row-merge ranges above each other, indent the ‘{‘ differently.

class ascii_designer.ascii_slice.MCell(row, col, text='', rowspan=1, colspan=1)

Warning

class ‘ascii_designer.ascii_slice.MCell’ undocumented

ascii_designer.toolkit module

Warning

module ‘ascii_designer.toolkit’ undocumented

ascii_designer.toolkit.set_toolkit(toolkit_name)

Warning

function ‘ascii_designer.toolkit.set_toolkit’ undocumented

ascii_designer.toolkit.get_toolkit()

Warning

function ‘ascii_designer.toolkit.get_toolkit’ undocumented

class ascii_designer.toolkit.ToolkitBase

Warning

class ‘ascii_designer.toolkit.ToolkitBase’ undocumented

anchor(widget, left=True, right=True, top=True, bottom=True)

anchor the widget. Depending on the anchors, widget will be left-, right-, center-aligned or stretched.

box(parent, id=None, text='', given_id='')

An empty panel (frame, widget, however you call it) or group box that you can fill with own widgets.

given_id is the user-given id value, as opposed to id (the autogenerated one). A Group box is created if text AND given_id are set.

The virtual attribute value is the panel itself, or in case of groupbox the contained panel.

button(parent, id=None, text='')

checkbox(parent, id=None, text='', checked=None)

Checkbox

close(frame)

close the frame

col_stretch(container, col, proportion)

set the given col to stretch according to the proportion.

combo(parent, id=None, text='', values=None)

combo box; values is the raw string between the parens. Free-text allowed.

connect(widget, function)

bind the widget’s default event to function.

Default event is:

• click() for a button

• value_changed(new_value) for value-type controls;

  usually fired after focus-lost or Return-press.

default_shortcuts = {'copy': 'C-C', 'cut': 'C-X', 'find': 'C-F', 'new': 'C-N', 'open': 'C-O', 'paste': 'C-P', 'redo': 'C-S-Z', 'refresh': 'F5', 'save': 'C-S', 'undo': 'C-Z'}

dropdown(parent, id=None, text='', values=None)

dropdown box; values is the raw string between the parens. Only preset choices allowed.

getval(widget)

get python-type value from widget.

grammar = [('box', '\\<(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*\\>', '"<Text>"'), ('option', '\\((?P<checked> |x)\\)\\s+(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*$', '"( ) text" or "(x) text"'), ('checkbox', '\\[(?P<checked> |x)\\]\\s+(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*$', '"[ ] Text" or "[x] Text"'), ('slider', '\\[\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:\\s*(?P<min>\\d+)\\s*\\-\\+\\-\\s*(?P<max>\\d+)\\s*\\]', '[id: 0 -+- 100]'), ('multiline', '\\[(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*__\\s*\\]', '"[Text__]"'), ('textbox', '\\[(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*_\\s*\\]', '"[Text_]"'), ('treelist', '\\[\\s*=(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*(?:\\((?P<columns>.*?)\\))?\\s*\\]', '"[= Text]" or [= Text (column1, column2, ..)]'), ('combo', '\\[(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*_\\s*(?:\\((?P<values>.*?)\\))?\\s+v\\s*\\]', '"[Text_ v]" or "[Text_ (val1, val2, ...) v]'), ('dropdown', '\\[(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*(?:\\((?P<values>.*?)\\))?\\s+v\\s*\\]', '"[Text v]" or "[Text (val1, val2, ...) v]'), ('button', '\\[(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*\\]', '"[Text]"'), ('label', '(?P<id>)(?:\\.)?(?P<text>.+?)$', '"Text" or ".Text"')]

label(parent, id=None, label_id=None, text='')

menu_command(parent, id, text, shortcut, handler)

Append command labeled text to menu parent.

Handler: func() -> None, is immediately connected.

shortcut follows the syntax (modifier)-(key), where modifier is one or more of C, S, A for Ctrl, Shift, Alt respectively.

menu_grammar = [('sub', '(?:\\s*(?P<id>[a-zA-Z0-9_]+)\\s*\\:)?\\s*(?P<text>[^(]*?)?\\s*>', '"text >"'), ('command', '(?ix)\\s*\n (?P<id>[a-zA-Z0-9_]+\\s*\\:)?\n (?P<text>[^#]+)\n (?:\\#(?P<shortcut>[a-zA-Z0-9-]*))?\n ', '"text :C-A-S-x"')]

menu_root(parent)

Create menu object and set as parent’s menu.

menu_sub(parent, id, text)

Append submenu labeled text to menu parent.

multiline(parent, id=None, text='')

multiline text entry box

option(parent, id=None, text='', checked=None)

Option button. Prefix ‘O’ for unchecked, ‘0’ for checked.

parse(parent, text)

Returns the widget id and widget generated from the textual definition.

Autogenerates id:

• If given, use it
• else, try to use text (extract all a-z0-9_ chars)
• else, use ‘x123’ with 123 being a globally unique number

For label type, id handling is special:

• The label’s id will be "label_" + id
• The id will be remembered and used on the next widget, if it has no id.

If nothing matched, return None, None.

parse_menu(parent, menudef, handlers)

Parse menu definition list and attach to the handlers

place(widget, row=0, col=0, rowspan=1, colspan=1)

place widget

root(title='Window', on_close=None)

make a root (window) widget. Optionally you can give a close handler.

row_stretch(container, row, proportion)

set the given row to stretch according to the proportion.

setval(widget, value)

update the widget from given python-type value.

value-setting must not interfere with, i.e. not happen when the user is editing the widget.

show(frame)

do what is necessary to make frame appear onscreen.

This should start the event loop if necessary.

slider(parent, id=None, min=None, max=None)

slider, integer values, from min to max

textbox(parent, id=None, text='')

single-line text entry box

treelist(parent, id=None, text='', columns=None)

treeview (also usable as plain list)

ascii_designer.toolkit.auto_id(id, text=None, last_label_id='')

for missing id, calculate one from text.

ascii_designer.toolkit_tk module

This is a construction site…

class ascii_designer.toolkit_tk.ToolkitTk(*args, **kwargs)

Builds Tk widgets.

Returns the raw Tk widget (no wrapper).

For each widget, a Tk Variable is generated. It is stored in <widget>.variable (attached as additional property).

If you create Radio buttons, they will all share the same variable.

The multiline widget is a tkinter.scrolledtext.ScrolledText and has no variable.

The ComboBox / Dropdown box is taken from ttk.

Box variable (placeholder): If you replace the box by setting its virtual attribute, the replacement widget must have the same master as the box: in case of normal box the frame root, in case of group box the group box. Recommendation: new_widget = tk.Something(master=autoframe.the_box.master)

anchor(widget, left=True, right=True, top=True, bottom=True)

anchor the widget. Depending on the anchors, widget will be left-, right-, center-aligned or stretched.

box(parent, id=None, text='', given_id='')

An empty panel (frame, widget, however you call it) or group box that you can fill with own widgets.

given_id is the user-given id value, as opposed to id (the autogenerated one). A Group box is created if text AND given_id are set.

The virtual attribute value is the panel itself, or in case of groupbox the contained panel.

button(parent, id=None, text='')

checkbox(parent, id=None, text='', checked=None)

Checkbox

close(frame)

close the frame

col_stretch(container, col, proportion)

set the given col to stretch according to the proportion.

combo(parent, id=None, text='', values=None)

combo box; values is the raw string between the parens. Free-text allowed.

connect(widget, function)

bind the widget’s default event to function.

Default event is:

• click() for a button

• value_changed(new_value) for value-type controls;

  usually fired after focus-lost or Return-press.

dropdown(parent, id=None, text='', values=None)

dropdown box; values is the raw string between the parens. Only preset choices allowed.

getval(widget)

get python-type value from widget.

label(parent, id=None, label_id=None, text='')

menu_command(parent, id, text, shortcut, handler)

Append command labeled text to menu parent.

Handler: func() -> None, is immediately connected.

menu_root(parent)

Create menu object and set as parent’s menu.

menu_sub(parent, id, text)

Append submenu labeled text to menu parent.

multiline(parent, id=None, text='')

multiline text entry box

option(parent, id=None, text='', checked=None)

Option button. Prefix ‘O’ for unchecked, ‘0’ for checked.

place(widget, row=0, col=0, rowspan=1, colspan=1)

place widget

root(title='Window', on_close=None)

make a root (window) widget

row_stretch(container, row, proportion)

set the given row to stretch according to the proportion.

setval(widget, value)

update the widget from given python-type value.

value-setting must not interfere with, i.e. not happen when the user is editing the widget.

show(frame)

do what is necessary to make frame appear onscreen.

slider(parent, id=None, min=None, max=None)

slider, integer values, from min to max

textbox(parent, id=None, text='')

single-line text entry box

treelist(parent, id=None, text='', columns=None)

treeview (also usable as plain list)

Implementation note: Uses a ttk.TreeView, and wraps it into a frame together with a vertical scrollbar. For correct placement, the .place, .grid, .pack methods of the returned tv are replaced by that of the frame.

Returns the treeview widget (within the frame).

ascii_designer.toolkit_qt module

ToolkitQt-specific notes:

• Alignment / Stretch not 100% reliable so far, if using row/col-span.
• Tree / List widget not available so far

• closing of form with X button cannot be stopped in the default handler. If

  you need to do this, replace (root).closeEvent function.

class ascii_designer.toolkit_qt.ToolkitQt(**kwargs)

Warning

class ‘ascii_designer.toolkit_qt.ToolkitQt’ undocumented

anchor(widget, left=True, right=True, top=True, bottom=True)

anchor the widget. Depending on the anchors, widget will be left-, right-, center-aligned or stretched.

box(parent, id=None, text='', given_id='')

An empty panel (frame, widget, however you call it) or group box that you can fill with own widgets.

given_id is the user-given id value, as opposed to id (the autogenerated one). A Group box is created if text AND given_id are set.

The virtual attribute value is the panel itself, or in case of groupbox the contained panel.

button(parent, id=None, text='')

checkbox(parent, id=None, text='', checked=None)

Checkbox

close(frame)

close the frame

col_stretch(container, col, proportion)

set the given col to stretch according to the proportion.

combo(parent, id=None, text='', values=None)

dropdown with editable values.

connect(widget, function)

bind the widget’s default event to function.

Default event is:

• click() for a button

• value_changed(new_value) for value-type controls;

  usually fired after focus-lost or Return-press.

default_shortcuts = {'copy': <DeepFakeModule object>, 'cut': <DeepFakeModule object>, 'delete': <DeepFakeModule object>, 'find': <DeepFakeModule object>, 'new': <DeepFakeModule object>, 'open': <DeepFakeModule object>, 'paste': <DeepFakeModule object>, 'preferences': <DeepFakeModule object>, 'quit': <DeepFakeModule object>, 'redo': <DeepFakeModule object>, 'refresh': <DeepFakeModule object>, 'save': <DeepFakeModule object>, 'save_as': <DeepFakeModule object>, 'undo': <DeepFakeModule object>}

dropdown(parent, id=None, text='', values=None)

dropdown box; values is the raw string between the parens. Only preset choices allowed.

getval(widget)

get python-type value from widget.

label(parent, id=None, label_id=None, text='')

menu_command(parent, id, text, shortcut, handler)

Append command labeled text to menu parent.

Handler: func() -> None, is immediately connected.

menu_root(parent)

Create menu object and set as parent’s menu.

menu_sub(parent, id, text)

Append submenu labeled text to menu parent.

multiline(parent, id=None, text='')

multi-line text entry box

option(parent, id=None, text='', checked=None)

Option button. Prefix ‘O’ for unchecked, ‘0’ for checked.

place(widget, row=0, col=0, rowspan=1, colspan=1)

place widget

root(title='Window', on_close=None)

make a root (window) widget

row_stretch(container, row, proportion)

set the given row to stretch according to the proportion.

setval(widget, value)

update the widget from given python-type value.

value-setting must not interfere with, i.e. not happen when the user is editing the widget.

show(frame)

do what is necessary to make frame appear onscreen.

slider(parent, id=None, min=None, max=None)

slider, integer values, from min to max

textbox(parent, id=None, text='')

single-line text entry box

treelist(parent, id=None, text='', columns=None)

treeview (also usable as plain list)

Qt notes: The model does no caching on its own, but retrieves item data all the time. I.e. if your columns are costly to calculate, roll your own caching please.

ascii_designer.list_model module

Pythonic list and tree classes that can be used in a GUI.

The general concept for Lists is this:

• List is wrapped into an ObsList (by ToolkitBase.setval)
• The “code-side” of the ObsList quacks (mostly) like a regular list.

• The “gui-side” of the ObsList

  • provides COLUMNS (key-value items) dynamically retrieved from each list item
  • remembers column and order to be used when sorting
  • has a notion of “selection” (forwarded to a callback)
  • provides event callbacks for insert, replace, remove, sort.

• Internally, the ListMeta class holds the state data for those functions.

class ascii_designer.list_model.ObsList(iterable=None, keys=None, meta=None, toolkit_parent_id=None)

Base class for treelist values.

Behaves mostly like a list, except that:

• it maintains a list of expected attributes (columns)
• it provides notification when items are added or removed

meta

Container for keys, source functions and remembered sorting.

Type:ListMeta

sorted

whether list is currently sorted by one of the list columns. Sorting the list with a key function (“Python way”) resets sorted to False.

Type:bool

toolkit_ids

can be indexed in the same way as the nodelist, and gives the toolkit-specific identifier of the list/treeview node.

append(value)

S.append(value) – append value to the end of the sequence

children_source(children_source, has_children_source=None)

Sets the source for children of each list item, turning the list into a tree.

children, has_children follow the same semantics as other sources.

Resolving children should return an iterable that will be turned into an ObsList of its own.

has_children should return a truthy value that is used to decide whether to display the expander. If omitted, all nodes get the expander initially if children_source is set.

Children source only applies when the list of children is initially retrieved. Once the children are retrieved, source changes do not affect already-retrieved children anymore.

has_children is usually evaluated immediately, because the treeview needs to decide whether to display an expander icon.

clear() → None -- remove all items from S

count(value) → integer -- return number of occurrences of value

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

find(item)

Finds the sublist and index of the item.

Returns (sublist: ObsList, idx:int).

If not found, raises ValueError.

Scans the whole tree for the item.

find_by_toolkit_id(toolkit_id)

finds the sublist and index of the item having the given toolkit id.

Returns (sublist: ObsList, idx: int)

If not found, raises ValueError.

Scans the whole tree for the item.

get_children(idx)

Get childlist of item at given idx, loading it if not already loaded.

has_children(item)

index(value[, start[, stop]]) → integer -- return first index of value.

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(idx, item)

S.insert(index, value) – insert value before index

item_mutated(item)

Call this when you mutated the item (which must be in this list) and want to update the GUI.

load_children(idx)

Retrieves the childlist of item at given idx.

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

retrieve(item, column='')

reverse()

S.reverse() – reverse IN PLACE

selection

returns the sublist of all currently-selected items.

Raises RuntimeError if the nodelist is detached.

set_listener(listener)

Set listener that observes the list.

The listener can provide any or all of the following methods:

• on_insert(idx, item, toolkit_parent_id) -> toolkit_id: function to call for each inserted item

• on_replace(toolkit_id, item): function to call for replaced item

  Replacement of item implies that children are “collapsed” again.

• on_remove(toolkit_id): function to call for each removed item
• on_load_children(toolkit_parent_id, sublist): function when children of a node are retrieved.

• on_get_selection(): return the items selected in the GUI

  Must return a List of (original) items.

• on_sort(): when list is reordered

set_listener(None) to reset listener.

sort(key=None, ascending: bool = None, restore=False)

Sort the list.

key can be a string, refering to the particular column of the listview. Use Empty String to refer to the anonymous column.

If key is a callable, the list is sorted in normal fashion.

Instead of specifying key and ascending, you can set restore=True to reuse the last applied sorting, if any.

sources(_text=None, **kwargs)

Alter the data binding for each column.

Takes the column names as kwargs and the data source as value; which can be:

• Empty string to retrieve str(obj)

• String "name" to retrieve attribute name from the source object

  (on attribute error, try to get as item)

• list of one item ['something'] to get item 'something' (think of it as index without object)
• Callable lambda obj: .. to do a custom computation.

The _text argument, if given, is used to set the source for the “default” (anynomous-column) value.

class ascii_designer.list_model.ListMeta(keys)

holds the metadata of a ObsList.

copy()

get_observer(name)

retrieve(obj, source)