ArlecchinoState class

Namespace: Arlecchino.State · Assembly: Arlecchino

State that outlives a single screen: the output line, the dialogs that are open, and a pending file picker request. All of it is written on the drawing thread, and only ArlecchinoState.Invalidate from anywhere.

public class ArlecchinoState

Constructors

Member	Summary
ArlecchinoState(Repaint, Notifications)	Creates the state.

Properties

Member	Summary
FilePicker	What the file picker should show: fill it in, then navigate to Routes.FilePicker. It is written on the drawing thread and cleared however the picker finishes.
Modal	The dialog on top, or null when none is open, taking every key while it is there. Assigning replaces the whole stack, where ArlecchinoState.PushModal opens one over another.
Modals	Every open dialog, bottom first, as a live read-only view. Drawing goes through this, so the ones underneath stay visible behind the top one.
Notifications	What the application has said lately, and the screen behind the output row.
Output	The status line at the bottom of the frame. Writing to it raises a notification, so the line clears itself and the message stays on the notifications screen; an empty string clears it at once.
PickerLastFolder	Folder the picker ended in, to be passed as the next starting path. It is written on the drawing thread, as ArlecchinoState.Modal is.

Methods

Member	Summary
CloseAllModals()	Closes every open dialog at once, however deep they are stacked.
CloseModal()	Closes the dialog on top, uncovering whatever it was opened over. Submitting, picking and canceling already do this, so it is only needed to dismiss one from the outside.
Invalidate()	Asks for a repaint. Needed only for changes the framework cannot see — a field mutated from outside, or data that arrived on a timer.
PushModal(Modal)	Opens a dialog over whatever is already open, which is how a callback asks a follow-up question without losing what the user was in the middle of. Closing it uncovers the one underneath.
RequestChoice(string, IReadOnlyList<string>, Action<string>, string)	Asks for one option out of a list that can be filtered by typing.
RequestColor(string, Rgb, Action<Rgb>)	Asks for a color with a swatch and three sliders. Channels are whole numbers, so a color that goes in can come back shifted by a unit or two.
RequestConfirmation(string, Action)	Asks a question that has to be confirmed before something happens. The negative answer starts selected, so a stray Enter cancels rather than deletes.
RequestDate(string, DateOnly, Action<DateOnly>)	Asks for a date, edited one segment at a time.
RequestEmail(string, string, Action<string>)	Asks for an email address, checked before the dialog will close.
RequestMessage(string, string, Action)	Shows a message with nothing to fill in; any of the closing keys dismisses it.
RequestMultiChoice(string, IReadOnlyList<string>, IReadOnlyList<string>, Action<IReadOnlyList<string>>)	Asks for any number of options. Marks survive filtering, and the result comes back in the order of options rather than the order they were marked.
RequestNumber(string, decimal, decimal, decimal, Action<decimal>)	Asks for a number within bounds. Typing is restricted to digits, and stepping keys clamp to the range.
RequestPassword(string, Action<string>)	Asks for a secret. The field shows dots, but the text handed to the callback is untouched.
RequestSlider(string, decimal, decimal, decimal, Action<decimal>)	Asks for a number on a track, adjusted with the arrows rather than typed.
RequestText(string, string, Func<string, string>, Action<string>)	Asks for a line of text.
RequestTextArea(string, string, Action<string>, Func<string, string>, int)	Asks for several lines of text. Enter starts a new line, so the text is confirmed with the Submit key — Ctrl+Enter unless the keymap says otherwise.
RequestTime(string, TimeOnly, Action<TimeOnly>)	Asks for a time of day, edited one segment at a time.
RequestToggle(string, bool, Action<bool>)	Asks a yes-or-no question.
RequestUrl(string, string, Action<string>)	Asks for an http or https link, checked before the dialog will close.

Constructors in detail

ArlecchinoState(Repaint, Notifications)

public ArlecchinoState(Repaint repaint, Notifications notifications);

Creates the state.

Parameters

Name	Type	Description
repaint	Repaint	Signal raised whenever anything here changes.
notifications	Notifications	Holds the output row and the notifications screen behind it.

