tickit

package: libtickit-devel

title: tickit(7)

summary: Terminal Interface Construction KIT

text:
# tickit(7)

## NAME
tickit - Terminal Interface Construction KIT

## SYNOPSIS

```
#include <tickit.h>

typedef struct Tickit;
```

## DESCRIPTION
tickit is a library for building full-screen interactive programs that use a terminal interface. A program using this library would start by creating a toplevel Tickit instance, from which one or more divisions of the terminal area, called "windows" are created. These form a heirarchial tree that subdivides the content area into independent regions that can be managed by different parts of the program structure. Each window can react to input events such as keyboard or mouse interaction.

As well as creating the initial root window, the toplevel Tickit instance also performs a few other jobs for the containing program. It can act as a containing event loop for the program, performing IO multiplexing tasks both for tickit's own needs and the needs of the program as a whole.

## FUNCTIONS
A new toplevel instance is created by using tickit_build(3), tickit_new_stdio(3) or tickit_new_stdtty(3). A toplevel instance stores a reference count to make it easier for applications to manage its lifetime. A new toplevel instance starts with a count of one, and it can be adjusted using tickit_ref(3) and tickit_unref(3). When the count reaches zero the instance is destroyed.

The toplevel instance manages a tree of TickitWindow instances. The root of this tree is obtained by tickit_get_rootwin(3) and thereafter can be divided further by other functions on the window, described more in tickit_window(7).

The TickitTerm instance behind the toplevel instance can be obtained by tickit_get_term(3), and is described more in tickit_term(7).

Event handling callback functions can be installed to be called at a later time, by using tickit_watch_io(3), tickit_watch_timer_after_msec(3), tickit_watch_timer_after_tv(3), tickit_watch_later(3), tickit_watch_signal(3) or tickit_watch_process(3). The main IO event loop is controlled using tickit_run(3) and tickit_stop(3).

The compile-time and run-time version of the library can be inspected using the macros and functions described in tickit_version(7).

## TYPICAL STRUCTURE
A typical program using this library would start by creating the toplevel instance, by calling tickit_new_stdtty(3), then obtain its root window on it by calling tickit_get_rootwin(3). This root window can then be sub-divided into regions of interest by calling tickit_window_new(3) to build a tree of windows. Window can then have some event handlers attached by calling tickit_window_bind_event(3) - each window will need to handle the TICKIT_WINDOW_ON_EXPOSE event, but might also wish to handle other kinds like geometry change for dynamic resizing, or keyboard or mouse to react to user input. Finally, once the initial window tree is created, the program would enter the main event loop by invoking tickit_run(3).

## COMMON TYPES
The flags argument to the various tickit_..._bind_event() functions should be zero, or a bitmask of the following constants.

```
typedef enum {
  TICKIT_BIND_FIRST,
  TICKIT_BIND_UNBIND,
  TICKIT_BIND_DESTROY,
  TICKIT_BIND_ONESHOT,
} TickitBindFlags;
```

TICKIT_BIND_FIRST indicates that this handler should be inserted at the start of the list, rather than the default position at the end.

TICKIT_BIND_UNBIND indicates that this handler should also be invoked at the time it is unbound, either due to a specific call to the tickit_..._unbind_event() function, or because the bound object is being destroyed.

TICKIT_BIND_DESTROY indicates that this handler should also be invoked at the time that the bound object is being destroyed.

TICKIT_BIND_ONESHOT indicates that the handler should be invoke at-most once, and unbound the first time it is invoked. When invoked it will receive both the TICKIT_EV_FIRE and TICKIT_EV_UNBIND flags at once.

Some API functions take or return the following enum type, to represent a tri-state extended boolean concept of true, false, or some third condition typically indicating a "don't care" or "unknown" state; the exact semantics will vary between specific uses and should be documented specifically.

```
typedef enum {
  TICKIT_YES = 1,
  TICKIT_NO = 0,
  TICKIT_MAYBE = -1,
} TickitMaybeBool;
```

The various tickit_*ctl_type() and tickit_pen_attrtype(3) functions return the following enum type, to indicate what type of value each individual control or attribute takes.

```
typedef enum {
  TICKIT_TYPE_NONE,
  TICKIT_TYPE_BOOL,
  TICKIT_TYPE_INT,
  TICKIT_TYPE_COLOUR,
} TickitType;
```

## COMMON EVENTS
Every object instance that supports events supports the following type of event, in addition to the specific ones listed for that kind of object:

TICKIT_..._ON_DESTROY

Invoked when the object instance is being destroyed. This will be the last time the application can use the stored data argument; it may perform any resource reclaiming operations that are required at this time.

## EVENT FLAGS
When an event handler function is invoked, it is passed a bitmask of flags to indicate the reason for its invocation.

```
typedef enum {
  TICKIT_EV_FIRE,
  TICKIT_EV_UNBIND,
  TICKIT_EV_DESTROY,
} TickitEventFlags;
```

TICKIT_EV_FIRE

This handler is being invoked because its associated event has occurred. The info pointer will point to a structure containing the relevant information.

TICKIT_EV_UNBIND

This handler is being invoked because it is being removed from the object. This will only be observed if it was bound with the TICKIT_BIND_UNBIND flag. The info pointer will be NULL.

TICKIT_EV_DESTROY

This handler is being invoked because the object instance itself is being destroyed. This will be observed if it was bound with the TICKIT_BIND_DESTROY flag, or because it is bound to the TICKIT_..._ON_DESTROY event. The info pointer will be NULL.

Any event handlers for this event will be invoked in reverse order; the newest is run first and the oldest last.

## CONTROLS
A toplevel instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_setctl_int(3), and queried using tickit_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_ctl_name(3) and searched by name using tickit_ctl_lookup(3). The type of a control option can be queried using tickit_ctl_type(3).

The options are given in an enumeration called TickitCtl. The following control values are recognised:

TICKIT_CTL_USE_ALTSCREEN (bool)

The value is a boolean indicating whether the instance will activate the terminal alternate screen buffer mode when started.

## SEE ALSO
tickit_window(7), tickit_term(7), tickit_pen(7), tickit_rect(7), tickit_rectset(7), tickit_renderbuffer(7), tickit_string(7), tickit_utf8_count(3), tickit_version(7)


title: tickit_debug(7)

summary: debug logging support for libtickit

text:
# tickit_debug(7)

## NAME
Tickit_Debug - debug logging support for libtickit

## SYNOPSIS

```
$ TICKIT_DEBUG_FLAGS=W TICKIT_DEBUG_FILE=tickit.log a-tickit-program
```

## DESCRIPTION
The libtickit library contains a debug logging system that other parts of the library use to report on interesting events and behaviours, that may help developers to observe internal details and assist in the development and debugging of applications that use the library.

Debug messages themselves each have a flag name, which is a short string identifying the library component or event that caused that message. A given set of these flags can be enabled during a debugging session, causing only those messages to be printed. Messages pertaining to flags that are not enabled will not be printed.

## FLAGS
Each flag name starts with an upper-case letter indicating the library component it relates to, then lower-case letters to indicate the particular kind of event or message within that component.

### B
These messages relate to TickitRenderBuffer (tickit_renderbuffer(7)).

Bd

Drawing operations such as tickit_renderbuffer_text(3).

Bf

Flushing

Bs

Stack state save and restore.

Bt

### I
These messages relate to input-system events.

Ik

Keyboard keypresses.

