Hooks & Input¶
A hook is a function that xnano calls when something happens. Attach a hook
with the hook decorator. Its on= argument sets the kind of event that runs
it. xnano calls the hook with a Context, which holds
the event and the devices of the canvas.
This page is about the keyboard and the mouse. For hooks that run on time, such
as on='tick', see Time & Effects.
Keys¶
on='key' runs a hook each time the user presses a key. While the user holds a
key, the terminal repeats it, and the hook runs again for each repeat. keys=
limits the hook to one key or to a list of keys.
import xnano
with xnano.open(height=3) as terminal:
count = terminal.write('pressed 0 times') # >> [placement]
terminal.write('space count · q quit', y='bottom', dim=True)
presses = 0
@terminal.hook(on='key', keys='space')
def add_one(context: xnano.Context):
global presses # >> [global]
presses += 1
count.text = f'pressed {presses} times' # >> [placement]
terminal.run(stop_on='q')
terminal.write() is the same as terminal.screen.write(). It returns a
placement. Set its text to change what the screen shows.
The hook changes presses, a variable outside the function, so the hook
declares it global.

Leave out keys= to run the hook for every key. context.keyboard.key is the
name of the key that the user pressed. A key name is a character such as 'a',
or a word such as 'enter', 'escape', 'backspace', 'tab', 'up' or
'f1'.
import xnano
with xnano.open(height=2) as terminal:
last = terminal.write('press any key')
terminal.write('q quit', y='bottom', dim=True)
@terminal.hook(on='key')
def show_key(context: xnano.Context):
last.text = f'you pressed {context.keyboard.key}'
terminal.run(stop_on='q')

If keys= has a name that is not a key, hook raises a ValueError. The
message suggests the closest key names, for example 'space' for 'spcae'.
Shortcuts¶
A key with modifiers is one string, with + between the parts, such as
'ctrl+s', 'alt+enter' or 'shift+tab'. To run one hook for several keys,
give keys= a list.
import xnano
with xnano.open(height=2) as terminal:
status = terminal.write('ctrl+s save · escape cancel · q quit')
@terminal.hook(on='key', keys='ctrl+s')
def save(context: xnano.Context):
status.text = 'saved'
@terminal.hook(on='key', keys=['escape', 'ctrl+z'])
def cancel(context: xnano.Context):
status.text = 'cancelled'
terminal.run(stop_on='q')
Some terminals send a key with alt as escape followed by the key. Then
xnano cannot always know which keys the user pressed. If your program uses
escape or alt keys, give keyboard='disambiguated' to xnano.open().
Terminals that support this setting then send each key in its own form.
Move with the arrow keys¶
context.keyboard.direction() reads the arrow keys and the w, a, s and
d keys. It returns one step on each axis, as (step_x, step_y). Each step is
-1, 0 or 1, and y increases downward. For example, left gives (-1, 0)
and down gives (0, 1). Any other key gives (0, 0).
import xnano
with xnano.open(height=6, edges='stop') as terminal: # >> [edges]
player = terminal.write('@', x='center', y='center', foreground='yellow')
terminal.write('arrows or wasd move · q quit', y='bottom', dim=True)
@terminal.hook(on='key')
def move(context: xnano.Context):
step_x, step_y = context.keyboard.direction()
player.move(step_x, step_y) # >> [move]
terminal.run(stop_on='q')
edges='stop' keeps each placement inside the canvas when it moves. Without
it, a placement can move past an edge, and xnano does not draw the part outside.
Moves the placement by a number of columns and rows.

To use other keys, give them to direction(), for example
direction(left='h', right='l', up='k', down='j'). These keys replace the arrow
keys and wasd.
The mouse¶
A terminal reports the mouse only when a program asks for it. Give mouse=True
to xnano.open() to receive presses, releases and drags. Without it, mouse
hooks do not run. To also receive each movement of the pointer, give
mouse='motion'.
A hook on a placement receives only the pointer events inside that
placement. With such a hook, any placement can be a button. context.mouse
describes the event:
is_downisTruewhile a button is held.kindis'press','release','drag'or'move'.buttonis'left','right'or'middle'.positionis the cell under the pointer, withxandy.
import xnano
with xnano.open(height=4, mouse=True) as terminal:
button = terminal.write(' off ', border='rounded')
terminal.write('click the switch · q quit', y='bottom', dim=True)
is_on = False
@button.hook(on='mouse')
def toggle(context: xnano.Context):
global is_on
if context.mouse.kind == 'press': # >> [press]
is_on = not is_on
button.text = ' on ' if is_on else ' off '
button.color.fg = 'green' if is_on else 'reset' # >> [reset]
terminal.run(stop_on='q')
A click sends a press and then a release. The hook acts only on the press, so
one click changes the switch one time. is_down is also True during a drag,
so a hook that uses it runs its code again at each step of the drag.
'reset' gives the text the default color of the terminal again.

