Nevron Open Vision Documentation
Command Builders
Command Builders Overview

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:

Command UI Creation
Copy Code
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 Builder Collections

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:

You can also use the Add, InsertRemove 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.

Modify a Command Builder Collection
Copy Code
// 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());
Ribbon UI

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:

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:

Ribbon UI Builder
Copy Code
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.

You can override the corresponding Add methods of ribbon UI, ribbon tab and group builders in order to add, remove or rearrange the ribbon tabs, groups and items respectively.

In case you want to remove, add or insert some ribbon group builders from the ribbon builder, you can use the Remove, Add and Insert methods of the RibbonGroupBuilders collection respectively as demonstrated above in the Command Builder Collections section.

Command Bar UI

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:

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

Command Bar UI Builder
Copy Code
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.

You can override the Add methods of command bar UI, menu drop down and toolbar builder to add, remove and rearrange the command bars (menu and toolbars)/menu drop downs/toolbar items respectively.

In case you want to remove, add or insert some menu drop down or toolbar builders from the command bar builder, you can use the Remove, Add and Insert methods of the MenuDropDownBuilders or the ToolBarBuilders collections respectively as demonstrated above in the Command Builder Collections section.

See Also
Send Feedback