Im

Mouse movement and button or wheel events.

Ir

Terminal resize. Transformations (translation, clipping and masking).

### W
These messages relate to windows.

W*

Window destroyed.

Wd

Damage to root window.

Wx

Window is exposed.

Wh

Window hierarchy changed.

Ws

Window scrolls.

Wsr

Window propagates a scrollrect to its underlying terminal.

## ENVIRONMENT
The debugging support is controlled by the following environment variables, which should be set before the application starts, or early during its initialisation before it has invoked any libtickit functions.

TICKIT_DEBUG_FLAGS

A comma-separated list of the flags or flag categories to enable for printing. Entire categories of flags can be enabled by list just the initial capital letter of its name. All the flags can be enabled at once by setting the name *.

TICKIT_DEBUG_FILE

Gives the name of a file to open in append mode to write logging lines to.

TICKIT_DEBUG_FD

Gives a file descriptor number to write logging lines to.

One technique that may be useful to observe logging in real-time while the application runs is to arrange for the application to run in a new terminal but have it log debugging output to an existing one. This may be achieved using

```
$ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM my-tickit-app 3>&2
```

This requests that libtickit log to file descriptor 3, which has been created by dup(2)ing the original shell's standard output. Debug logging will therefore be printed to the existing terminal where this command was executed, while the application itself draws its output to the newly-created one.

## FUNCTIONS
The debug system is initialised by calling tickit_debug_init(3). Messages can be logged using tickit_debug_logf(3) and tickit_debug_vlogf(3).

## SEE ALSO
tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_window(7)


title: tickit_pen(7)

text:
# tickit_pen(7)

## NAME
TickitPen - store a collection of terminal rendering attributes

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitPen;
```

## DESCRIPTION
A TickitPen instance stores a collection of terminal rendering attributes. For each known attribute, a pen instance may store a value for this attribute. A pen instance is used in the tickit_term_chpen(3) and tickit_term_setpen(3) functions.

## FUNCTIONS
A new TickitPen instance is created using the tickit_pen_new(3) function. A pen instance stores a reference count to make it easier for applications to manage the lifetime of pens. A new pen starts with a count of one, and it can be adjusted using tickit_pen_ref(3) and tickit_pen_unref(3). When the count reaches zero the instance is destroyed.

## ATTRIBUTES
The TickitPenAttr enumeration lists the attributes known by a pen. Each attribute has a type, as given by the TickitPenAttrType enumeration. The tickit_penattr_type(3) function gives the type of a given attribute. The tickit_penattr_name(3) function gives the name of a given attribute, which is also given below in parentheses. The tickit_penattr_lookup(3) function looks up an attribute constant from a string containing the name.

TICKIT_PEN_FG ("fg"), TICKIT_PEN_BG ("bg")

foreground and background colours. These are of type TICKIT_PENTYPE_COLOUR. This gives an integer from 0 to 255 to use as the colour index. It may also be set to the value -1, which sets the terminal's default, which may be a colour distinct from any of the others. Some terminals may not support more than 8 or 16 colours, however. When setting a pen colour on a terminal, it may be converted to one that is supported by the terminal tickit_term_setpen(3) or tickit_term_chpen(3) functions.

These colour attributes also support a secondary RGB8 (24-bit) specification, which some terminal drivers may prefer over the indexed version.

TICKIT_PEN_BOLD ("b"), TICKIT_PEN_ITALIC ("i"), TICKIT_PEN_REVERSE ("rv"), TICKIT_PEN_STRIKE ("strike"), TICKIT_PEN_BLINK ("blink")

boolean rendering attributes. These are of type TICKIT_PENTYPE_BOOL. They are either true or false. Most terminals should support at least bold, underline, reverse and blink, though italic and strikethrough are less commonly supported. Applications are advised not to use these two alone to distinguish significant parts of the user interface.

TICKIT_PEN_UNDER ("u")

underline. This is of type TICKIT_PENTYPE_INT. Its value is one of the values from the TickitPenUnderline enumeration. Most terminals should support the single underline value, however other values are less commonly supported, and may be drawn instead as a single underline. Applications are advised not to make use of underline style alone to distinguish significant parts of the user interface.

Valid values are:

TICKIT_PEN_UNDER_NONE

No underline.

TICKIT_PEN_UNDER_SINGLE

Single underline.

TICKIT_PEN_UNDER_DOUBLE

Double underline.

TICKIT_PEN_UNDER_WAVY

Single wavy underline, sometimes called "undercurl".

For backward-compatibility this attribute will also behave like a boolean-typed attribute. When set to any value other than none, it appears true as a boolean. Setting it to true as a booelan will set its value to single.

TICKIT_PEN_ALTFONT ("af")

alternate font index. This is of type TICKIT_PENTYPE_INT. It is a value 0 to 9, which selects from the terminal's available fonts. Few terminals actually support this in practice.

## FUNCTIONS
The values of attributes are set or queried on a pen instance by using functions depending on the type of the attribute. Boolean attributes use tickit_pen_set_bool_attr(3) and tickit_pen_get_bool_attr(3). Integer attributes use tickit_pen_set_int_attr(3) and tickit_pen_get_int_attr(3). Colour attributes use tickit_pen_set_colour_attr(3), tickit_pen_set_colour_attr_desc(3) and tickit_pen_get_colour_attr(3). The RGB8 secondary field for colours can be set with tickit_pen_set_colour_attr_rgb8(3), and queried with tickit_pen_has_colour_attr_rgb8(3) and tickit_pen_get_colour_attr_rgb8(3).

To test if an attribute has a value set, use tickit_pen_has_attr(3), and to remove the attribute entirely use tickit_pen_clear_attr(3). To test if a pen has any attributes set at all, use tickit_pen_is_nonempty(3), and to test if it has any attributes set to a non-default value use tickit_pen_is_nondefault(3). To remove all the attributes use tickit_pen_clear(3). To copy the value of one attribute from a pen into another pen use tickit_pen_copy_attr(3), to copy the entire pen use tickit_pen_copy(3), and to compare two pens for equality use tickit_pen_equiv_attr(3).

## EVENTS
A pen instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_pen_bind_event(3) and removed using tickit_pen_unbind_event_id(3).

The event types recognised are:

TICKIT_PEN_ON_DESTROY

The pen instance is being destroyed.

TICKIT_PEN_ON_CHANGE

The stored attributes on the pen have changed. The info pointer will be NULL.


title: tickit_rect(7)

text:
# tickit_rect(7)

## NAME
TickitRect - utility structure representing a rectangular region

## SYNOPSIS

```
#include <tickit.h>

typedef struct {
  int top;
  int left;
  int lines;
  int cols;
} TickitRect;
```

## DESCRIPTION
A TickitRect structure represents a single non-empty rectangular region of the screen. It stores the position of the top left corner of the region, and its size in lines and columns.

## FUNCTIONS
A new TickitRect structure can be initialised using the tickit_rect_init_sized(3) and tickit_rect_init_bounded(3) functions. Its bottom right corner can be obtained using tickit_rect_bottom(3) and tickit_rect_right(3). Interactions between rectangles can be tested using the predicate functions tickit_rect_contains(3) and tickit_rect_intersects(3). New rectangles can be created from existing ones using tickit_rect_intersect(3) to form the intersection, tickit_rect_add(3) to form the union sum, and tickit_rect_subtract(3).


title: tickit_rectset(7)

summary: store a collection of rectangular areas

text:
# tickit_rectset(7)

## NAME
TickitRectSet - store a collection of rectangular areas

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitRectSet;
```

