NanoByte.Common  2.4.3
NanoByte.Common.Tasks.ITaskHandler Interface Reference

Used to execute and track ITasks and ask the user questions. Specific implementations provide different kinds of user interfaces. More...

Inheritance diagram for NanoByte.Common.Tasks.ITaskHandler:
NanoByte.Common.Tasks.SilentTaskHandler NanoByte.Common.Tasks.TaskHandlerBase NanoByte.Common.Tasks.CliTaskHandler NanoByte.Common.Tasks.GuiTaskHandlerBase NanoByte.Common.Tasks.DialogTaskHandler

Public Member Functions

void RunTask (ITask task)
 Runs an ITask and tracks its progress. Returns once the task has been completed. The task may be executed on a different thread. More...
 
bool Ask ([Localizable(true)] string question)
 Asks the user a Yes/No/Cancel question. More...
 
bool Ask ([Localizable(true)] string question, bool defaultAnswer, [Localizable(true)] string? alternateMessage=null)
 Asks the user a Yes/No/Cancel question or uses a default answer in Tasks.Verbosity.Batch mode. More...
 
void Output ([Localizable(true)] string title, [Localizable(true)] string message)
 Displays multi-line text to the user. More...
 
void Output< T > ([Localizable(true)] string title, IEnumerable< T > data)
 Displays tabular data to the user. More...
 
void OutputLow ([Localizable(true)] string title, [Localizable(true)] string message)
 Displays multi-line text to the user unless Verbosity is Tasks.Verbosity.Batch. More...
 
void OutputLow< T > ([Localizable(true)] string title, IEnumerable< T > data)
 Displays tabular data to the user unless Verbosity is Tasks.Verbosity.Batch. More...
 
void Error (Exception exception)
 Displays an error message to the user. More...
 

Properties

CancellationToken CancellationToken [get]
 Used to signal when the user wishes to cancel the entire current process (and any ITasks it includes). More...
 
ICredentialProviderCredentialProvider [get]
 Used to ask the user or a keyring for NetworkCredentials for specific Uris; can be null. More...
 
Verbosity Verbosity [get, set]
 The detail level of messages displayed to the user. More...
 

Detailed Description

Used to execute and track ITasks and ask the user questions. Specific implementations provide different kinds of user interfaces.

The methods may be called from a background thread. Implementations need to apply appropriate thread-synchronization to update UI elements. Implementations should derive from MarshalNoTimeout.

Member Function Documentation

◆ Ask() [1/2]

bool NanoByte.Common.Tasks.ITaskHandler.Ask ( [Localizable(true)] string  question)

Asks the user a Yes/No/Cancel question.

Parameters
questionThe question and comprehensive information to help the user make an informed decision.
Returns
true if the user answered with 'Yes'; false if the user answered with 'No'.
Exceptions
OperationCanceledExceptionThe user selected 'Cancel'.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, and NanoByte.Common.Tasks.SilentTaskHandler.

◆ Ask() [2/2]

bool NanoByte.Common.Tasks.ITaskHandler.Ask ( [Localizable(true)] string  question,
bool  defaultAnswer,
[Localizable(true)] string?  alternateMessage = null 
)

Asks the user a Yes/No/Cancel question or uses a default answer in Tasks.Verbosity.Batch mode.

Parameters
questionThe question and comprehensive information to help the user make an informed decision.
defaultAnswerThe answer to automatically use when Verbosity is Tasks.Verbosity.Batch or lower.
alternateMessageA message to output with Log.Warn(string) when the defaultAnswer is used instead of asking the user.
Returns
true if the user answered with 'Yes'; false if the user answered with 'No'.
Exceptions
OperationCanceledExceptionThe user selected 'Cancel'.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, and NanoByte.Common.Tasks.SilentTaskHandler.

◆ Error()

void NanoByte.Common.Tasks.ITaskHandler.Error ( Exception  exception)

Displays an error message to the user.

