ArlecchinoBuilder class

Namespace: Arlecchino.Hosting · Assembly: Arlecchino

Configures an application while its services are being registered. Every method returns the builder, so a whole application is described in one chain at startup.

public sealed class ArlecchinoBuilder

Properties

Member	Summary
Options	The settings gathered so far, for anything the builder has no method for.
Services	The service collection being built, for registering whatever the views depend on.

Methods

Member	Summary
AddCommand<TCommand>()	Registers a command available everywhere. Its key has to carry a modifier, since plain letters belong to whatever is being typed.
AddStartup<TStartup>()	Registers work to run once the container is ready but before the first frame, for loading what the opening view expects to find.
AddStore<TStore>()	Registers one store, resolved by its own type: a singleton, or scoped to the screen when it implements IArlecchinoScopedStore. An alternative to AddGeneratedStores() for a store the generator cannot see — one from another assembly — rather than a layer on top of it.
AddView<T>(string)	Registers a view at a route, built from the container so it can take whatever it needs in its constructor. Views are created on demand rather than at startup.
AddView(string, Func<IServiceProvider, IArlecchinoView>)	Registers a view built by hand, for the cases the container cannot cover on its own, such as a view that needs a value known only at startup.
AddViewFactory<TFactory>()	Registers a source of views that decides at run time which routes it serves. This is what the generated factory is registered through, and how a plugin adds views the host never listed.
AddWidget<TWidget>()	Registers one widget as a singleton, for a widget AddGeneratedWidgets() cannot see. It is shared by every screen that resolves it, state and focus included.
StartAt(ViewRoute)	Sets the view the application opens on.
StartAt(string)	Sets the view the application opens on, by name.
UseKeymap(ArlecchinoKeymap)	Replaces the key bindings, which every widget then follows.
UseKeysByPosition()	Takes every character from where its key sits rather than from what the layout makes of it, so shortcuts read the same everywhere and those languages cannot be typed at all.
UseLayout<TLayout>()	Draws every view inside a frame of the application's own, from one instance that outlives the views. A view answering false to IArlecchinoView.UsesLayout is drawn without it.
UseMouse()	Turns the mouse on, which stops the terminal from handling selection itself. It is off by default for that reason.
UseNotifications(Nullable<KeyPress>, Nullable<TimeSpan>, Nullable<TimeSpan>)	Turns the output row on and says how long a message lives. The row shows the newest notification until timeout is up; the message stays readable on the notifications screen — the Notifications key, or a click on the row — until lifetime is up.
UseStrings(ArlecchinoStrings)	Replaces the wording the framework itself shows. This is the only way it is localized: nothing is looked up from resources.
UseTerminal<TTerminal>()	Draws to something other than the console, replacing whatever terminal was registered. This is how tests capture frames instead of writing them.
UseTextInput(TextInputMode)	Chooses how typed characters are read. This is a trade-off rather than a preference: reading the terminal's own characters accepts any language but can misread keys on some terminals.
UseTheme(ThemePalette)	Replaces the colors. What actually reaches the screen still depends on what the terminal supports.
WithoutHostedService()	Stops the application from taking over the terminal when the host starts, leaving everything registered. A test can then drive the loop itself.
WithoutNotifications()	Leaves the output row off, so nothing the application says is drawn on the frame.

Properties in detail

Options

public ArlecchinoOptions Options { get; }

The settings gathered so far, for anything the builder has no method for.

Type ArlecchinoOptions

Services

public IServiceCollection Services { get; }

The service collection being built, for registering whatever the views depend on.

Type IServiceCollection

Methods in detail

AddCommand<TCommand>()

public ArlecchinoBuilder AddCommand<TCommand>();

Registers a command available everywhere. Its key has to carry a modifier, since plain letters belong to whatever is being typed.

Returns ArlecchinoBuilder — The builder.

AddStartup<TStartup>()

public ArlecchinoBuilder AddStartup<TStartup>();

Registers work to run once the container is ready but before the first frame, for loading what the opening view expects to find.

Returns ArlecchinoBuilder — The builder.

AddStore<TStore>()

public ArlecchinoBuilder AddStore<TStore>();

Registers one store, resolved by its own type: a singleton, or scoped to the screen when it implements IArlecchinoScopedStore. An alternative to AddGeneratedStores() for a store the generator cannot see — one from another assembly — rather than a layer on top of it.

Returns ArlecchinoBuilder — The builder.

AddView<T>(string)

public ArlecchinoBuilder AddView<T>(string route);

Registers a view at a route, built from the container so it can take whatever it needs in its constructor. Views are created on demand rather than at startup.

Parameters

Name	Type	Description
route	string	The route it answers to.

Returns ArlecchinoBuilder — The builder.

AddView(string, Func<IServiceProvider, IArlecchinoView>)

public ArlecchinoBuilder AddView(string route, Func<IServiceProvider, IArlecchinoView> factory);

Registers a view built by hand, for the cases the container cannot cover on its own, such as a view that needs a value known only at startup.