## DESCRIPTION
A TickitRectSet instance stores a collection of rectangular areas as non-overlapping regions. Mutation operations allow areas to be added or subtracted. Query operations allow testing for area containment, intersection, or iterating the stored regions.

## FUNCTIONS
A new TickitRectSet instance is created using the tickit_rectset_new(3) function, and destroyed using tickit_rectset_destroy(3).

Rectangular areas can be added using tickit_rectset_add(3) and subtracted using tickit_rectset_subtract(3). The TickitRectSet can be emptied of regions entirely by using tickit_rectset_clear(3). The entire set of regions can be uniformly moved using tickit_rectset_translate(3).

The stored regions can be queried by using tickit_rectset_rects(3) and tickit_rectset_get_rects(3). An area can be tested to see if it is entirely contained in the set using tickit_rectset_contains(3), or that it intersects at all using tickit_rectset_intersects(3).


title: tickit_renderbuffer(7)

text:
# tickit_renderbuffer(7)

## NAME
TickitRenderBuffer - store display content to be drawn to the terminal

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitRenderBuffer;
```

## DESCRIPTION
A TickitRenderBuffer instance stores content waiting to be drawn to the terminal. It provides an efficient place to build the eventual display, by applying drawing operations to it that can alter and overwrite the pending content, before eventually flushing it directly to the terminal in an efficient transfer of state. The buffer stores plain text content along with rendering attributes, and also stores line drawing information, allowing line segments to be merged correctly and rendered using Unicode characters.

The primary purpose for the render buffer is the storage of pending content to be displayed. The buffer consists of a grid of cells of the given size. Each cell has a state; neighbouring cells in the same state constitute a region. Each region is either in a skip state (where it will not affect the terminal display when it is flushed), or has either textual content or an instruction to erase the display. In both of these cases, the region has an associated TickitPen instance to give its display attributes. Text regions can be given either by UTF-8 strings, individual Unicode codepoint numbers, or are created as Unicode line-drawing characters by merging one or more effective line segments.

There are several advantages to using a TickitRenderBuffer over plain drawing requests directly to the terminal. Firstly, because the content is simply stored in memory until it is flushed to the terminal, it doesn't have to be rendered in screen order. It can be built up in any order that makes sense within the application, and when flushed to the terminal it will be performed in an efficient top-to-bottom, left-to-right order.

Secondly, the buffer understands horizontal and vertical line drawing using Unicode characters. While content is being built up, it will keep track of what kinds of lines meet in every cell in the buffer, so that when it is flushed to the terminal it can pick the appropriate Unicode line-drawing characters to render these with.

Thirdly, several features of the buffer are designed to easily support applications that divide the screen area into several possibly-overlapping regions that are managed by different parts of the application. Clipping, translation and masking support the concept of independent areas of the buffer, and stored pens and the state stack support the concept that these areas might be nested within each other, allowing rendering attributes to be inherited from outer regions into inner ones.

### VIRTUAL CURSOR
A TickitRenderBuffer instance maintains a virtual cursor position, that application code can use to render at. This is a virtual cursor, because it doesn't relate to the actual cursor in use on the terminal instance; it is simply a position stored by the buffer state.

Most of the content drawing functions come in pairs; one using and updating the cursor position, and a second that operates directly on the buffer contents, without regard to the virtual cursor. Functions of this latter form can be identified by the _at suffix on their name.

### PEN
A TickitPen instance can be set on a TickitRenderBuffer, acting as a default pen for subsequent drawing functions. This is optionally combined with a pen instance given to individual drawing functions; if both are present then the attributes are combined, with those of the given pen taking precedence over the ones in the stored pen.

### TRANSLATION
A translation offset can be applied to have the drawing functions store their output at some other location within the buffer. This translation only affects the drawing functions; the actual operation to flush the contents to the terminal is not affected.

### CLIPPING AND MASKING
All of the drawing functions are also subject to restriction of their output, to apply within a clipping region. Initially the entire buffer is available for drawing, but the area can be restricted to a smaller rectangular area at any time. Requests to draw content outside of this region will be ignored.

In addition to clipping, a buffer can also mask out arbitrary additional rectangular areas within the clipping region. These areas act with the clipping region by ignoring requests to draw inside them while preserving any existing content within them.

Masking and clipping are related but separate concepts. Both place restrictions on where output functions can alter the pending content. Whereas the clipping region is the rectangular area within which all drawing occurs, masking regions are areas in which drawing does not occur.

When combined with translation, these two features allow possibly-overlapping regions of content to be independently managed by separate pieces of code. To render each region of the screen, a render buffer can be set up with a translation offset and clipping rectangle to suit that region, thus avoiding the rendering code having to care about the exact on-screen geometry. By using masking regions, additionally these areas can be managed even when they overlap, by ensuring that areas already drawn by "higher" regions are masked off to ensure that "lower" regions do not overwrite them.

### SAVE STACK
As a further assistance to applications wishing to divide the screen area into nested regions, a set of functions exist to store the current auxiliary state of the buffer (that is, all of the mutable attributes listed above, but without the actual pending content) and later restore that state to its original values.

## FUNCTIONS
A new TickitRenderBuffer instance is created using tickit_renderbuffer_new(3). A render buffer instance stores a reference count to make it easier for applications to manage the lifetime of buffers. A new buffer starts with a count of one, and it can be adjusted using tickit_renderbuffer_ref(3) and tickit_renderbuffer_unref(3). When the count reaches zero the instance is destroyed.

Its size is fixed after creation and can be queried using tickit_renderbuffer_get_size(3). Its contents can be entirely reset back to its original state using tickit_renderbuffer_reset(3).

A translation offset can be set using tickit_renderbuffer_translate(3), and the clipping region restricted using tickit_renderbuffer_clip(3). Masks can be placed within the current clipping region using tickit_renderbuffer_mask(3).

The virtual cursor position can be set using tickit_renderbuffer_goto(3) and unset using tickit_renderbuffer_ungoto(3). It can be queried using tickit_renderbuffer_has_cursorpos(3) to determine if it is set, and tickit_renderbuffer_get_cursorpos(3) to return its position. A TickitPen instance can be set using tickit_renderbuffer_setpen(3).

The auxiliary state can be saved to the state stack using tickit_renderbuffer_save(3) and later restored using tickit_renderbuffer_restore(3). A stack state consisting of just the pen with no other state can be saved using tickit_renderbuffer_savepen(3).

The stored content of a buffer can be copied to another buffer using tickit_renderbuffer_blit(3). This is useful for allowing a window to maintain a backing buffer that can be drawn to at any time and then copied to a destination buffer for display.

The stored content can be flushed to a TickitTerm instance using tickit_renderbuffer_flush_to_term(3).

## DRAWING OPERATIONS
The following functions all affect the stored content within the buffer, taking into account the clipping, translation, masking, stored pen, and optionally the virtual cursor position.

tickit_renderbuffer_skip_at(3), tickit_renderbuffer_skip(3), tickit_renderbuffer_skip_to(3) and tickit_renderbuffer_skiprect(3) create a skipping region; a place where no output will be drawn.

tickit_renderbuffer_text_at(3) and tickit_renderbuffer_text(3) create a text region; a place where normal text is output.

tickit_renderbuffer_erase_at(3), tickit_renderbuffer_erase(3) and tickit_renderbuffer_erase_to(3) create an erase region; a place where existing terminal content will be erased. tickit_renderbuffer_eraserect(3) is a convenient shortcut that erases a rectangle, and tickit_renderbuffer_clear(3) erases the entire buffer area.

tickit_renderbuffer_char_at(3) and tickit_renderbuffer_char(3) place a single Unicode character directly.

tickit_renderbuffer_hline_at(3) and tickit_renderbuffer_vline_at(3) create horizontal and vertical line segments.

## SEE ALSO
tickit(7), tickit_pen(7), tickit_rect(7) tickit_term(7)


title: tickit_string(7)

summary: a reference-counted string buffer

text:
# tickit_string(7)

## NAME
TickitString - a reference-counted string buffer

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitString;
```

