LaunchBoxCONTRIBUTORS
On this page

14.1 Beta 1 SDK

This reference documents the current beta SDK. Beta APIs can change before stable.

PluginConfigurationForm14.1 Beta

C#
public sealed class Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationForm
Describes one host-rendered plugin configuration form and its submission handler.

Constructors

PluginConfigurationForm 14.1 Beta

C#
public PluginConfigurationForm(string id, string name, Unbroken.LaunchBox.Plugins.Forms.PluginFormDefinition form, System.Func<System.Collections.Generic.IReadOnlyDictionary<string, string?>, System.Threading.CancellationToken, System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginFormResult>> submit, string? description = null)
Initializes a new instance of the Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationForm class.
id 14.1 Beta
The stable configuration form ID within the component, compared ordinally.
name 14.1 Beta
The required literal name used when localization is unavailable.
form 14.1 Beta
The framework-neutral form presented by the host.
submit 14.1 Beta
The asynchronous handler that validates and saves submitted values. It must return a non-null task with a non-null result and observe cancellation during asynchronous work.
description 14.1 Beta
An optional nonblank literal description used when localization is unavailable.
Exception: System.ArgumentNullException
A required argument is null.
Exception: System.ArgumentException
A supplied ID, name, or description is blank.

PluginConfigurationForm 14.1 Beta

C#
public PluginConfigurationForm(string id, Unbroken.LaunchBox.Plugins.PluginText name, Unbroken.LaunchBox.Plugins.Forms.PluginFormDefinition form, System.Func<System.Collections.Generic.IReadOnlyDictionary<string, string?>, System.Threading.CancellationToken, System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginFormResult>> submit, Unbroken.LaunchBox.Plugins.PluginText? description = null)
Initializes a configuration form with localizable, formattable presentation text.
id 14.1 Beta
The stable configuration form ID within the component, compared ordinally.
name 14.1 Beta
The form name, including its required fallback format.
form 14.1 Beta
The framework-neutral form presented by the host.
submit 14.1 Beta
The asynchronous handler that validates and saves submitted values.
description 14.1 Beta
An optional description with its fallback format.

PluginConfigurationForm 14.1 Beta

C#
public PluginConfigurationForm(string id, Unbroken.LaunchBox.Plugins.PluginText name, Unbroken.LaunchBox.Plugins.Forms.PluginFormDefinition form, System.Func<System.Threading.CancellationToken, System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationValues>> loadValues, System.Func<Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationValues, System.Threading.CancellationToken, System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginFormResult>> submit, System.Func<Unbroken.LaunchBox.Plugins.Forms.IPluginConfigurationValues, Unbroken.LaunchBox.Plugins.Forms.PluginFormResult>? validate, Unbroken.LaunchBox.Plugins.PluginText? description = null)
Creates a configuration form with explicit initial values and optional named scopes.
id 14.1 Beta
The stable form identity within the component.
name 14.1 Beta
The localizable form name.
form 14.1 Beta
The shared field definition.
loadValues 14.1 Beta
Loads detached explicit values. Bind instance identity in this callback.
submit 14.1 Beta
Persists the complete accepted snapshot once, including all scopes.
validate 14.1 Beta
Validates one effective scope without persisting or changing the submitted snapshot.
description 14.1 Beta
Optional localizable explanation.

Remarks

The host retains drafts and validates every supplied scope before submitting. Field defaults are presentation fallbacks and are not stored unless explicitly edited. This non-secret scoped contract cannot contain secret fields.

Properties

Description 14.1 Beta

C#
public Unbroken.LaunchBox.Plugins.PluginText? Description { get; }
Gets the optional localizable, formattable description.

Form 14.1 Beta

C#
public Unbroken.LaunchBox.Plugins.Forms.PluginFormDefinition Form { get; }
Gets the framework-neutral form presented by the host.

Id 14.1 Beta

C#
public string Id { get; }
Gets the stable configuration form ID within the component, compared ordinally.

Name 14.1 Beta

C#
public Unbroken.LaunchBox.Plugins.PluginText Name { get; }
Gets the localizable, formattable name and its fallback format.

SupportsScopes 14.1 Beta

C#
public bool SupportsScopes { get; }
Gets whether this form exchanges explicit values across optional named scopes.

Methods

LoadValuesAsync 14.1 Beta

C#
public System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationValues?> LoadValuesAsync(System.Threading.CancellationToken cancellationToken)
Loads detached scoped values. Ordinary forms instead supply initial field defaults.
cancellationToken 14.1 Beta
Cancels retrieval.

Returns

The explicit values for a scoped form, or null for an ordinary form.

SubmitAsync 14.1 Beta

C#
public System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginFormResult> SubmitAsync(System.Collections.Generic.IReadOnlyDictionary<string, string?> values, System.Threading.CancellationToken cancellationToken)
Submits configuration values for validation and persistence by the plugin.
values 14.1 Beta
Submitted values keyed by form field ID. Values are passed unchanged to the handler; the plugin determines which values are required and how they are saved.
cancellationToken 14.1 Beta
A token used to cancel submission.

Returns

The plugin's acceptance result, including any form or field validation errors.

Remarks

Cancellation requested before this call prevents the handler from running. Once invoked, the handler is responsible for observing the token. Handler exceptions and cancellation propagate to the caller; cancellation does not automatically undo plugin persistence.
Exception: System.ArgumentNullException
values is null.
Exception: System.OperationCanceledException
Cancellation has already been requested.

SubmitValuesAsync 14.1 Beta

C#
public System.Threading.Tasks.Task<Unbroken.LaunchBox.Plugins.Forms.PluginFormResult> SubmitValuesAsync(Unbroken.LaunchBox.Plugins.Forms.PluginConfigurationValues values, System.Threading.CancellationToken cancellationToken)
Submits a complete scoped snapshot after host validation.
values 14.1 Beta
All explicit values, including scopes and preserved unknown fields.
cancellationToken 14.1 Beta
Cancels submission.

Returns

The plugin's acceptance result.

Remarks

This method is only available for forms constructed with scoped callbacks. Cancellation does not roll back completed writes.

ValidateValues 14.1 Beta

C#
public Unbroken.LaunchBox.Plugins.Forms.PluginFormResult ValidateValues(Unbroken.LaunchBox.Plugins.Forms.IPluginConfigurationValues values)
Validates one effective scope without persisting. Ordinary forms validate during submission.
values 14.1 Beta
A detached view, including declared defaults.

Returns

The validation result.