Parameters

Name	Type	Description
route	string	The route it answers to.
factory	Func<T, TResult><IServiceProvider, IArlecchinoView>	Builds the view.

Returns ArlecchinoBuilder — The builder.

AddViewFactory<TFactory>()

public ArlecchinoBuilder AddViewFactory<TFactory>();

Registers a source of views that decides at run time which routes it serves. This is what the generated factory is registered through, and how a plugin adds views the host never listed.

Returns ArlecchinoBuilder — The builder.

AddWidget<TWidget>()

public ArlecchinoBuilder AddWidget<TWidget>();

Registers one widget as a singleton, for a widget AddGeneratedWidgets() cannot see. It is shared by every screen that resolves it, state and focus included.

Returns ArlecchinoBuilder — The builder.

StartAt(ViewRoute)

public ArlecchinoBuilder StartAt(ViewRoute route);

Sets the view the application opens on.

Parameters

Name	Type	Description
route	ViewRoute	The opening route.

Returns ArlecchinoBuilder — The builder.

StartAt(string)

public ArlecchinoBuilder StartAt(string route);

Sets the view the application opens on, by name.

Parameters

Name	Type	Description
route	string	The opening route.

Returns ArlecchinoBuilder — The builder.

UseKeymap(ArlecchinoKeymap)

public ArlecchinoBuilder UseKeymap(ArlecchinoKeymap keymap);

Replaces the key bindings, which every widget then follows.

Parameters

Name	Type	Description
keymap	ArlecchinoKeymap	The bindings to use.

Returns ArlecchinoBuilder — The builder.

UseKeysByPosition()

public ArlecchinoBuilder UseKeysByPosition();

Takes every character from where its key sits rather than from what the layout makes of it, so shortcuts read the same everywhere and those languages cannot be typed at all.

Returns ArlecchinoBuilder — The builder.

UseLayout<TLayout>()

public ArlecchinoBuilder UseLayout<TLayout>();

Draws every view inside a frame of the application's own, from one instance that outlives the views. A view answering false to IArlecchinoView.UsesLayout is drawn without it.

Returns ArlecchinoBuilder — The builder.

UseMouse()

public ArlecchinoBuilder UseMouse();

Turns the mouse on, which stops the terminal from handling selection itself. It is off by default for that reason.

Returns ArlecchinoBuilder — The builder.

UseNotifications(Nullable<KeyPress>, Nullable<TimeSpan>, Nullable<TimeSpan>)

public ArlecchinoBuilder UseNotifications(
    Nullable<KeyPress> key,
    Nullable<TimeSpan> timeout,
    Nullable<TimeSpan> lifetime);

Turns the output row on and says how long a message lives. The row shows the newest notification until timeout is up; the message stays readable on the notifications screen — the Notifications key, or a click on the row — until lifetime is up.

Parameters

Name	Type	Description
key	Nullable<T><KeyPress>	Key that opens the notifications screen, modifiers and all. Omit it for Ctrl+N.
timeout	Nullable<T><TimeSpan>	How long a message holds the output row; omit to keep the default.
lifetime	Nullable<T><TimeSpan>	How long it stays in the list; omit to keep the default.

Returns ArlecchinoBuilder — The builder.

UseStrings(ArlecchinoStrings)

public ArlecchinoBuilder UseStrings(ArlecchinoStrings strings);

Replaces the wording the framework itself shows. This is the only way it is localized: nothing is looked up from resources.

Parameters

Name	Type	Description
strings	ArlecchinoStrings	The wording to use.

Returns ArlecchinoBuilder — The builder.

UseTerminal<TTerminal>()

public ArlecchinoBuilder UseTerminal<TTerminal>();

Draws to something other than the console, replacing whatever terminal was registered. This is how tests capture frames instead of writing them.

Returns ArlecchinoBuilder — The builder.

UseTextInput(TextInputMode)

public ArlecchinoBuilder UseTextInput(TextInputMode mode);

Chooses how typed characters are read. This is a trade-off rather than a preference: reading the terminal's own characters accepts any language but can misread keys on some terminals.

Parameters

Name	Type	Description
mode	TextInputMode	The mode to use.

Returns ArlecchinoBuilder — The builder.

UseTheme(ThemePalette)

public ArlecchinoBuilder UseTheme(ThemePalette palette);

Replaces the colors. What actually reaches the screen still depends on what the terminal supports.

Parameters

Name	Type	Description
palette	ThemePalette	The colors to use.

Returns ArlecchinoBuilder — The builder.

WithoutHostedService()

public ArlecchinoBuilder WithoutHostedService();

Stops the application from taking over the terminal when the host starts, leaving everything registered. A test can then drive the loop itself.

Returns ArlecchinoBuilder — The builder.

WithoutNotifications()

public ArlecchinoBuilder WithoutNotifications();

Leaves the output row off, so nothing the application says is drawn on the frame.

Returns ArlecchinoBuilder — The builder.