## DESCRIPTION
A TickitString instance stores a NUL-terminated character buffer (i.e. a plain C string) and a reference count. It allows string buffers to be efficiently shared while their usage is tracked, and reclaimed once no longer required.

## FUNCTIONS
A new TickitString instance is created by calling tickit_string_new(3). Once constructed, its buffer can be read by calling tickit_string_get(3) and its length queried by tickit_string_len(3). The buffer should be considered immutable; it cannot be modified.

A string instance maintains a reference count to make it easier for applications to share and manage the lifetime of these buffers. A new string starts with a count of one, and it can be adjusted using tickit_string_ref(3) and tickit_string_unref(3). When the count reaches zero the instance is destroyed.

## SEE ALSO
tickit(7)


title: tickit_term(7)

summary: abstraction of an interactive terminal

text:
# tickit_term(7)

## NAME
TickitTerm - abstraction of an interactive terminal

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitTerm;
```

## DESCRIPTION
A TickitTerm instance represents an interactive user terminal. It provides functions to draw content to the terminal, and to accept input and other events from it. It supports a variety of modes of operation; allowing both synchronous and asynchronous filehandle IO, and working abstractly via byte buffers.

## FUNCTIONS
A new TickitTerm instance is created using the tickit_term_build(3). A terminal instance stores a reference count to make it easier for applications to manage the lifetime of terminals. A new terminal starts with reference count of one, and it can be adjusted using tickit_term_ref(3) and tickit_term_unref(3). When the count reaches zero the instance is destroyed.

The tickit_term_open_stdio(3) function offers a convenient shortcut to creating a new instance set up to represent the standard input and output streams of the process.

Once built the terminal startup actions are performed, and the tickit_term_await_started_msec(3) function can be used to wait until this is complete. A running instance can be paused using tickit_term_pause(3) and resumed using tickit_term_resume(3). It can be stopped entirely ahead of application termination by tickit_term_teardown(3).

It supports UTF-8 if enabled; either by detection of a UTF-8 locale, explicitly by calling tickit_term_set_utf8(3).

The size of the terminal can be queried using tickit_term_get_size(3), or forced to a given size by tickit_term_set_size(3). If the application is aware that the size of a terminal represented by a tty(7) filehandle has changed (for example due to receipt of a SIGWINCH signal), it can call tickit_term_refresh_size(3) to update it. The type of the terminal is set at construction time but can be queried later using tickit_term_get_termtype(3).

## OUTPUT
A terminal instance can be used for outputting drawing and other commands. For drawing, the functions tickit_term_print(3), tickit_term_goto(3), tickit_term_move(3), tickit_term_scrollrect(3), tickit_term_chpen(3), tickit_term_setpen(3), tickit_term_clear(3) and tickit_term_erasech(3) can be used. Additionally for setting modes, the function tickit_term_setctl_int(3) can be used. If an output buffer is defined it will need to be flushed when drawing is complete by calling tickit_term_flush(3).

## INPUT
Input via a filehandle can be received either synchronously by calling tickit_term_input_wait_msec(3), or asynchronously by calling tickit_term_input_readable(3) and tickit_term_input_check_timeout_msec(3). Any of these functions may cause one or more events to be raised by invoking event handler functions.

## EVENTS
A terminal instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_term_bind_event(3) and removed using tickit_term_unbind_event_id(3).

Fake events can be artificially injected into the event handler chain, as if they had been received from the controlling terminal, by tickit_term_emit_key(3) and tickit_term_emit_mouse(3). These may be useful for testing, event capture-and-replay, or other specialised cases.

The event types recognised are:

TICKIT_TERM_ON_DESTROY

The terminal instance is being destroyed.

TICKIT_TERM_ON_RESIZE

The terminal has been resized. info will point to a structure defined as:

```
typedef struct {
    int lines;
    int cols;
} TickitResizeEventInfo;

```

TICKIT_TERM_ON_KEY

A key has been pressed on the keyboard. info will point to a structure defined as:

```
typedef struct {
    TickitKeyEventType type;
    int mod;
    const char *str;
} TickitKeyEventInfo;

```

type is an enumeration that gives the specific type of key event.

TICKIT_KEYEV_KEY

a cursor control, arrow key, or function key. i.e. any of the keys that don't directly produce text.

TICKIT_KEYEV_TEXT

regular Unicode characters.

str will contain the name of the special key, including any applied modifiers, or a UTF-8 string of the Unicode character.

mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.

TICKIT_TERM_ON_MOUSE

A mouse button has been pressed or released, the mouse cursor moved while dragging a button, or the wheel has been scrolled. info will point to a structure defined as:

```
typedef struct {
    TickitMouseEventType type;
    int button;
    int mod;
    int line;
    int col;
} TickitMouseEventInfo;

