Views.md

Views

Opal is primarily intended for view-based rendering. Views effectively treat the console as a canvas that it renders characters onto, with an update loop running in the background, and optional support for keyboard- and mouse input.

A view can be created by simply inheriting from the ConsoleView class. It comes with three basic methods to manage the view:

• Initialize: Gets called when the view is used for the first time.
• Render: Used to render the view onto the provided IConsoleGrid, which will then be rendered to the console.
• Update: Perform non-rendering logic.

Alternatively, the AsyncConsoleView class can be inheriting from instead of ConsoleView, which provides methods to ConsoleView except the initialize- and update methods can perform async logic and will be waited on. Do note that the Render method remains synchronous, as it is only intended to handle rendering and nothing else.

Rendering

Rendering is called on a loop at a regular interval, or if the console's size is changed by the user.

Updating

The Update and UpdateAsync methods provide logic to periodically update the view.

The update methods are called with an IConsoleState parameter, which allows the view to request moving to a different view, or to exit Opal entirely.

Note: Rendering is called after the Update method is called.

Input handling

Views can implement various interfaces, which lets them receive and handle user input.

• IKeyInputHandler: Keyboard input.
• IMouseButtonInputHandler: Mouse button input.
• IMouseMoveInputHandler: Mouse movement input.
• ICancellationRequestHandler: Intercept and optionally cancel user requests to exit Opal via Ctrl+C.

Note: Input handling gets executed before the Update method is called.

View navigation

The IConsoleState class provides methods for navigating back and forth between views.

Opal keeps track of navigation between view by storing the navigation history to the view stack.

• The GotoChild method navigates to a new view, and stores the current view to the view stack, so it can be accessed by existing the new view.
• The Goto method navigates to a new view, but does not store the current view to the view stack, meaning the current view cannot be navigated to by simply exiting the new view.
• The ExitView method exits the current view, and goes back to the previous view in the view stack. If there are no previous views, this exits Opal.
• The Exit method fully exits Opal, regardless of where the current view is in the view stack.
• The Exit method also has an overload which accepts an Exception. This will gracefully exit Opal (returning the console to its initial state), and then throw the exception (preserving the original StackTrace).