Command builders automate the process of creating widgets, associating them with command sources and adding them to a menu, toolbar or a ribbon. All command builders inherit from the NCommandBuilder class, which provides a set of protected virtual methods that let you easily create common widgets like labels, combo boxes, check boxes, text boxes, menu items, split buttons, etc.

All command builders also expose a Name property, which can be used to obtain a builder from a command builder collection by name. The Name property is also used in the resulting UI depending on the builder, for example as a title of a ribbon group, name of a toolbar, text of a menu drop down, etc.

Nevron Open Vision can create two types of commanding UI - ribbon based and command bar based. Both types of UI builders inherit from the NCommandUIBuilder class, which contains two abstract methods for creating a status bar builder and a widget that should host the command based UI. The latter is implemented by the ribbon and command bar UI builders, so you will only have to provide implementation of the CreateStatusBarBuilder method. The command UI builder provides a CreateUI method that should be called to create the UI of the builder:

NRichTextRibbonBuilder ribbonBuilder = new NRichTextRibbonBuilder();
NWidget widget = ribbonBuilder.CreateUI(m_RichText);

You can also pass a host widget to the CreateUI method if the widget that should be placed in the center of the commanding UI is different from the command target. The sections below examine these two types of command UI builders in more details.

Command UI builders contain collections, which hold the ribbon group builders for ribbon UI builders and the menu drop down and toolbar builders for command bar UI builders. You can use these collections to add, insert or remove command builders from the UI builder. All of these collections inherit the NCommandBuilderCollection generic type and provide the following useful properties and methods:

• this[string name] - lets you get a command builder by name.
• IndexOf(string name) - returns the index of the command builder with the given name in the collection or -1 if a builder with such name does not exist in the collection
• Remove(string name) - finds a command builder with the given name and if found removes it from this collection and returns true, otherwise the method does nothing and returns false.

You can also use the Add, Insert, Remove and RemoveAt methods inherited from NList to modify the items of the collection. The following piece of code demonstrates how to remove the "Clipboard" ribbon group of a rich text ribbon builder and how to add a custom one.

// Remove the "Clipboard" ribbon group from the "Home" tab page of the rich text ribbon
NRibbonTabPageBuilder homeTabBuilder = m_RibbonBuilder.TabPageBuilders[NRichTextRibbonBuilder.TabPageHomeName];
homeTabBuilder.RibbonGroupBuilders.Remove(NHomeTabPageBuilder.GroupClipboardName);

// Insert a custom ribbon group at the beginning of the home tab page
homeTabBuilder.RibbonGroupBuilders.Insert(0, new CustomRibbonGroup());

The NRibbonUIBuilder abstract class is the base class for creating ribbon based command UI. The host control of ribbon based UI is a dock panel. The NRibbonUIBuilder class contains two abstract methods that should be implemented by ribbon UI builders:

• CreateApplicationMenu - creates the application menu of the ribbon. It's equivalent to the File menu in the classic command bar based UI.
• AddTabPageBuilders - adds ribbon tab page builders to the collection of builder of the ribbon UI builder. You can use this method to add, remove or rearrange the tab pages of the ribbon.

If you want the ribbon to also have a help button, you should override the HelpButtonCommand property of the ribbon UI builder to return the command whose command action should be executed when the user clicks the help button. The default implementation of this property returns null, which means that the help button of the ribbon will not be visible.

The following code example demonstrates how to create a simple ribbon UI builder:

public class NRichTextRibbonBuilder : NRibbonUIBuilder
{
    protected override NApplicationMenu CreateApplicationMenu()
    {
        NApplicationMenu appMenu = new NApplicationMenu("File", false);

        NMenuItemCollection items = appMenu.MenuPane.Items;
        items.Add(CreateMenuItem(NResources.Image_Ribbon_32x32_AppMenu_New_png, NRichTextView.NewCommand));
        items.Add(CreateMenuItem(NResources.Image_Ribbon_32x32_AppMenu_Open_png, NRichTextView.OpenCommand));
        items.Add(CreateMenuItem(NResources.Image_Ribbon_32x32_AppMenu_Save_png, NRichTextView.SaveCommand));
        items.Add(CreateMenuItem(NResources.Image_Ribbon_32x32_AppMenu_SaveAs_png, NRichTextView.SaveAsCommand));
        items.Add(CreateMenuItem(NResources.Image_Ribbon_32x32_AppMenu_Print_png, NRichTextView.PrintCommand));

        return appMenu;
    }