```

type is an enumeration that gives the specific type of mouse event.

TICKIT_MOUSEEV_PRESS

A mouse button has been pressed.

TICKIT_MOUSEEV_DRAG

The mouse has been moved while a button is being held down.

TICKIT_MOUSEEV_RELEASE

A mouse button has been released.

TICKIT_MOUSEEV_WHEEL

The wheel has been rolled.

button gives the button index for button events, or one of TICKIT_MOUSEWHEEL_UP or TICKIT_MOUSEWHEEL_DOWN for wheel events.

line and col give the position of the mouse cursor for this event.

mod will contain a bitmask of TICKIT_MOD_SHIFT, TICKIT_MOD_ALT and TICKIT_MOD_CTRL.

This event only runs until a bound function returns a true value; this prevents later handler functions from observing it.

## CONTROLS
A terminal instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_term_setctl_int(3) and tickit_term_setctl_str(3), and queried using tickit_term_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_termctl_name(3) and searched by name using tickit_termctl_lookup(3). The type of a control option can be queried using tickit_termctl_type(3).

The options are given in an enumeration called TickitTermCtl. The following control values are recognised:

TICKIT_TERMCTL_ALTSCREEN (bool)

The value is a boolean indicating whether the terminal alternate buffer mode should be enabled. When enabled, a temporary buffer is used for drawing, preserving the original contents of the screen. This mode is usually used by full-screen applications to preserve the shell's scrollback state.

TICKIT_TERMCTL_COLORS (int, read-only)

The value indicates how many colors are available. This value is read-only; it can be requested but not set.

On terminfo-driven terminals this will likely be 8, 16, or 256. On xterm-like terminals this will be 16,777,216 (i.e. 1 << 24) if the driver detects that the terminal supports 24-bit RGB8 ("true-color") palettes, or 256 if not.

TICKIT_TERMCTL_CURSORBLINK (bool)

The value is a boolean indicating whether the terminal text cursor should blink. When disabled, the cursor will appear in a steady state, if visible. When enabled, the cursor will appear blinking, if visible. If the cursor is invisible, this should not have any effect.

TICKIT_TERMCTL_CURSORSHAPE (int)

The value is an integer from the TickitCursorShape enumeration indicating what shape the terminal's text cursor should be. Values are:

TICKIT_CURSORSHAPE_BLOCK

A solid block filling the entire cell.

TICKIT_CURSORSHAPE_UNDER

An underline below the character.

TICKIT_CURSORSHAPE_LEFT_BAR

A vertical bar to the left of the character.

Note that not all terminals support setting this option, nor to all of the possible values.

TICKIT_TERMCTL_CURSORVIS (bool)

The value is a boolean indicating whether the terminal text cursor should be visible. When disabled the cursor position is not visible. Typically applications will hide the cursor while performing redrawing operations so as not to show a flickering effect as the cursor moves, and show it again when drawing is complete.

TICKIT_TERMCTL_ICON_TEXT (str)

The value is a string for the terminal to use as its minimised icon text.

TICKIT_TERMCTL_ICONTITLE_TEXT (str)

The value is a string for the terminal to use as its minimised icon text and main window title.

TICKIT_TERMCTL_KEYPAD_APP (bool)

The value is a boolean controlling the terminal's keypad mode. When enabled, the terminal is in keypad application mode; in this mode the numerical keypad will send different sequences that can be detected as distinct from regular ASCII text. When disabled, the keypad will send normal text.

TICKIT_TERMCTL_MOUSE (int)

The value is an integer from the TickitTermMouseMode enumeration indicating what mouse events should be sent. Values are:

BTICKIT_TERM_MOUSEMODE_CLICK

Report button press and release events.

TICKIT_TERM_MOUSEMODE_DRAG

Report button press and release events, and movement while a button is held.

TICKIT_TERM_MOUSEMODE_MOVE

Report all button press, release and motion events even with no buttons held.

TICKIT_TERM_MOUSEMODE_OFF

Report nothing.

TICKIT_TERMCTL_TITLE_TEXT (str)

The value is a string for the terminal to use as its main window title.

## SEE ALSO
tickit(7), tickit_renderbuffer(7)


title: tickit_version(7)

summary: libtickit version queries

text:
# tickit_version(7)

## NAME
tickit_version_* - libtickit version queries

## SYNOPSIS

```
#define TICKIT_VERSION_MAJOR
#define TICKIT_VERSION_MINOR
#define TICKIT_VERSION_PATCH

int tickit_version_major(void);
int tickit_version_minor(void);
int tickit_version_patch(void);
```

## DESCRIPTION
These three macros provide the version numbers of the development header at compiletime. The related functions return the version numbers from the running library. Between them they can be used to check at program startup that the library version is suitable to support the running program.

## RETURN VALUE
Each tickit_version_*() function returns a version integer.

## SEE ALSO
tickit(7)


title: tickit_window(7)

text:
# tickit_window(7)

## NAME
TickitWindow - a window for drawing operations and input

## SYNOPSIS

```
#include <tickit.h>

typedef struct TickitWindow;
```

## DESCRIPTION
A TickitWindow instance represents a rectangular region of the screen. Windows are constructed as sub-divisions of existing windows, ultimately coming from a special "root window" is that represents the entire area of the terminal. Each window allows drawing to its region of the screen by responding to an event that signifies damage to that area that needs to be repainted, and has other events that represent user input.

A window occupies a given size and position within its parent (apart from the root window, which occupies the entire terminal). Conceptually a window can be placed outside of the bounds of its parent, though any drawing output is clipped to the parent (and its parent, hierarchially, all the way to the root). A window may be hidden, at which point none of its output affects the screen, nor will it receive input events.

The child windows of a given parent form an ordered list, the order of which can be modified. Drawing operations on a window only take effect if there are no higher siblings that would obscure it. The stacking order also affects the way that windows receive mouse events, with higher-level window shielding lower ones from receiving an event at a given cell.

Each window tracks whether a single child window has the "input focus"; this is the child window that will be informed of keyboard input events. The innermost window following the focus chain gets the first chance to react to the event, followed by successively outer ones if it remains unhandled.

Newly-exposed areas of windows are tracked by the root window, ready to be rendered by expose events. The root window itself will expose new areas caused by terminal resizes, and the entire root window is entirely exposed initially, to allow the application to run its initial rendering on startup. Each window stores a TickitPen instance that can be used to apply a default style to any rendering operations that take place within it or its children.

## FUNCTIONS
A new top-level TickitWindow instance to represent the entire terminal is created by calling tickit_get_rootwin(3) on the toplevel Tickit instance, further sub-divided into regions using tickit_window_new(3). A window instance stores a reference count to make it easier for applications to manage the lifetime of windows. A new window starts with a count of one, and it can be adjusted using tickit_window_ref(3) and tickit_window_unref(3). When the count reaches zero the instance is destroyed. A window can also be immediately removed from its parent with tickit_window_close(3).

The ancestry of a window can be queried using tickit_window_parent(3) and tickit_window_root(3). The stored child windows can be queried by using tickit_window_children(3) and tickit_window_get_children(3). The backing terminal can be queried with tickit_window_get_term(3).

The stacking order of a window among its siblings can be controlled using tickit_window_raise(3), tickit_window_raise_to_front(3), tickit_window_lower(3) and tickit_window_lower_to_back(3). Its visibility can be controlled using tickit_window_show(3) and tickit_window_hide(3), and queried using tickit_window_is_visible(3).

The position of a window within its parent can be queried using tickit_window_get_geometry(3) and within the terminal as a whole using tickit_window_get_abs_geometry(3). It can be resized using tickit_window_resize(3), moved using tickit_window_reposition(3), or both using tickit_window_set_geometry(3).

A window can be given the input focus using tickit_window_take_focus(3), and can be queried to see if it has the focus using tickit_window_is_focused(3). Windows normally only invoke focus events about themselves, but can be made to invoke events about children windows as well by using tickit_window_set_focus_child_notify(3). When a window has the input focus, the properties of the terminal cursor can be set using tickit_window_set_cursor_position(3), tickit_window_set_cursor_visible(3) and tickit_window_set_cursor_shape(3).

The TickitPen instance associated with each window for drawing purposes can be obtained using tickit_window_get_pen(3), and replaced using tickit_window_set_pen(3). This pen is used during expose events, which can be requested using tickit_window_expose(3). Pending expose events and other activity are performed by calling tickit_window_flush(3) on the root window instance.

While most drawing operations are performed in a deferred manner using expose events, scrolling of the terminal content can be directly requested using tickit_window_scrollrect(3), tickit_window_scroll(3) or tickit_window_scroll_with_children(3).

## EVENTS
A window instance stores a list of event handlers. Each event handler is associated with one event type and stores a function pointer, and an arbitrary pointer containing user data. Event handlers may be installed using tickit_window_bind_event(3) and removed using tickit_window_unbind_event_id(3).

The event types recognised are:

TICKIT_WINDOW_ON_DESTROY

The window instance is being destroyed.

TICKIT_WINDOW_ON_KEY

A key has been pressed on the keyboard while this window has input focus (or is set to steal input). info will point to a structure defined the same as the TICKIT_EV_KEY event described in tickit_term(7).

TICKIT_WINDOW_ON_MOUSE

A mouse button has been pressed or released, the mouse cursor moved while dragging a button, or the wheel has been scrolled while the cursor is within the bounds of this window (or the window is set to steal input), or certain kinds of mouse dragging behaviour have happened. info will point to a structure defined the same as the TICKIT_EV_MOUSE event described in tickit_term(7), except that the position given by the line and col fields will be relative to the window, rather than the terminal as a whole.

In addition to the basic mouse events found at the terminal layer, there are a few additional kinds of events that occur during mouse dragging. These give information about mouse drag motions within a window or between different windows.

TICKIT_MOUSEEV_DRAG_START

A dragging motion has started. This event is delivered just before the TICKIT_MOUSEEV_DRAG event, and gives the original position of the mouse before it started dragging (i.e. the position of the press event).

TICKIT_MOUSEEV_DRAG_OUTSIDE

A dragging motion that was started within this window has now moved outside it. In this case, the position given by the event will be somewhere outside the bounds of the window it is delivered to. This event is delivered directly to the source window; i.e. the window that handled the TICKIT_MOUSEEV_DRAG_START event.

TICKIT_MOUSEEV_DRAG_DROP

A dragging motion has stopped by the mouse button being released. This event is delivered normally at the position of the mouse cursor.

TICKIT_MOUSEEV_DRAG_STOP

A dragging motion has stopped by the mouse button being released. This event is delivered directly to the source window; i.e. the window that handled the TICKIT_MOUSEEV_DRAG_START event. If that is a different window than the one that received the TICKIT_MOUSEEV_DRAG_STOP event then the position may be outside the bounds of the window.

TICKIT_WINDOW_ON_GEOMCHANGE

At least one of the fields of the window geometry have been changed, meaning it now occupies a different area of the screen. info will point to a structure defined as:

```
typedef struct {
    TickitRect rect;
    TickitRect oldrect;
} TickitGeomchangeEventInfo;

