RussKie
commented
4 years ago Dealing with the API discoverability issue: the static methods do not expose the full set of available APIs
There are a number of different ways to mitigate the API discoverability issue.
One can be exposing all remaining properties via the static API, these properties include (but not limited to):
This removal prompted to add many arguments to ShowDialog methods to expose all of TaskDialogPage's functionality, e.g.:
TaskDialogFooter,TaskDialogCheckBox,TaskDialogExpander,TaskDialogRadioButtonCollection,TaskDialogProgressBar,RightToLeftLayout.
However if we pass all these properties into the method, we will make the API unusable:
var result = TaskDialog.ShowDialog(this,
text: ...,
mainInstruction: ...,
caption: ...,
buttons: new TaskDialogButton[] { button1, button2, button3 },
icon: TaskDialogIcon.ShieldWarningYellowBar,
footer: footer,
checkBox: verificationCheckBox,
expander: expander,
progressBar: progressBar,
rightToLeftLayout: rightToLeftLayout,
....
);One way out of this situation is to consider a creation of an TaskDialogOptions class that would allow to configure a page without exposing an instance of a TaskDialogPage to the user. It is more idiomatic to ASP.NET Core than Windows Forms though, but didn't look too bad API-wise:
public class TaskDialogOptions
{
public TaskDialogFooter Footer { get; set; }
public TaskDialogCheckBox Verification { get; set; }
public TaskDialogExpander Expander { get; set; }
// etc...
}
public static TaskDialogButton ShowDialog(
string? text,
string? mainInstruction = null,
string? caption = null,
IEnumerable<TaskDialogButton>? buttons = null,
TaskDialogIcon? icon = null,
TaskDialogOptions? options = null)Internally, properties set in the options object would be assigned to the corresponding properties on a Page object.
This design addresses the first discoverability issue - the user will be able to see and explore additional properties available. However the issue of multipage API is still unaccounted for.
Dealing with the cognitive load issue
It would not totally unreasonable to expect the majority of users to use the TaskDialog as a simple replacement for MessageBox, and therefore it would be used as a single page dialog. We have initially based the public API surface to match the API of MessageBox. However, as we later discovered, following the same pattern we seriously constrain our abilities to provide a useable and discoverable API.
To reduce the cognitive load, and to make users more aware of a Page concept (and thus possible make aware of multipage functionality), perhaps we should consider simplifying the API as follows:
public static TaskDialogButton ShowDialog(TaskDialogPage page);
public static TaskDialogButton ShowDialog(IntPtr hwndOwner, TaskDialogPage page);
public static TaskDialogButton ShowDialog(IWin32Window owner, TaskDialogPage page);A user could write the following code that it is slightly more verbose than the original but marginally so:
TaskDialogButton clickedButton = TaskDialog.ShowDialog(this,
new TaskDialogPage
{
Text = "Are you sure you want to do this?",
MainInstruction = "Stopping the operation might break things...",
Caption = "Confirmation",
Buttons = new TaskDialogButtonCollection { button1, button2, button3 },
Icon = TaskDialogIcon.ShieldWarningYellowBar,
DefaultButton = button2
});This way the user does not need to think about what method to chose, and has the full access to the properties of the dialog. We also address the first discoverability issue, and reduce the gap with the multipage API.
The added bonus is that this API would naturally lend itself to integration with the Designer. For example, the TaskDialogPage may be designable component, and a user could design one (or many) pages, that are later shown in a dialog:
// MyForm.Designer.cs
private void InitializeComponent()
{
// ...
//
// startDialogPage
//
startDialogPage.Buttons = new TaskDialogButtonCollection { buttonYes, buttonCancel };
startDialogPage.Caption = "Confirmation";
startDialogPage.DefaultButton = buttonCancel
startDialogPage.Icon = TaskDialogIcon.ShieldWarningYellowBar;
startDialogPage.MainInstruction = "Stopping the operation might break things...";
startDialogPage.Text = "Are you sure you want to do this?";
//
// selectionDialogPage
//
selectionDialogPage.Buttons = ...;
selectionDialogPage.Caption = ...;
}
private System.Windows.Forms.TaskDialogButton buttonYes;
private System.Windows.Forms.TaskDialogButton buttonCancel;
private System.Windows.Forms.TaskDialogPage startDialogPage;
private System.Windows.Forms.TaskDialogPage selectionDialogPage;// MyForm.cs
private void ShowDialog()
{
TaskDialogButton clickedButton = TaskDialog.ShowDialog(this, startDialogPage);
}Dealing API discoverability issue: the current API does not advertise the multipage functionality
TBD
kpreisser
Let's explore how we can streamline the API and make it easier to grasp.
Right now we have the following API:
During an internal usability study for the TaskDialog API, all participant were confused by different ways of setting up the dialog. Few issues have been identified:
staticmethods do not expose the full set of available APIs. Thestaticvariants only expose a subset of configurable properties, and thus disallow to configure other properties such as progressbar, radio buttons, footer, verification checkbox, etc. To access the more powerful features (like those listed above) requires a user to instantiate the dialog (which caused some confusion during the user study). However an instance of the dialog does not expose any properties expect forPage, which further confused the users.