Classes

The Application class is responsible for running your application.

The Application class has at least one TopLevel view that is displayed (and is the one pointed to by top) and will send events to this instance. You should add your views to this top instance. A minimal initialization sequence looks like this:

 Application.prepare ()
 let win = Window()
 win.fill ()
 Application.top.addSubview (win)
 Application.run()

The call to the prepare method initializes the default console driver, which will be set depending on your platform and heuristics (currently it is limited to the curses version).

Then you need to add one or more views to your application, in the example above, a new Window is created, we flag it to take over all the available space by calling the fill method, and then we add this to the top element. Once this happens, we call Application.run which is a method that will never return.

# TopLevels At any given point there is only a single Toplevel instance active, this means that all mouse and keyboard events are routed here. There might be multiple visible Toplevel at any given point, for example the main application is a Toplevel, and a popup dialog box is another form of a toplevel. When the popup is executing, all keyboard and mouse input are routed to the dialog box, but the main Toplevel will still be updated visually and might also be updated continously.

To execute a new nested toplevel, one that either obscures a portion of the screen, or the whole screen, you call the present method with the new instance. To pop the toplevel from the stack, you call the Application.requestStop method which will queue the toplevel for termination and will make the previous toplevel the active one.

# Main Loop Execution Calling the present method in Application will start the mainloop, which is implemented using the Dispatch framework. This means that this method will never return, but also that all the operations that you have come to expect from using the Dispatch API (from Grand Central Dispatch) will work as expected.

The TermKit framework is not multi-thread safe, so any operations that you execute on the background should queue operations that access properties, or call methods in any of the TermKit methods using the global queue, so that the operation is executed in the context of the TermKit queue.

See more

public class Application

Undocumented

See more

public class MarkupView : View

AttributedString offers a simple way to markup strings to annotate them with terminal attributes and colors.

A convenient init (markup:) method is provided to create these easily using a simple markup system, inspired by the Spectre.Console markup, which is in turn inspired by BBCode. Unlike BBCode, does not use the word on the closing tag, it merely auto-closes.

See more

public class AttributedString : CustomDebugStringConvertible

Clipboard is a simple interface to share data across views

See more

public class Clipboard

Describes a dimension which can be an absolute value, a percentage, fill, or a reference to a dimension of another view

To create a Dim object, you can choose from one of the following options:

• Dim.sized(n) creates an absolute dimension of size n
• Dim.percent(n) creates a dimension that reprensents the n% of the container
• Dim.fill(margin) creates a dimension that fills to the end of the container dimension, leaving the specified margin on the side
• Dim.width(view) and Dim.heigh(view) are used to reference the computed width or height of another view.

Dim objects can be combined using the addition and substraction operators to create various rules, like for example:

 password.width = Dim.width(login) - Dim(4)

See more

public class Dim

Undocumented

See more

public class Layer

The drawing context tracks the cursor position, and attribute in use during the View’s draw method, it enforced clipping on the view bounds.

Instances of this class are passed to a View‘s redraw method to paint

See more

public class Painter

Describes a position which can be an absolute value, a percentage, centered, or relative to the ending dimension. Integer values are implicitly convertible to an absolute Pos. These objects are created using the static methods percent, anchorEnd and center. The Pos objects can be combined with the addition and subtraction operators.

Use the Pos objects on the x or y properties of a view to control the position.

These can be used to set the absolute position, when merely assigning an integer value (via the implicit integer to Pos conversion), and they can be combined to produce more useful layouts, like: pos.center - 3, which would shift the postion of the view 3 characters to the left after centering for example.

It is possible to reference coordinates of another view by using the methods left(of: view), right(of: view), bottom(of: View), top(of: View). The x(of: View) and y(of: View) are aliases to left(of: View) and top(of: View) respectively.

Examples:

 label = Label ("Hello world")
 label.x = Pos.at (10)        // at column 10
 label.y = Pos.percent (50)   // At 50%
 label.x = Pos.center ()      // center position
 // Center relative to another label
 label.x = Pos.center () - Dim.width(anotherLabel)

See more

public class Pos

Toplevel views provide both the basic keyboard navigation between views using cursor keys and tab keys and they also contain the drawing backing store for views that are added to it.

Toplevels are the views that are expected to be passed to Application.present to be rendered. It introduces an independent rendering chain, in addition to the View rendering chain.

Calling Application.requestStop will remove the last Toplevel from the execution stack, redrawing the screen contents if necessary.