```

rect gives the new geometry of the window relative to its parent, and oldrect gives the previous geometry.

TICKIT_WINDOW_ON_EXPOSE

An area of the window needs to be re-rendered because it has now been freshly exposed; either because of stacking or visibility changes of this or sibling windows, a cascaded expose event on its parent, or due to a call to tickit_window_expose(). info will point to a structure defined as:

```
typedef struct {
    TickitRect rect;
    TickitRenderBuffer *rb;
} TickitExposeEventInfo;

```

rect gives the region of the window that needs to be redrawn. This will always be inside the window's bounds. If multiple pending regions need to be exposed, they are output in non-overlapping segments. The handling function or functions should then use the TickitRenderBuffer instance given by the rb field to draw the required contents of the window to. This instance will already be set up with the appropriate drawing pen, clipping rectangle and hole regions to account for the window hierarchy.

TICKIT_WINDOW_ON_FOCUS

This window has either gained or lost the input focus, or a child of it has an this window is set to also notify on that case by using tickit_window_set_focus_child_notify(). info will point to a structure defined as:

```
typedef struct {
    TickitFocusEventType type;
    TickitWindow *win;
} TickitFocusEventInfo;

```

type takes onw of the values TICKIT_FOCUSEV_IN or TICKIT_FOCUSEV_OUT. win will normally be the window that is invoking the event, except for the case of notifications about child windows, where it will indicate which child has changed focus. When a focus change happens, the window losing focus receives its TICKIT_FOCUSEV_OUT event before the window gaining it receives its TICKIT_FOCUSEV_IN.

## CONTROLS
A window instance has a number of runtime-configuration control options that affect its behaviour. These can be set using tickit_window_setctl_int(3), and queried using tickit_window_getctl_int(3). The individual controls have human-readable string names that can be obtained by tickit_windowctl_name(3) and searched by name using tickit_windowctl_lookup(3). The type of a control option can be queried using tickit_windowctl_type(3).

The options are given in an enumeration called TickitWindowCtl. The following control values are recognised:

TICKIT_WINCTL_CURSORBLINK (bool)

The value is a boolean indicating whether the terminal text cursor should blink while this window has the input focus.

TICKIT_WINCTL_CURSORSHAPE (int)

The value is an integer from the TickitCursorShape enumeration indicating what shape the terminal's text cursor should be while this window has the input focus. Values are:

TICKIT_CURSORSHAPE_BLOCK

A solid block filling the entire cell.

TICKIT_CURSORSHAPE_UNDER

An underline below the character.

TICKIT_CURSORSHAPE_LEFT_BAR

A vertical bar to the left of the character.

TICKIT_WINCTL_CURSORVIS (bool)

The value is a boolean indicating whether the terminal text cursor should be visible while this window has the input focus.

TICKIT_WINCTL_FOCUS_CHILD_NOTIFY (bool)

The value is a boolean indicating whether the window will receive TICKIT_EV_FOCUS events when its child windows change focus states (when true), or whether the only focus events it will receive are ones relating to itself directly (when false).

TICKIT_WINCTL_STEAL_INPUT (bool)

The value is a boolean indicating whether the window will receive all key events on its parent first, while it is the front-most child of its parent, even before the sibling that actually has input focus receives them. Additionally, the window will receive all mouse events, even those outside of its geometry. This option is useful when implementing popup windows such as menu bars.

## SEE ALSO
tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_rect(7)


ecpp

package: libtntnet-devel

title: ecpp(7)

summary: template\-language for

text:
# ecpp(7)

## NAME
ecpp - template-language for tntnet(8)

## DESCRIPTION
ecpp is the template-language used by the tntnet-system to generate dynamic content.

A template consists of normal content (normally html-data) enriched with special tags, which trigger some special handling.

One ecpp-file is compiled into a C++-class. The C++-class is placed into the namespace component. A ecpp-file compiled into a C++-class is called component. The name of the class is the basename of the file.

### request, reply, qparam
Each component has 3 parameters: request, reply and qparam. request holds information about the client-request like http headers and the url, but also additional parameters specified in the config-file tntnet.xml(7). The type of request is tnt::HttpRequest.

reply receives the answer from the component. The component can set additional http-headers here, set cookies and - most important - generate output. The most important methods here are reply.out() and reply.sout(). Both return a std::ostream, which receives the output of the component. reply.sout() has a filter installed, which translates some characters, whith special meanings in html to the corresponding html-entities. The characters are <, >, &, " and '. This is useful for printing values from variables to the html-code.

qparam holds the query-parameters parsed from GET- or POST-parameters or received from other components. The type of qparam is tnt::query_params. Normally you use a <%args>-block to specify the parameters, but there are special cases, where it is useful to access these directly.

### component adressing
Each component has a unique name. The name is composed from the class-name, the character '@' and the name of the shared library, it is located. Components can have internal subcomponents. The name of the internal subcomponent is appended to the classname separated by a dot (.).

### special rule for line feeds after a </%something>-tag
A line feed immediately after a closing tag for all <%something>-blocks are ignored. Hence blocks followed immediately one after another does not generate white space in output, which is often undesirable.

### error-handling
Error-handling is done by exception. Tntnet catches all exceptions thrown by components and handles them properly. Exceptions must be derived from std::exception. Exceptions derived from tnt::HttpError, are handled separately. They carry a http-return-code, which is sent to the client. Other exceptions derived from std::exception, result in a http error code 500 (Internal Server Error).

## TAGS
<$ expr $>

Print expressions expr to the outputstream. The characters <, >, &, " and ', which have special meanings in html, are translated to the corresponding html-entities.

<$$ expr $>

Print expressions expr without translating characters with special meaning in html to html entities to the output stream.

<? cond ? expr ?>

Conditional output. Print expression expr to the outputstream, if cond evaluates to true. Characters with special meaning in html are translated to the corresponding html-entities.

<?? cond ? expr ?>

Conditional output. Print expression expr to the outputstream, if cond evaluates to true. Characters with special meaning in html are not translated to the corresponding html-entities.

<& component [ arguments ] >

Call the specified component. The output of the component is printed into the outputstream. If the component-name does not start with a letter, the ecpp-compiler treats it as a expression, which returns the name of the component. You must surround the expression in brackets, if it contains spaces.

The arguments-part specify the parameters, the component will receive. Arguments are name-value-pairs separated by '='. They are put in the qparam-parameter of the component and are normally declared in the <%args>-block. Values can be specified in 3 forms:

As a plain word without spaces

As a string enclosed in quotation marks

As a expression enclosed in brackets

A single plain word in the argumentlist is treated as a variable of type cxxtools::query_params and a copy is passed to the component. Other parameters are added to this copy. If you want to pass all parameters of the current component put the variable qparam as a plain word in the argument list.

</&component>

Closing-tag for a component-call. When components are called, this closing-tag might occur later. The code in <%close>-block is placed here.

<{...}>

C++-inline-processing-block. The code in this block is copied into the C++-class unchanged.

A linefeed after the closing tag is not ignored.

<#...#>

Comment-block. Everything in this block is ignored.

<%application [ scope="component|page|global" ] >...</%application>

Variables defined here, have the lifetime of the application.

Application-scope is automatically locked.

<%args>...</%args>

Defines GET- or POST-parameters recieved by the component.

Each argument has a name and optionally a defaul-value. The default-value is delimited by '=' from the name. A single argument-definition followed by a semicolon (;). In the component a variable with the same name of type std::string is defined, which receives the value.

A argument-name can be prefixed by a type-definition. The ecpp-compiler generates code, which tries to convert the value with the input-stream-operator. This means, that each type, which can be read from a input-stream (std::istream) can be used. If the argument can't be converted, a exception is thrown.

Argumentnames can be postfixed by empty square-brackets. This defines a std::vector with the specified type or std::string, if no type is specified. This way multiple values with the same name can be received. If a type is specified, each value is converted to the target-type.

<%close>...</%close>

Code in these tags is placed into the calling component, when a closing tag </&component> is found.

The <%close> receives the same parameters like the corresponding normal component call.

<%config>...</%config>

Often webapplications need some configuration like database-names or login-information to the database. These configuratioin-variables can be read from the tntnet.xml. Variablenames ended with a semicolon are defined as static std::string-variables and filled from tntnet.xml. A variable can be prepended by a type. The value from tntnet.xml is then converted with a std::istream.

You can also specify a default value by appending a '=' and the value to the variable.

Example:

```
<%config>

  dburl = "sqlite:db=mydbfile.sqlite";

  int maxvalue = 10;