Drag with the mouse¶
A drag hook can be a generator. Each bare yield waits for the next
movement of the pointer, then gives the hook a new context. Write it as
context = yield. The loop runs while the user holds the button. After a press
inside the placement, the hook receives each movement until the user releases
the button, also outside the placement.
A range such as x=(0, 29) keeps a placement between two columns. Here, it
keeps the thumb of the slider on its track, from column 0 to column 29.
import xnano
with xnano.open(height=3, mouse=True) as terminal:
terminal.write('─' * 30, y=1, dim=True)
label = terminal.write('drag the ●', y=2)
thumb = terminal.write('●', x=(0, 29), y=1)
@thumb.hook(on='drag')
def slide(context: xnano.Context):
while context.mouse.is_down:
thumb.x = context.parent.local(context.mouse.position).x # >> [local]
context = yield # >> [yield]
label.text = f'dropped at {thumb.x}'
terminal.run(stop_on='q')
local() changes a position on the screen into a position inside the parent of
the thumb. The slider then works at any position on the screen.
Waits for the next movement of the pointer. Then the hook continues with the new context.

Follow the pointer¶
PointerPosition is the cell that the
pointer was over in the last mouse report. It is an expression, as the clock is.
Give PointerPosition.x and PointerPosition.y to write(), and the placement
follows the pointer without a hook. Use mouse='motion', so that the terminal
reports each movement of the pointer.
import xnano
from xnano.expressions import PointerPosition
with xnano.open(height=6, mouse='motion') as terminal:
terminal.write('move the mouse · q quit', y='bottom', dim=True)
terminal.write('<+>', x=PointerPosition.x - 1, y=PointerPosition.y) # >> [center]
terminal.run(stop_on='q')
- 1 puts the middle cell of <+> on the pointer. To put the center of a
placement on the pointer, subtract half of its width and half of its height.
Before the first mouse report, the position has no value, so xnano does not draw
the placement. After that, PointerPosition keeps its value, also after a key
press or another event. While the mouse does not move, the placement causes no
frames. The canvas draws a frame for it only when the pointer moves. These rules
apply to such a placement:
is_visible = Falsehides it, as it hides other placements.- Before the first mouse report,
write()withlock=Trueraises aTerminalError, because the position has no value to keep.
context.mouse.position and the expression
MousePosition are different. They give the
cell of the mouse event that the hook receives now, so use them in a mouse hook.
The cursor of the
Circles
game follows the pointer with PointerPosition.
The mouse wheel¶
To receive the mouse wheel, give scroll=True to xnano.open(). Then attach a
hook with on='scroll'. context.mouse.scroll.y is the number of steps: -1
for one step up and 1 for one step down. context.mouse.scroll.x gives the
steps to the side, with positive steps to the right.
Pasted text¶
on='paste' runs a hook when the user pastes text. The hook receives all of the
text at one time, not one key at a time. The text is in
context.keyboard.pasted.
import xnano
with xnano.open(height=2) as terminal:
received = terminal.write('paste something')
@terminal.hook(on='paste')
def show_paste(context: xnano.Context):
received.text = f'{len(context.keyboard.pasted)} characters pasted'
terminal.run(stop_on='q')
Paste events are on by default. If you give paste=False to xnano.open(),
pasted text arrives as key presses.
Stop the program¶
terminal.run() keeps the program open until the user presses a stop key.
stop_on= sets the stop keys, as one key or a list of keys. Without
stop_on=, the stop key is 'ctrl+c'. ctrl+c also stops the program when
you give other stop keys. A hook can stop the program with
context.canvas.stop().
import xnano
with xnano.open(height=2) as terminal:
terminal.write('press enter three times')
presses = 0
@terminal.hook(on='key', keys='enter')
def count(context: xnano.Context):
global presses
presses += 1
if presses == 3:
context.canvas.stop() # >> [stop]
terminal.run()
Ends the loop. terminal.run() returns, and the canvas closes.
End a run and keep the terminal¶
A program with several steps needs terminal.run() to return while the
terminal stays open: a title screen before a game, or the pages of a form. Give
end_on= the key, or the keys, that end the run. When the user presses one,
terminal.run() returns, and the terminal goes on drawing and listening. Your
program can then change the screen and call terminal.run() again. A hook can
end the run with context.canvas.end_run().
import xnano
with xnano.open(height=2) as terminal:
message = terminal.write('press enter to start')
terminal.run(stop_on='q', end_on='enter') # >> [end]
if terminal.is_running: # >> [is_running]
message.text = 'loading...'
@terminal.hook(on='tick', after=1.0)
def loaded(context: xnano.Context):
context.canvas.end_run() # >> [end_run]
terminal.run(stop_on='q')
if terminal.is_running:
message.text = 'ready: press q to quit'
terminal.run(stop_on='q')
enter ends this run and leaves the terminal open. q still stops the
terminal.
True after the run ended, and False after the terminal stopped. A stopped
terminal is closed, and writing to it raises an error, so the program only
goes on while the terminal is running.
Ends the run that is waiting. If no run is waiting, it does nothing.
The stop keys and the end keys belong to one call of terminal.run(). Give
them again to the next call.
A hook runs until you remove it. You can remove a hook in two ways:
- Outside the hook, call
remove()on the name of the function, for examplecount.remove(). The decorator replaces the function with the hook, so the name refers to the hook. - Inside the hook, call
context.hook.remove().
There are more kinds of hooks: 'focus', 'resize', 'state' and 'custom'.
The hook reference lists every kind and all of the options.