There will be a toplevel created for you on the first time use and can be accessed from the property Application.top but new toplevels can be created and ran on top of it. To run, create the toplevel and then invoke `Application.run with the new toplevel.

To make a toplevel modal, set the modal property to true, this will prevent keyboard and mouse events to go to a previous toplevel.

See more

open class Toplevel : View

View is the base class for all views on the screen and represents a visible element that can render itself and contains zero or more nested views.

The View defines the base functionality for user interface elements in TermKit. Views can contain one or more subviews, can respond to user input and render themselves on the screen.

Views can either be created with a constructor that takes a Rect as the frame to used for the view, which means that the view is using the .fixed LayoutStyle, or with the empty construtor, and then setting the x, y, width and height properties on the view which configures the view to use the .computed layout style.

The view layout system can be controlled by accessing the layoutStyle property, and is used to transition from the fixed to the computed mode.

The x, and y properties are of type Pos, and you can use either absolute positions, percentages or anchor points.

The width and height properties are of type Dim and can use absolute position, percentages and anchors. These are useful as they will take care of repositioning your views if your view’s frames are resized or if the terminal size changes

Subviews can be added to a View by calling the addSubview method. The container of a view is the Superview.

Developers can call the setNeedsDisplay method on the view to flag a region or the entire view as requiring to be redrawn.

Views have a ColorScheme property that defines the default colors that subviews should use for rendering. This ensures that the views fit in the context where they are being used, and allows for themes to be plugged in. For example, the default colors for windows and toplevels uses a blue background, while it uses a white background for dialog boxes and a red background for errors.

If a ColorScheme is not set on a view, the result of the ColorScheme is the value of the SuperView and the value might only be valid once a view has been added to a SuperView, so your subclasses should not rely on ColorScheme being set at construction time.

Using ColorSchemes has the advantage that your application will work both in color as well as black and white displays.

Views that are focusable should implement the positionCursor to make sure that the cursor is placed in a location that makes sense. Unix terminals do not have a way of hiding the cursor, so it can be distracting to have the cursor left at the last focused view. So views should make sure that they place the cursor in a visually sensible place.

The metnod layoutSubviews is invoked when the size or layout of a view has changed. The default processing system will keep the size and dimensions for views that use the LayoutKind.Absolute, and will recompute the frames for the vies that use LayoutKind.Computed.

See more

open class View : Responder, Hashable, CustomDebugStringConvertible

A toplevel view that draws a frame around its region and has a “ContentView” subview where the contents are added. with an optional title that is displayed at the top

See more

public class Window : Toplevel

The dialog box is a window that by default is centered and contains one or more buttons, it defaults to the Colors.dialog color scheme and has a 1 cell padding around the edges.

To run the dialog modally, create the Dialog, and pass this to Application.run which will execute the dialog until it terminates via the [ESC] key, or when one of the views

See more

public class Dialog : Window

Base class for the OpenDialog and SaveDialog, use one of those subclasses.

See more

public class FileDialog : Dialog

The SaveDialog provides an interactive dialog box for users to pick a file to save.

To use, create an instance of SaveDialog, and call present with a callback for completion. Then you can examine the fileName property, that will contain the selected file name ornil if the user canceled.

See more

public class SaveDialog : FileDialog

The OpenDialog provides an interactive dialog box for users to select files or directories.

The open dialog can be used to select files for opening, it can be configured to allow multiple items to be selected (based on the allowsMultipleSelection) variable and you can control whether this should allow files or directories to be selected. To use, create an instance of OpenDialog, and pass it to Application.present. When complete, the list of files will be available in the `filePaths property.

To select more than one file, users can use the spacebar, or control-t.

See more

public class OpenDialog : FileDialog

Message box displays a modal message to the user, with a title, a message and a series of options that the user can choose from.

There are a couple of options:

• query is used to show a message with buttons
• error is similar to query, but uses the error color scheme for the dialogs
• info merely takes a title and message, it is informational only, so the button “ok” is added

The following example pops up a Message Box with 50 columns, and 7 lines, with the specified title and text, plus two buttons. The value -1 is returned when the user cancels the dialog by pressing the ESC key.

See more

public class MessageBox

Color scheme definitions, cover the four colors that are typically needed by views in a console applications to display text and show the focused state. They include the regular attribute (normal), the attribute used when the view is focused (focus) and the attributes use to highlight the hotkeys in a view both in normal mode and focused mode.

See more

public class ColorScheme

The default ColorSchemes for the application, there are settngs for four different common scenarios: base is the set of colors that is used for most of your application UI. dialog is the color scheme that is used for popup dialogs, usually they offer some contrast over the default colors; menu is used for the top-level menus, and error is intended to have a set of attributes suitable to display error messages.

See more

public class Colors

Base class for implementing text drivers.

Currently there is a Curses implementation, but an implementation that does not rely on Curses and that purely uses Terminfo would be desirable, as well as a Windows console one

See more

public class ConsoleDriver

Button is a view that provides an item that invokes a callback when activated.