</%config>
```

tntnet.xml:

<dburl>postgresql:dbname=mydb</dburl>

<%cpp>...</%cpp>

C++-processing-block. The code between these tags are copied into the C++-class unchanged.

A linefeed after the closing tag is ignored.

<%def name>...</%def>

Defines a internal subcomponent with the name name, which can be called like other components.

<%doc>...</%doc>

Comment-block. Everything in this block is ignored.

A linefeed after the closing tag is ignored.

<%get>...</%get>

Works like a <%args> block but receives only GET parameters.

<%i18n>...</%i18n>

Encloses a block of text-data, which is to be translated. See ecppl(1) and ecppll(1) for details.

<%include>filename</%include>

The specified file is read and compiled.

<%param>...</%param>

Defines parameter received from calling components. In contrast to query-parameters these variables can be of any type. The syntax (and the underlying technology) is the same like in scoped variables. See the description about scoped variables to see how to define parameters. The main difference is, that a parameter variable has no scope, since the parameter is always local to the component.

<%out> expr </%out>

Same as <$$ ... $>. Prints the contained C++ expression expr.

<%post>...</%post>

Works like a <%args> block but receives only POST parameters.

<%pre>...</%pre>

Defines C++-code, which is placed outside the C++-class and outside the namespace-definition. This is a good place to define #include-directives.

<%request [ scope="component|page|global" ] >...</%request>

Define request-scope variables. Variables defined here, has the lifetime of the request.

<%session [ scope="component|page|global" ] >...</%session>

Variables defined here, has the lifetime of the session.

Sessions are identified with cookies. If a <%session>-block is defined somewhere in a component, a session-cookie is sent to the client.

Sessions are automatically locked.

<%securesession [ scope="component|page|global" ] >...</%securesession>

Secure session is just like session but a secure cookie is used to identify the session. Secure cookies are transfered only over a ssl connection from the browser and hence the variables are only kept in a ssl secured application.

If a variable defined here is used in a non ssl page, the variable values are lost after the current request.

<%sout> expr </%sout>

Same as <$ ... $>. Prints the contained C++ expression expr. The characters <, >, &, " and ', which have special meanings in html, are translated to the corresponding html-entities.

<%thread [ scope="component|page|global" ] >...</%thread>

Variables defined here, has the lifetime of the thread. Each thread has his own instance of these variables.

Thread-scope-variables do not need to be locked at all, because they are only valid in the current thread.

## SCOPED VARIABLES
Scoped variables are c++-variables, whose lifetime is handled by tntnet. These variables has a lifetime and a scope. The lifetime is defined by the tag, used to declare the variable and the scope is passed as a parameter to the tag.

There are 5 different lifetimes for scoped variables:

request

The variable is valid in the current request. The tag is <%request>.

application

The variable is valid in the application. The tag is <%application>. The application is specified by the shared-library of the top-level component.

session

The variable is valid for the current session. The tag is <%session>. If at least session-variable is declared in the current request, a session-cookie is sent to the client.

thread

The variable is valid in the current thread. The tag is <%thread>.

param

The variable receives parameters. The tag is <%param>.

And 3 scopes:

component

The variable is only valid in the same component. This is the default scope.

page

The variable is shared between the components in a single ecpp-file. You can specify multiple internal subcomponents in a %def-block. Variables, defined in page-scope are shared between these subcomponents.

global

Variables are shared between all components. If you define the same variable with global-scope in different components, they must have the same type. This is achieved most easily defining them in a separate file and include them with a <%include>-block.

Variables are automatically locked as needed. If you use session-variables, tntnet ensures, that all requests of the same session are serialized. If you use application-variables, tntnet serializes all requests to the same application-scope. Request- and thread-scope variables do not need to be locked at all, because they are not shared between threads.

### Syntax of scoped variables
Scoped variables are declared with exactly the same syntax as normal variables in c++-code. They can be of any type and are instantiated, when needed. Objects, which do not have default constructors, need to be specified with proper constructor-parameters in brackets or separated by '='. The parameters are only used, if the variable need to be instantiated. This means, that parameters to e.g. application-scope variables are only used once. When the same component is called later in the same or another request, the parameters are not used any more.

### Examples
Specify a application-specific global variable, which is initialized with 0:

```
<%application>
unsigned count = 0;
</%application>
```

Specify a variable with a user-defined type, which holds the state of the session:

```
<%session>
MyClass sessionState;
</%session>
```

Specify a persistent databaseconnection, which is initialized, when first needed and hold for the lifetime of the current thread. This variable may be used in other components:

```
<%thread scope="global">
tntdb::Connection conn(dburl);
</%thread>
```

## AUTHOR
This manual page was written by Tommi Mäkitalo tommi@tntnet.org.

## SEE ALSO
tntnet(1), ecppc(1)


title: tss2-tcti-cmd(7)

summary: TPM2 Sub-process Command TCTI library

text:
# tss2-tcti-cmd(7)

## NAME
tcti-cmd - TPM2 Sub-process Command TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with a sub-process.

## DESCRIPTION
tcti-cmd is a library that abstracts the details of direct communication with the interface and protocol exposed by a sub-process that can receive and transmit raw TPM2 command and response buffers. The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification.

## EXAMPLES
For example, if you wanted to use the tpm2_send(1) command as the sub-process to send data to and from the TPM, one could do so like this:

```
tpm2_getrandom -T "cmd:tpm2_send -s" --hex 4
```

A more useful example would be connecting to a remote machine using ssh and interacting with the remote machine's TPM as if it were local. This uses tpm2_send(1) on a remote machine and uses ssh as the sub-process to create the tunnel to the remote machine. If encrypted sessions are used, the remote machine is blinded to the TPM data and cannot interpose on that traffic.

```
tpm2_getrandom -T "cmd:ssh remotehost tpm2_send" -s --hex 4
```

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-device(7)

summary: device driver TCTI library

text:
# tss2-tcti-device(7)

## NAME
tcti-device - device driver TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with the TPM device driver.

## DESCRIPTION
tcti-device is a library that abstracts the details of direct communication with the device node exposed by the Linux kernel driver (typically /dev/tpm0). The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-i2c-ftdi(7)

summary: USB to I2C-based TPM TCTI library

text:
# tss2-tcti-i2c-ftdi(7)

## NAME
tcti-i2c-ftdi - USB to I2C-based TPM TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with a I2C-based TPM over the FTDI MPSSE USB to I2C bridge.

## DESCRIPTION
tcti-i2c-ftdi is a library that abstracts the details of communication with a I2C-based TPM over the FTDI MPSSE USB to I2C bridge. The interface exposed by this library is defined in the “TSS System Level API and and TPM Command Transmission Interface Specification” specification.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-i2c-helper(7)

summary: device driver TCTI library

text:
# tss2-tcti-i2c-helper(7)

## NAME
tcti-i2c-helper - device driver TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for communication via I2C. TPM device driver.

## DESCRIPTION
tcti-i2c-helper is a library that abstracts the details of communication with a TPM via I2C protocol. It uses user supplied methods for I2C and timing operations in order to be platform independent. These methods are supplied to `Tss2_Tcti_I2c_Helper_Init` via the `TSS2_TCTI_I2C_HELPER_PLATFORM` struct.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-mssim(7)

summary: TPM simulator TCTI library

text:
# tss2-tcti-mssim(7)

## NAME
tcti-socket - TPM simulator TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with the Microsoft TPM2 simulator.

## DESCRIPTION
tcti-socket is a library that abstracts the details of direct communication with the interface and protocol exposed by the daemon hosting the TPM2 reference implementation. The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-spi-ftdi(7)

summary: USB to SPI-based TPM TCTI library

text:
# tss2-tcti-spi-ftdi(7)

## NAME
tcti-spi-ftdi - USB to SPI-based TPM TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with a SPI-based TPM over the FTDI MPSSE USB to SPI bridge.

## DESCRIPTION
tcti-spi-ftdi is a library that abstracts the details of communication with a SPI-based TPM over the FTDI MPSSE USB to SPI bridge. The interface exposed by this library is defined in the “TSS System Level API and and TPM Command Transmission Interface Specification” specification.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-spi-helper(7)

summary: device driver TCTI library

text:
# tss2-tcti-spi-helper(7)

## NAME
tcti-spi-helper - device driver TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for communication via SPI. TPM device driver.

## DESCRIPTION
tcti-spi-helper is a library that abstracts the details of communication with a TPM via SPI protocol. It uses user supplied methods for SPI and timing operations in order to be platform independent. These methods are supplied to `Tss2_Tcti_Spi_Init` via the `TSS2_TCTI_SPI_PLATFORM` struct.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-spi-ltt2go(7)

summary: LetsTrust-TPM2Go USB TPM TCTI library

text:
# tss2-tcti-spi-ltt2go(7)

## NAME
tcti-spi-ltt2go - LetsTrust-TPM2Go USB TPM TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with the LetsTrust-TPM2Go USB TPM.

## DESCRIPTION
tcti-spi-ltt2go is a library that abstracts the details of communication with the LetsTrust-TPM2Go USB TPM. The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-spidev(7)

text:
# tss2-tcti-spidev(7)

## NAME
tcti-spidev - TCTI library for accessing TPMs via spidev

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with a TPM that is attached to an spidev device node.

## DESCRIPTION
tcti-spidev is a library that abstracts the details of communication with a TPM that is attached to an spidev device node.. The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification. The configuration of this TCTI takes the filepath to the device node (Default: /dev/spidev0.1).

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tcti-swtpm(7)

summary: TPM simulator TCTI library

text:
# tss2-tcti-swtpm(7)

## NAME
tcti-swtpm - TPM simulator TCTI library

## SYNOPSIS
A TPM Command Transmission Interface (TCTI) module for interaction with the TPM2 software simulator.

## DESCRIPTION
tcti-swtpm is a library that abstracts the details of direct communication with the interface and protocol exposed by the daemon hosting the TPM2 reference implementation. The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification” specification.

## NOTES
It is best not to use the CUSE interface when setting up swtpm, but rather to use the vtpm module proxy:

```
modprobe tpm_vtpm_proxy
swtpm chardev --vtpm-proxy --tpmstate dir=... --tpm2 ...
```

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.


title: tss2-tctildr(7)

text:
# tss2-tctildr(7)

## NAME
tss2-tctildr - Simplifiy management of TCTI instance lifecycle.

## SYNOPSIS
This library simplifies the instantiation and finalization of TCTI instances.

## DESCRIPTION
The TCTI dynamic loading and initialization protocol requires a lot of boilerplate code. To reduce duplication the tss2-tctildr library adds the Tss2_TctiLdr_Initialize(), Tss2_TctiLdr_Initialize_Ex(), and Tss2_TctiLdr_Finalize() functions to abstract away the machinery required to load, initialize, and finalize a TCTI context.

To assist in the discovery of TCTIs this library provides the Tss2_TctiLdr_GetInfo() function. This function, paired with a ‘free’ function to free the memory allocated by ‘GetInfo’, provides a simple query interface for discovery of the available and default TCTIs available to the tss2-tctildr implementation

The interface exposed by this library is defined in the “TSS System Level API and TPM Command Transmission Interface Specification”.

## AUTHOR
TPM2 Software Project <https://github.com/tpm2-software/tpm2-tss>

## SEE ALSO
Tss2_Tcti_Device_Init(3), Tss2_Tcti_Socket_Init(3), Tss2_TctiLdr_Initialize(3), Tss2_TctiLdr_Finalize(3), tcti-device(7), tcti-socket(7), tcti-tabrmd(7), tpm2-abrmd(8)

## COLOPHON
This page is part of release 4.1.3 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.