Properties in detail

FilePicker

public FilePickerRequest? FilePicker { get; set; }

What the file picker should show: fill it in, then navigate to Routes.FilePicker. It is written on the drawing thread and cleared however the picker finishes.

Type FilePickerRequest

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

Modal

public Modal? Modal { get; set; }

The dialog on top, or null when none is open, taking every key while it is there. Assigning replaces the whole stack, where ArlecchinoState.PushModal opens one over another.

Type Modal

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

Modals

public IReadOnlyList<Modal> Modals { get; }

Every open dialog, bottom first, as a live read-only view. Drawing goes through this, so the ones underneath stay visible behind the top one.

Type IReadOnlyList<T><Modal>

Notifications

public Notifications Notifications { get; }

What the application has said lately, and the screen behind the output row.

Type Notifications

Output

public string Output { get; set; }

The status line at the bottom of the frame. Writing to it raises a notification, so the line clears itself and the message stays on the notifications screen; an empty string clears it at once.

Type string

PickerLastFolder

public string PickerLastFolder { get; set; }

Folder the picker ended in, to be passed as the next starting path. It is written on the drawing thread, as ArlecchinoState.Modal is.

Type string

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

Methods in detail

CloseAllModals()

public void CloseAllModals();

Closes every open dialog at once, however deep they are stacked.

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

CloseModal()

public void CloseModal();

Closes the dialog on top, uncovering whatever it was opened over. Submitting, picking and canceling already do this, so it is only needed to dismiss one from the outside.

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

Invalidate()

public void Invalidate();

Asks for a repaint. Needed only for changes the framework cannot see — a field mutated from outside, or data that arrived on a timer.

PushModal(Modal)

public void PushModal(Modal modal);

Opens a dialog over whatever is already open, which is how a callback asks a follow-up question without losing what the user was in the middle of. Closing it uncovers the one underneath.

Parameters

Name	Type	Description
modal	Modal	The dialog to open.

Exceptions

Type	Thrown when
InvalidOperationException	Called from off the drawing thread.

RequestChoice(string, IReadOnlyList<string>, Action<string>, string)

public void RequestChoice(
    string title,
    IReadOnlyList<string> options,
    Action<string> onPicked,
    string current = "");

Asks for one option out of a list that can be filtered by typing.

Parameters

Name	Type	Description
title	string	Title of the dialog.
options	IReadOnlyList<T><string>	What to choose from.
onPicked	Action<T><string>	Called with the chosen option.
current	string	Option to start on; the first one when it is not in the list.

RequestColor(string, Rgb, Action<Rgb>)

public void RequestColor(string title, Rgb initial, Action<Rgb> onPicked);

Asks for a color with a swatch and three sliders. Channels are whole numbers, so a color that goes in can come back shifted by a unit or two.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	Rgb	Color the sliders start on.
onPicked	Action<T><Rgb>	Called with the chosen color.

RequestConfirmation(string, Action)

public void RequestConfirmation(string title, Action onYes);

Asks a question that has to be confirmed before something happens. The negative answer starts selected, so a stray Enter cancels rather than deletes.

Parameters

Name	Type	Description
title	string	The question.
onYes	Action	Called only when the answer was yes.

RequestDate(string, DateOnly, Action<DateOnly>)

public void RequestDate(string title, DateOnly initial, Action<DateOnly> onSubmit);

Asks for a date, edited one segment at a time.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	DateOnly	Date the field starts on.
onSubmit	Action<T><DateOnly>	Called with the chosen date.

RequestEmail(string, string, Action<string>)

public void RequestEmail(string title, string initial, Action<string> onSubmit);

Asks for an email address, checked before the dialog will close.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	string	Text the field starts with.
onSubmit	Action<T><string>	Called with the accepted address.

RequestMessage(string, string, Action)

public void RequestMessage(string title, string text, Action? onClosed = null);

Shows a message with nothing to fill in; any of the closing keys dismisses it.

Parameters

Name	Type	Description
title	string	Title of the dialog.
text	string	What to say. Long text wraps inside the box.
onClosed	Action	Called once it is dismissed.