Provides a button that can be clicked, or pressed with the enter key or space key. It also responds to hotkeys (the first letter after an underscore) and triggers the execution of a callback method.

If the button is configured as the default IsDefault the button will respond to the return key is no other view processes it, and turns this into a clicked event.

To connect a clicked handler, set the clicked property here to your callback

 var d = Dialog("_Hello")
 var ok = Button ("Ok")
 ok.clicked = { d.requestStop () }
 d.addButton (ok)
 Application.run (d)

See more

public class Button : View

The Checkbox View shows an on/off toggle that the user can set

Example:

 c = Checkbox ("Toggle me")
 c.x = Pos.at (0)
 c.y = Pos.at (0)
 c.width = Dim(30)
 c.height = Dim (1)
 c.toggled = { check in ... }

 // Alternatively, you can use Combine to track the event changes:
 var cancellable = c.toggledSubject.sink { cbox in }

See more

public class Checkbox : View

Undocumented

See more

public class Desktop : View

The FrameView is a container frame that draws a frame around the contents

See more

public class Frame : View

Label view, displays a string at a given position, can include multiple lines.

When labels are initiallly created, they compute a default width and height, and additional changes to the configuration of the label (the text, the lineBreak, the text alignemtn) will not automatically change that. You must call autoSize() if you want to change those parameters.

See more

public class Label : View

Label view, displays a string at a given position, can include multiple lines.

See more

public class Label3 : View

ListView is a control used to displays rows of data.

# Initialization: The ListView offers both easy to use, as well as customizable options for the data being rendered. For very simple scenarios there is a constructor that takes an array of strings, and provides a way of rendering those, and selecting those (the selection can be retrieved through the API).

If you desire to customize the rendering of the data, or if your data is not a string, a separate constructor takes both a ListViewDataSource instance, which is used to describe your information to display, as well as a rendering method that is invoked to render every line on demand and is expected to return a string, which is in turn rendered.

A more advanced method requires both the datasource and the delegate to be specified, in this scenario, you can control directly how the contents of your data source are rendered.

To scroll to a particular place, you can set the “topItem” property

See more

public class ListView : View

A menu bar item contains either MenuBarItem or MenuItem

See more

public class MenuBarItem

Menus are views displayed vertically that contain various menu items, and are attached to a menubar.

See more

public class Menu : View

A menubar for your application, defaults to be at the top of its container.

See more

public class MenuBar : View

Progress bar can indicate progress of an activity visually.

The progressbar can operate in two modes, percentage mode, or activity mode. The progress bar starts in percentage mode and setting the fraction property will reflect on the UI the progress made so far. Activity mode is used when the application has no way of knowing how much time is left, and is started when you invoke the Pulse() method. You should call the pulse method repeatedly as your application makes progress.

See more

public class ProgressBar : View

Undocumented

See more

public class RadioGroup : View

ScrollBarViews are views that display a 1-character scrollbar, either horizontal or vertical

The scrollbar is drawn to be a representation of the Size, assuming that the scroll position is set at position

If the region to display the scrollbar is larger than three characters, arrow indicators are drawn.

See more

public class ScrollBarView : View

Scrollviews are views that present a window into a virtual space where subviews are added. Similar to the iOS UIScrollView.

The subviews that are added to this Gui.ScrollView are offset by the `contentOffset property. The view itself is a window into the space represented by the contentSize

See more

public class ScrollView : View

Undocumented

See more

public class StatusBar : View

The terminal captures almost all input, if you want to send a command to the toolkit, you can use Control-Q which will quote the next keystroke, and will instead be prcessed by TermKit.

See more

public class TerminalView : View, TerminalDelegate

Undocumented

See more

public class LocalProcessTerminalView : TerminalView, LocalProcessDelegate, TerminalViewDelegate

Single-line text entry View

This view provides line-editing and mouse support

See more

public class TextField : View

Multi-line text editing view

The text view provides a multi-line text view. Users interact with it with the standard Emacs commands for movement or the arrow keys.

Navigation:

• Move left: left cursor, or Control-B
• Move right: right cursor key, or Control-F
• Move one page down: Page Down or Control-V
• Move one page up: Page Up or Alt-V
• Move to the beginning of the line: Home key or Control-A
• Move to the end of the line: End key or Control-E

Editing:

• Backspace key: removes the previous character
• Delete character: Delete Key or Control-D
• Delete to the end-of-line: Control-K, appends contents to the clipboard
• Delete line at the end of the line: Control-K, appends content to the clipboard
• Paste contents of copy buffer: Control-Y

Selection:

• Start selectrion: Control-Space
• Copy selection to clipboard: Alt-W
• Cut selection to clipboard: Control-W

See more

public class TextView : View