Alot sets up a widget tree and a mainloop in the constructor of alot.ui.UI. The visible area is a urwid.Frame, where the footer is used as a status line and the body part displays the currently active alot.buffers.Buffer.
To be able to bind keystrokes and translate them to Commands, keypresses are not propagated down the widget tree as is customary in urwid. Instead, the root widget given to urwids mainloop is a custom wrapper (alot.ui.Inputwrap) that interprets key presses. A dedicated SendKeypressCommand can be used to trigger key presses to the wrapped root widget and thereby accessing standard urwid behaviour.
In order to keep the interface non-blocking and react to events like terminal size changes, alot makes use of twisted’s deferred - a framework that makes it easy to deal with callbacks. Many commands in alot make use of inline callbacks, which allow you to treat deferred-returning functions almost like syncronous functions. Consider the following example of a function that prompts for some input and acts on it:
from twisted.internet import defer
@defer.inlineCallbacks
def greet(ui): # ui is instance of alot.ui.UI
name = yield ui.prompt('pls enter your name')
ui.notify('your name is: ' + name)
This class integrates all components of alot and offers methods for user interaction like prompt(), notify() etc. It handles the urwid widget tree and mainloop (we use twisted) and is responsible for opening, closing and focussing buffers.
Parameters: |
|
---|
applies a command
This calls the pre and post hooks attached to the command, as well as cmd.apply().
Parameters: | cmd (Command) – an applicable command |
---|
Dispatches the interpretation of the command line string to CommandSequenceCommand.
Parameters: | cmdline (str) – command line to interpret |
---|
closes given Buffer.
This it removes it from the bufferlist and calls its cleanup() method.
construct and return statusbar widget
prompt user to make a choice.
Parameters: |
|
---|---|
Return type: | twisted.defer.Deferred |
Clears notification popups. Call this to ged rid of messages that don’t time out.
Parameters: | messages – The popups to remove. This should be exactly what notify() returned when creating the popup |
---|
shuts down user interface without cleaning up. Use a alot.commands.globals.ExitCommand for a clean shutdown.
returns currently open buffers for a given subclass of Buffer.
Parameters: | t (alot.buffers.Buffer) – Buffer class |
---|---|
Return type: | list |
return the bottom most focussed widget of the widget tree
opens notification popup.
Parameters: |
|
---|---|
Returns: | an urwid widget (this notification) that can be handed to clear_notify() for removal |
prompt for text input. This returns a Deferred that calls back with the input string.
Parameters: |
|
---|---|
Return type: | twisted.defer.Deferred |
Replaces root widget by given urwid.Widget and makes the UI ignore all further commands apart from cursor movement. If later on key is pressed, the old root widget is reset, callable afterwards is called and normal behaviour is resumed.
redraw interface
list of active buffers
history of the command line prompt
flag used to prevent multiple ‘index locked’ notifications
stores partial keyboard input
saves the last executed commandline
interface mode identifier - type of current buffer
A buffer defines a view to your data. It knows how to render itself, to interpret keypresses and is visible in the “body” part of the widget frame. Different modes are defined by subclasses of the following base class.
Abstract base class for buffers.
called before buffer is closed
return dict of meta infos about this buffer. This can be requested to be displayed in the statusbar.
tells the buffer to (re)construct its visible content.
Available modes are:
Mode | Buffer Subclass |
---|---|
search | SearchBuffer |
thread | ThreadBuffer |
bufferlist | BufferlistBuffer |
taglist | TagListBuffer |
envelope | EnvelopeBuffer |
lists all active buffers
message composition mode
toggles visibility of all envelope headers
shows a result list of threads for a query
returns curently focussed alot.widgets.ThreadlineWidget from the result list.
terminates the process that fills this buffers PipeWalker.
displays a thread as a tree of messages
Parameters: |
---|
collapse message at given position
collapse all messages in thread
expand message at given position
expand all messages in thread
set focus to first message of thread
move focus to first reply to currently focussed message
move focus to last reply to currently focussed message
focus next message in depth first order
focus next matching message in depth first order
focus next sibling of currently focussed message in thread tree
focus next unfolded message in depth first order
move focus to parent of currently focussed message
focus previous message in depth first order
focus previous matching message in depth first order
focus previous sibling of currently focussed message in thread tree
focus previous unfolded message in depth first order
does a walk in the given direction and focuses the first message tree that matches the given property
focus the summary line of currently focussed message
returns a Generator to walk through all positions of MessageTree in the ThreadTree of this buffer.
returns focussed Message
returns position of focussed message in the thread tree
returns currently focussed MessageTree
returns Message ID of focussed message
get MessageTree for given position
returns a Generator of all MessageTree in the ThreadTree of this buffer.
refresh and flushe caches of Thread tree
What follows is a list of the non-standard urwid widgets used in alot. Some of them respect user settings, themes in particular.
Utility Widgets not specific to alot
An AttrMap that can remember attributes to set
This contains alot-specific urwid.Widget used in more than one mode.
one-line summary of an Attachment.
This is a vamped-up urwid.Edit widget that allows for tab-completion using Completer objects
These widgets are meant to be used as user input prompts and hence react to ‘return’ key presses by calling a ‘on_exit’ callback that processes the current text value.
enter: | calls ‘on_exit’ callback with current value |
---|---|
esc: | calls ‘on_exit’ with value None, which can be interpreted as cancelation |
tab: | calls the completer and tabs forward in the result list |
shift tab: | tabs backward in the result list |
up/down: | move in the local input history |
ctrl a/e: | moves curser to the beginning/end of the input |
Parameters: |
|
---|
renders a pile of header values as key/value list
Parameters: |
|
---|
text widget that renders a tagstring.
It looks up the string it displays in the tags section of the config as well as custom theme settings for its tag.
Widgets specific to Bufferlist mode
selectable text widget that represents a Buffer in the BufferlistBuffer.
Widgets specific to search mode
selectable line widget that represents a Thread in the SearchBuffer.
Widgets specific to thread mode
SimpleTree that displays key-value pairs.
The structure will obey the Tree API but will not actually be a tree but a flat list: It contains one top-level node (displaying the k/v pair in Columns) per pair. That is, the root will be the first pair, its sibblings will be the other pairs and first|last_child will always be None.
Parameters: |
|
---|
Selectable Text used for nodes in our example
displays printable parts of an email
one line summary of a Message.
Parameters: |
|
---|
Tree that displays contents of a single alot.db.Message.
Its root node is a MessageSummaryWidget, and its child nodes reflect the messages content (parts for headers/attachments etc).
Collapsing this message corresponds to showing the summary only.
Parameters: |
|
---|
collapse (and show summary only) if the alot.db.Message matches given querystring
Tree that parses a given alot.db.Thread into a tree of MessageTrees that display this threads individual messages. As MessageTreess are not urwid widgets themself this is to be used in combination with NestedTree only.
alot.ui.UI.prompt() allows tab completion using a Completer object handed as ‘completer’ parameter. alot.completion defines several subclasses for different occasions like completing email addresses from an AddressBook, notmuch tagstrings. Some of these actually build on top of each other; the QueryCompleter for example uses a TagsCompleter internally to allow tagstring completion after “is:” or “tag:” keywords when typing a notmuch querystring.
All these classes overide the method complete(), which for a given string and cursor position in that string returns a list of tuples (completed_string, new_cursor_position) that are taken to be the completed values. Note that completed_string does not need to have the original string as prefix. complete() may rise alot.errors.CompletionError exceptions.
completes a contact from given address books
Parameters: |
|
---|
completes users’ own mailaddresses
completes option parameters for a given argparse.Parser
Parameters: | parser (argparse.ArgumentParser) – the option parser we look up parameter and choices from |
---|
completes one command consisting of command name and parameters
Parameters: |
---|
completes command lines: semicolon separated command strings
Parameters: |
---|
computes start and end position of substring of line that is the command string under given position
completes command names
Parameters: | mode (str) – mode identifier |
---|
base class for completers
returns a list of completions and cursor positions for the string original from position pos on.
Parameters: | |
---|---|
Returns: | pairs of completed string and cursor position in the new string |
Return type: | list of (str, int) |
Raises : | CompletionError |
calculates the subword in a sep-splitted list of substrings of original that pos is ia.n
completes contacts from given address books
Parameters: |
|
---|
completion for gpg keys
Parameters: | private (bool) – return private keys |
---|
Meta-Completer that turns any Completer into one that deals with a list of completion strings using the wrapped Completer. This allows for example to easily construct a completer for comma separated recipient-lists using a ContactsCompleter.
Parameters: |
|
---|
calculates the subword of original that pos is in
completion for paths
completion for a notmuch query string
Parameters: | dbman (DBManager) – used to look up avaliable tagstrings |
---|
completer for a fixed list of strings
Parameters: |
|
---|
complete a tagstring
Parameters: | dbman (DBManager) – used to look up avaliable tagstrings |
---|
completion for a comma separated list of tagstrings
Parameters: | dbman (DBManager) – used to look up avaliable tagstrings |
---|