RequestMultiChoice(string, IReadOnlyList<string>, IReadOnlyList<string>, Action<IReadOnlyList<string>>)

public void RequestMultiChoice(
    string title,
    IReadOnlyList<string> options,
    IReadOnlyList<string> selectedKeys,
    Action<IReadOnlyList<string>> onSubmit);

Asks for any number of options. Marks survive filtering, and the result comes back in the order of options rather than the order they were marked.

Parameters

Name	Type	Description
title	string	Title of the dialog.
options	IReadOnlyList<T><string>	What to choose from.
selectedKeys	IReadOnlyList<T><string>	Options marked to begin with.
onSubmit	Action<T><IReadOnlyList<T><string>>	Called with everything marked.

RequestNumber(string, decimal, decimal, decimal, Action<decimal>)

public void RequestNumber(
    string title,
    decimal initial,
    decimal minimum,
    decimal maximum,
    Action<decimal> onSubmit);

Asks for a number within bounds. Typing is restricted to digits, and stepping keys clamp to the range.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	decimal	Value the field starts on, clamped to the range.
minimum	decimal	Lowest value allowed.
maximum	decimal	Highest value allowed.
onSubmit	Action<T><decimal>	Called with the accepted number.

RequestPassword(string, Action<string>)

public void RequestPassword(string title, Action<string> onSubmit);

Asks for a secret. The field shows dots, but the text handed to the callback is untouched.

Parameters

Name	Type	Description
title	string	Title of the dialog.
onSubmit	Action<T><string>	Called with what was typed.

RequestSlider(string, decimal, decimal, decimal, Action<decimal>)

public void RequestSlider(
    string title,
    decimal initial,
    decimal minimum,
    decimal maximum,
    Action<decimal> onSubmit);

Asks for a number on a track, adjusted with the arrows rather than typed.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	decimal	Value the slider starts on, clamped to the range.
minimum	decimal	Left end of the track.
maximum	decimal	Right end of the track.
onSubmit	Action<T><decimal>	Called with the chosen value.

RequestText(string, string, Func<string, string>, Action<string>)

public void RequestText(
    string title,
    string initial,
    Func<string, string?>? validate,
    Action<string> onSubmit);

Asks for a line of text.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	string	Text the field starts with.
validate	Func<T, TResult><string, string>	Checked on confirm; return a message to keep the dialog open, or null to accept.
onSubmit	Action<T><string>	Called with the accepted text.

RequestTextArea(string, string, Action<string>, Func<string, string>, int)

public void RequestTextArea(
    string title,
    string initial,
    Action<string> onSubmit,
    Func<string, string?>? validate = null,
    int visibleRows = 8);

Asks for several lines of text. Enter starts a new line, so the text is confirmed with the Submit key — Ctrl+Enter unless the keymap says otherwise.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	string	Text the editor starts with.
onSubmit	Action<T><string>	Called with the accepted text.
validate	Func<T, TResult><string, string>	Checked on submit; return a message to keep the dialog open, or null to accept.
visibleRows	int	How many rows to show before the text starts scrolling.

RequestTime(string, TimeOnly, Action<TimeOnly>)

public void RequestTime(string title, TimeOnly initial, Action<TimeOnly> onSubmit);

Asks for a time of day, edited one segment at a time.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	TimeOnly	Time the field starts on.
onSubmit	Action<T><TimeOnly>	Called with the chosen time.

RequestToggle(string, bool, Action<bool>)

public void RequestToggle(string title, bool initial, Action<bool> onSubmit);

Asks a yes-or-no question.

Parameters

Name	Type	Description
title	string	The question.
initial	bool	Which chip starts selected.
onSubmit	Action<T><bool>	Called with the answer.

RequestUrl(string, string, Action<string>)

public void RequestUrl(string title, string initial, Action<string> onSubmit);

Asks for an http or https link, checked before the dialog will close.

Parameters

Name	Type	Description
title	string	Title of the dialog.
initial	string	Text the field starts with, often just the scheme.
onSubmit	Action<T><string>	Called with the accepted link.