    protected override void AddTabPageBuilders(NCommandBuilderCollection<NRibbonTabPageBuilder> tabPageBuilders)
    {
        tabPageBuilders.Add(new NHomeTabPageBuilder());
        tabPageBuilders.Add(new NInsertTabPageBuilder());
        tabPageBuilders.Add(new NPageLayoutTabPageBuilder());
        tabPageBuilders.Add(new NTableTabPageBuilder());
        tabPageBuilders.Add(new NViewTabPageBuilder());
        tabPageBuilders.Add(new NReviewTabPageBuilder());
        tabPageBuilders.Add(new NMailingsTabPageBuilder());
    }

    protected override NStatusBarBuilder CreateStatusBarBuilder()
    {
        return new NRichTextStatusBarBuilder();
    }
}

Ribbon tab page builders create the tab pages of the ribbon and should inherit the NRibbonTabPageBuilder class, pass to its constructor the name of the ribbon tab they create and implement the AddRibbonGroupBuilders method to add the ribbon group builders for the ribbon tab.

Ribbon group builders create the ribbon groups of a ribbon tab page and should inherit the NRibbonGroupBuilder class. Pass to its constructor the name of the ribbon group and the image that should be shown when the ribbon group is in collapsed state. Ribbon group builders should implement the AddRibbonGroupItems method to add items to the ribbon group. If you want a ribbon group to have a dialog launcher button, then you should also override the DialogLauncherButtonCommand property of the ribbon group builder to return the command whose command action should be executed when the user clicks the dialog launcher button. The default implementation of this property returns null, which means that the dialog launcher button of the ribbon group will not be visible.

The NCommandBarUIBuilder abstract class is the base class for creating command bar based UI. The host control of command bar based UI is a command bar manager. The NCommandBarUIBuilder contains two abstract methods that should be implemented by command bar UI builders:

• AddMenuDropDownBuilders - adds the menu builders, e.g. the "File" menu builder, the "Edit" menu builder, etc.
• AddToolBarBuilders - adds the toolbar menu builders. You can use the StartsOnNewLane property of toolbar builders to specify which toolbar builder should start on a new lane.

The following code demonstrates how to create a simple command bar UI builder:

public class NRichTextCommandBarBuilder : NCommandBarUIBuilder
{
    protected override void AddMenuDropDownBuilders(NCommandBuilderCollection<NMenuDropDownBuilder> menuBuilders)
    {
        menuBuilders.Add(new NRichTextFileMenuBuilder());
        menuBuilders.Add(new NRichTextEditMenuBuilder());
        menuBuilders.Add(new NRichTextInsertMenuBuilder());
        menuBuilders.Add(new NRichTextViewMenuBuilder());
        menuBuilders.Add(new NRichTextFormatMenuBuilder());
        menuBuilders.Add(new NRichTextTableMenuBuilder());
        menuBuilders.Add(new NRichTextToolsMenuBuilder());
    }

    protected override void AddToolBarBuilders(NCommandBuilderCollection<NToolBarBuilder> toolBarBuilders)
    {
        toolBarBuilders.Add(new NRichTextStandardToolBarBuilder());
        toolBarBuilders.Add(new NRichTextViewToolBarBuilder());

        NToolBarBuilder builder = new NRichTextFormatToolBarBuilder();
        builder.StartsOnNewLane = true;
        toolBarBuilders.Add(builder);

        builder = new NRichTextBlockToolBarBuilder();
        builder.StartsOnNewLane = true;
        toolBarBuilders.Add(builder);
        toolBarBuilders.Add(new NRichTextTableToolBarBuilder());
        toolBarBuilders.Add(new NRichTextMailMergeToolBarBuilder());
    }

    protected override NStatusBarBuilder CreateStatusBarBuilder()
    {
        return new NRichTextStatusBarBuilder();
    }
}

Menu and toolbar builders inherit the NCommandBarBuilder class and has an abstract AddItems method you should implement in order to add menu/toolbar items. You should also pass the name of the command bar to the constructor of the base class.