Text User Interface (Full screen applications)¶
quo can be used to create complex full screen terminal applications. Typically, an application consists of a layout (to describe the graphical part) and a set of key bindings.
The sections below describe the components required for full screen applications (or custom, non full screen applications), and how to assemble them together.
Note
Also remember that the examples
directory of the quo
repository contains plenty of examples. Each example is supposed to explain
one idea. So, this as well should help you get started.
Don’t hesitate to open a GitHub issue if you feel that a certain example is missing.
A simple application
¶
Almost every quo application is an instance of an Console
object. The simplest full screen example would look like this:
from quo import container
from quo.widget import TextField
content = TextField("Hello, world")
container(content, bind=False)
This will only consume the least amount of space required.
Note
If we set the full_screen
option, the application will run in an alternate screen buffer, in full screen mode. however a key binder has to be added inorder to exit the app
from quo import container
from quo.keys import bind
from quo.widget import TextField
content = TextField("Hello, world")
# Key binder to exit the application
@bind.add("ctrl-c")
def _(event):
event.app.exit()
container(content, full_screen=True)
An application consists of several components. The most important are:
I/O objects: the input and output device.
The layout: this defines the graphical structure of the application. For instance, a text box on the left side, and a button on the right side.
A style: this defines what colors and underline/bold/italic styles are used everywhere.
A set of key bindings.
We will discuss all of these in more detail below.
I/O objects
¶
Every Console
instance requires an I/O
object for input and output:
An
Input
instance, which is an abstraction of the input stream (stdin).An
Output
instance, which is an abstraction of the output stream, and is called by the renderer.
Both are optional and normally not needed to pass explicitly. Usually, the default works fine.
There is a third I/O object which is also required by the application, but not
passed inside. This is the event loop, an
eventloop
instance. This is basically a
while-true loop that waits for user input, and when it receives something (like
a key press), it will send that to the the appropriate handler, like for
instance, a key binding.
When run()
is called, the event
loop will run until the application is done. An application will quit when
exit()
is called.
The layout
¶
Layout
is the layout for a quo Console
. This also keeps track of which user control is focused or used in the application.
- Parameters
container
- The “root” container for the layout.focused_element
- Element to be focused initially. (Can be anything the `focus` function accepts.)
A layered layout architecture¶
There are several ways to create a layout, depending on how customizable you want things to be. In fact, there are several layers of abstraction.
The most low-level way of creating a layout is by combining
Container
andUIControl
objects.Examples of
Container
objects areVSplit
(vertical split),HSplit
(horizontal split) andFloatContainer
. These containers arrange the layout and can split it in multiple regions. Each container can recursively contain multiple other containers. They can be combined in any way to define the “shape” of the layout.The
Window
object is a special kind of container that can contain aUIControl
object. TheUIControl
object is responsible for the generation of the actual content. TheWindow
object acts as an adaptor between theUIControl
and other containers, but it’s also responsible for the scrolling and line wrapping of the content.Examples of
UIControl
objects areBufferControl
for showing the content of an editable/scrollable buffer, andFormattedTextControl
for displaying (formatted) text.Normally, it is never needed to create new
UIControl
orContainer
classes, but instead you would create the layout by composing instances of the existing built-ins.A higher level abstraction of building a layout is by using “widgets”. A widget is a reusable layout component that can contain multiple containers and controls. Widgets have a
__pt_container__
function, which returns the root container for this widget. Quocontains several widgets likeTextArea
,Button
,Frame
,VerticalLine
and so on.The highest level abstractions can be found in the
dialog
module. There we don’t have to think about the layout, controls and containers at all. This is the simplest way to use quo, but is only meant for specific use cases, like a prompt or a simple dialog window.
Containers and controls¶
The biggest difference between containers and controls is that containers arrange the layout by splitting the screen in many regions, while controls are responsible for generating the actual content.
Note
Under the hood, the difference is:
containers use absolute coordinates, and paint on a
Screen
instance.user controls create a
UIContent
instance. This is a collection of lines that represent the actual content. AUIControl
is not aware of the screen.
Abstract base class |
Examples |
---|---|
|
|
|
|
The Window
class itself is
particular: it is a Container
that
can contain a UIControl
. Thus, it’s the adaptor
between the two. The Window
class also takes
care of scrolling the content and wrapping the lines if needed.
Finally, there is the Layout
class which wraps
the whole layout. This is responsible for keeping track of which window has the
focus.
Here is an example of a layout that displays the content of the default buffer
on the left, and displays "Hello world"
on the right. In between it shows a
vertical line:
from quo import container
from quo.buffer import Buffer
from quo.layout import BufferControl, FormattedTextControl, VSplit, Window
buffer1 = Buffer() # Editable buffer.
content = VSplit([
# One window that holds the BufferControl with the default buffer on the left.
Window(BufferControl(buffer=buffer1)),
# A vertical line in the middle. We explicitly specify the width, to
# make sure that the layout engine will not try to divide the whole
# width by three for all these windows. The window will simply fill its
# content by repeating this character.
Window(width=1, char='|'),
# Display the text 'Hello world' on the right.
Window(FormattedTextControl('Hello world')),
])
container(content, full_screen=True)
# You won't be able to Exit this app unless you add a key binder
Notice that if you execute this right now, there is no way to quit this application yet. This is something we explain in the next section below.
More complex layouts can be achieved by nesting multiple
VSplit
,
HSplit
and
FloatContainer
objects.
If you want to make some part of the layout only visible when a certain
condition is satisfied, use a
ConditionalContainer
.
Finally, there is ScrollablePane
, a container
class that can be used to create long forms or nested layouts that are
scrollable as a whole.
Focusing windows¶
Focusing something can be done by calling the
focus()
method. This method is very
flexible and accepts a Window
, a
Buffer
, a
UIControl
and more.
In the following example, we use get_app()
for getting the active application.
from quo.console import get_app
# This window was created earlier.
w = Window()
# ...
# Now focus it.
get_app().layout.focus(w)
Changing the focus is something which is typically done in a key binding, so read on to see how to define key bindings.
Key bindings
¶
In order to react to user actions, we need to create a
Bind
object using quo.keys.bind()
There are two kinds of key bindings:
Global key bindings, which are always active.
Key bindings that belong to a certain
UIControl
and are only active when this control is focused. BothBufferControl
FormattedTextControl
takes abind
argument.
Global key bindings¶
Key bindings can be passed to the application as follows:
from quo import container
from quo.keys import bind
container(bind=True)
To register a new keyboard shortcut, we can use the
add()
method as a decorator of the key handler:
from quo.keys import bind
@bind.add('ctrl-q')
def exit_(event):
"""
Pressing Ctrl-Q will exit the user interface.
Setting a return value means: quit the event loop that drives the user
interface and return this value from the `Suite.run()` call.
"""
event.app.exit()
container(bind=True, full_screen=True)
The callback function is named exit_
for clarity, but it could have been
named _
(underscore) as well, because we won’t refer to this name.
Read more about key bindings
Modal containers¶
The following container objects take a modal
argument
VSplit
,
HSplit
, and
FloatContainer
.
Setting modal=True
makes what is called a modal container. Normally, a
child container would inherit its parent key bindings. This does not apply to
modal containers.
Consider a modal container (e.g. VSplit
)
is child of another container, its parent. Any key bindings from the parent
are not taken into account if the modal container (child) has the focus.
This is useful in a complex layout, where many controls have their own key bindings, but you only want to enable the key bindings for a certain region of the layout.
The global key bindings are always active.
More about the Window class
¶
As said earlier, a Window
is a
Container
that wraps a
UIControl
, like a
BufferControl
or
FormattedTextControl
.
Note
Basically, windows are the leafs in the tree structure that represent the UI.
A Window
provides a “view” on the
UIControl
, which provides lines of content. The
window is in the first place responsible for the line wrapping and scrolling of
the content, but there are much more options.
Adding left or right margins. These are used for displaying scroll bars or line numbers.
There are the cursorline and cursorcolumn options. These allow highlighting the line or column of the cursor position.
Alignment of the content. The content can be left aligned, right aligned or centered.
Finally, the background can be filled with a default character.
More about buffers and BufferControl
¶
Input processors¶
A Processor
is used to postprocess
the content of a BufferControl
before it’s
displayed. It can for instance highlight matching brackets or change the
visualisation of tabs and so on.
A Processor
operates on individual
lines. Basically, it takes a (formatted) line and produces a new (formatted)
line.
Some build-in processors:
Processor |
Usage: |
---|---|
|
Highlight the current search results. |
|
Highlight the selection. |
|
Display input as asterisks. ( |
|
Highlight open/close mismatches for brackets. |
|
Insert some text before. |
|
Insert some text after. |
|
Append auto suggestion text. |
|
Visualise leading whitespace. |
|
Visualise trailing whitespace. |
|
Visualise tabs as n spaces, or some symbols. |
A BufferControl
takes only one processor as
input, but it is possible to “merge” multiple processors into one with the merge_processors()
function
» Check out more examples here