DisplayCommandsForm Class

A form to display available user commands for a control or application (a quick reference list). Buttons are displayed as images, keys are shown as icons, and tooltips may also be used for further details.

For a list of all members of this type, see DisplayCommandsForm Members.

System.Object
   MarshalByRefObject
      Component
         Control
            ScrollableControl
               ContainerControl
                  Form
                     DisplayCommandsForm

public class DisplayCommandsForm : Form

Thread Safety

Public static (Shared in Visual Basic) members of this type are safe for multithreaded operations. Instance members are not guaranteed to be thread-safe.

Remarks

This form provides a handy pop-up quick-reference chart for the commands in either an application or a control. If you have several complex controls within an application, embed this in each of them and then wire them up at the application level to show each of them in separate windows. Using this form requires just these simple steps:

Create a list of commands; optionally include a shortcut key and/or a tooltip for each. Each such command is represented by a CommandElement.
Group these into categories and decide whether to visually delineate the categories with category names (CategoryElement) or with simple separator lines (SeparatorElement).
Build a collection of IDisplayElement objects from (1) and (2).
Feed the IDisplayElement collection to the DisplayCommandsForm and display it.

CommandElements are the main type of DisplayElement. A CommandElement accepts up to four parameters: a command description, a tooltip for the command description, a shortcut description, and a ToolStripItem to enhance the shortcut description. The simplest example is something like this:

new CommandElement("Start search","Ctrl+F")

The command description is displayed in the left-hand column of the two-column reference table, and the shortcut in the right-hand column. If you provide a tooltip, it is attached to the command description so that rolling over it will provide further information to the user. It is also attached to a visible information icon (a question mark) appended to the end of the shortcut elements.

The shortcut description (like "Ctrl+F") is a textual representation of the shortcut. You are not limited to referencing keys; you may also reference buttons. Say, for example, you want a shortcut that indicates the user should depress the config button. The button should be enclosed in brackets indicating a button, as in [b]config[b]. This named button may or may not avail itself of an associated ToolStripItem or ButtonBase, another parameter to a CommandElement. Without one, the shortcut will render as config, i.e. the button name will just be italicized. But if a ToolStripItem or ButtonBase is provided (typically a ToolStripButton or a plain Button), then the config button is rendered as a button on the reference table. If the button in question contains an image, that image is displayed here as well and the original single-quoted button name is attached as a tooltip; otherwise, the button gets a textual label with the button name. If a textual label is used, there is one further option available. By default, the textual label will be the text surrounded by single quotes. But if this text contains parentheses, the text before the parentheses is used as the text on the displayed label and the parenthetical text is used as the tooltip. This is handy, for example, on a file picker button that is commonly displayed with an ellipsis (...). Well, supplying a string of '...' will show the button just fine, but the tool tip would also be '...', which is not terribly useful. Therefore, use instead something like ... (file picker) which assigns '...' to the button label and 'file picker' to its tooltip. Click on the thumbnail at right for a screenshot of the DisplayCommandsForm.

Finally, while you may include only a single button reference in a shortcut description, you may include any number of keystrokes, using a [k]key[k] notation. If, for example, the config button given above needs Control and Shift modifier keys, use this: [k]Ctrl[k][k]Shift[k][b]config[b]. These keystrokes are rendered with a tight bounding box around each.

To automatically snap this form onto the same monitor as your application in a multiple-monitor environment, set the Owner property to the application's Form instance (either this.ParentForm or this.FindForm() depending on your context). For further refining the position, you may optionally set the ParentRelativeLocation property, useful in cases where you have instances of this subform invoked by more than one control on your main form.

This DisplayElement collection includes two groups of commands, each prefaced with a category. Note that this definition of userCommands must be separate from its declaration because it includes references to form elements (e.g. newFileButton). If you are not referencing any such tool strip items, you could declare and define it at once.

userCommands = new Collection<DisplayElement>
{
    new CategoryElement("SEARCH and FILTER"),
    new CommandElement("Start search (query)","[k]Ctrl[k][k]F[k]"),
    new CommandElement("Search again (query)","[k]F3[k]"),
    new CommandElement("Search result set", "[k]Ctrl[k][k]/[k]",
        "Opens search pane; not available until you sort"),
    new CommandElement("Filter result set", "[k]Ctrl[k][k].[k]",
        "Opens filtering pane for the current column"),
        
    new CategoryElement("GENERAL"),
    new CommandElement("New file","[b]New file[b] button",
        "Clears the file name and empties the buffer", newFileButton),
    new CommandElement("Refresh","[k]F5[k]"),
    new CommandElement("Adjust width", "[k]Alt[k][k]a[k]", "Sets width to fit data"),
    new CommandElement("Move to next/previous control", "[k]Tab[k] / [k]Shift[k][k]Tab[k]",
        "May be swapped with Ctrl+Tab depending on settings")
};

The collection is fed to the DisplayCommandsForm constructor using late-binding; i.e., the form is not built until the user asks to see the command list. This lets you tailor the command list dynamically or to adjust display parameters of the form (category colors, title color, etc.)

public void ShowUserCommands(string title)
{
    DisplayCommandsForm userCommandsForm
        = new DisplayCommandsForm(userCommands);
    userCommandsForm.Description = "subtext here";
    userCommandsForm.ShowList(title);
}

See the user command collection for the CleanCode.GeneralComponents.SqlEditorControls.SqlEditor for a rich example.

Since CleanCode 0.9.23.

Requirements

Namespace: CleanCode.GeneralComponents.Dialogs

Assembly: CleanCode.GeneralComponents (in CleanCode.GeneralComponents.dll)

DisplayCommandsForm Class

Thread Safety

Remarks

Requirements

See Also