Parameters
exceptionThe exception representing the error that occurred.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, NanoByte.Common.Tasks.SilentTaskHandler, NanoByte.Common.Tasks.CliTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, and NanoByte.Common.Tasks.DialogTaskHandler.

◆ Output()

void NanoByte.Common.Tasks.ITaskHandler.Output ( [Localizable(true)] string  title,
[Localizable(true)] string  message 
)

Displays multi-line text to the user.

Parameters
titleA title for the message. Will only be displayed in GUIs, not on the console. Must not contain critical information!
messageThe string to display. Trailing linebreaks are appropriately handled or ignored.

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, NanoByte.Common.Tasks.SilentTaskHandler, NanoByte.Common.Tasks.CliTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, and NanoByte.Common.Tasks.DialogTaskHandler.

◆ Output< T >()

void NanoByte.Common.Tasks.ITaskHandler.Output< T > ( [Localizable(true)] string  title,
IEnumerable< T >  data 
)

Displays tabular data to the user.

Parameters
titleA title for the data. Will only be displayed in GUIs, not on the console. Must not contain critical information!
dataThe data to display.

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, NanoByte.Common.Tasks.SilentTaskHandler, NanoByte.Common.Tasks.GuiTaskHandlerBase, and NanoByte.Common.Tasks.DialogTaskHandler.

◆ OutputLow()

void NanoByte.Common.Tasks.ITaskHandler.OutputLow ( [Localizable(true)] string  title,
[Localizable(true)] string  message 
)

Displays multi-line text to the user unless Verbosity is Tasks.Verbosity.Batch.

Parameters
titleA title for the message. Will only be displayed in GUIs, not on the console. Must not contain critical information!
messageThe string to display.

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, and NanoByte.Common.Tasks.SilentTaskHandler.

◆ OutputLow< T >()

void NanoByte.Common.Tasks.ITaskHandler.OutputLow< T > ( [Localizable(true)] string  title,
IEnumerable< T >  data 
)

Displays tabular data to the user unless Verbosity is Tasks.Verbosity.Batch.

Parameters
titleA title for the message. Will only be displayed in GUIs, not on the console. Must not contain critical information!
dataThe data to display.

Implementations may close the UI as a side effect. Therefore this should be your last call on the handler.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, and NanoByte.Common.Tasks.SilentTaskHandler.

◆ RunTask()

void NanoByte.Common.Tasks.ITaskHandler.RunTask ( ITask  task)

Runs an ITask and tracks its progress. Returns once the task has been completed. The task may be executed on a different thread.

Parameters
taskThe task to be run. (ITask.Run or equivalent is called on it.)
Exceptions
OperationCanceledExceptionThe user canceled the task.
IOExceptionThe task ended with TaskState.IOError.
WebExceptionThe task ended with TaskState.WebError.

This may be called multiple times concurrently but concurrent calls must not depend on each other. The specific implementation of this method determines whether the tasks actually run concurrently or in sequence.

Implemented in NanoByte.Common.Tasks.TaskHandlerBase, NanoByte.Common.Tasks.SilentTaskHandler, NanoByte.Common.Tasks.CliTaskHandler, and NanoByte.Common.Tasks.DialogTaskHandler.

Property Documentation

◆ CancellationToken

CancellationToken NanoByte.Common.Tasks.ITaskHandler.CancellationToken
get

Used to signal when the user wishes to cancel the entire current process (and any ITasks it includes).

Once this has been signalled this ITaskHandler cannot be reused, since any subsequently started ITasks will be cancelled immediately.

◆ CredentialProvider

ICredentialProvider? NanoByte.Common.Tasks.ITaskHandler.CredentialProvider
get

Used to ask the user or a keyring for NetworkCredentials for specific Uris; can be null.

◆ Verbosity

Verbosity NanoByte.Common.Tasks.ITaskHandler.Verbosity
getset

The detail level of messages displayed to the user.


The documentation for this interface was generated from the following file: