Application

public class Application

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.

  • top

    The Toplevel object used for the application on startup.

    Declaration

    Swift

    public static var top: Toplevel { get }
  • The current toplevel object. This is updated when Application.Run enters and leaves and points to the current toplevel.

    Declaration

    Swift

    public static var current: Toplevel? { get }
  • Prepares the application, must be called before anything else.

    Declaration

    Swift

    public static func prepare()
  • Triggers a refresh of the whole display

    Declaration

    Swift

    public static func refresh()
  • Grabs the mouse, forcing all mouse events to be routed to the specified view until ungrabMouse is called.

    Declaration

    Swift

    public static func grabMouse(from view: View)

    Parameters

    from

    View that will receive all mouse events until UngrabMouse is invoked.

  • Ungrabs the mouse, allowing mouse events that were previously captured by one view to flow to other views

    Declaration

    Swift

    public static func ungrabMouse()
  • A token representing a registered root mouse handler

    Declaration

    Swift

    public struct MouseHandlerToken
  • Registers a global mouse event handler to be invoked for every mouse event, this is called before any event processing takes place for the currently focused view.

    Declaration

    Swift

    public static func addRootMouseHandler(_ handler: @escaping (MouseEvent) -> ()) -> MouseHandlerToken
  • Removes a previously registered mouse event handler

    Declaration

    Swift

    public static func removeRootMouseHandler(_ token: MouseHandlerToken)
  • Building block API: Prepares the provided toplevel for execution.

    This method prepares the provided toplevel for running with the focus, it adds this to the list of toplevels, sets up the mainloop to process the event, lays out the subviews, focuses the first element, and draws the toplevel in the screen.

    Declaration

    Swift

    public static func begin(toplevel: Toplevel)

    Parameters

    toplevel

    Toplevel to prepare execution for.

  • Makes the provided toplevel the new toplevel, sending all events to it, it returns control immediately. If the toplevel is modal

    Declaration

    Swift

    public static func present(top: Toplevel)
  • Starts the application mainloop - does not return, but can exit to the OS.

    Declaration

    Swift

    public static func run()
  • Stops running the most recent toplevel, use this to close a dialog, window, or toplevel. The last time this is called, it will return to the OS and will return with the status code 0.

    If you want to terminate the application with a different status code, call the Application.shutdown method directly with the desired exit code.

    Declaration

    Swift

    public static func requestStop()
  • Terminates the application execution

    Because this is using Dispatch to run the application main loop, there is no way of terminating the main loop, other than exiting the process. This restores the terminal to its previous state and terminates the process.

    • Paramter statusCode: status code passed to the exit(2) system call to terminate the process.

    Declaration

    Swift

    public static func shutdown(statusCode: Int = 0)