RibbonBar

Namespace: Wisej.Web.Ext.RibbonBar

Assembly: Wisej.Web.Ext.RibbonBar (4.1.0.0)

• Control
  • RibbonBar

The RibbonBar organizes the features of an application into a series of tabs.

C#

public class RibbonBar : Control, IWisejDesignTarget

VB.NET

Public Class RibbonBar
    Inherits Control
    Implements IWisejDesignTarget

The RibbonBar is a command bar that organizes the features of an application into a series of tabs at the top of the application main page or window.

The RibbonBar user interface (UI) increases discoverability of features and functions, enables quicker learning of the application, and makes users feel more in control of their experience with the application.

The RibbonBar replaces the traditional menu bar and toolbars.

The content is organized in a hierarchy: the Pages collection contains RibbonBarPage tabs, each page contains RibbonBarGroup panels (Groups), and each group contains RibbonBarItem components (Items) such as RibbonBarItemButton, RibbonBarItemCheckBox or RibbonBarItemComboBox.

The events fired by the child components are also routed to the RibbonBar (ItemClick, MenuButtonItemClick, GroupClick, ItemValueChanged), allowing the application to handle all the ribbon commands in a single handler.

Example:

Building a simple ribbon in code and handling all the item clicks in one place:

var ribbonBar = new RibbonBar();

var home = new RibbonBarPage { Text = "&Home" };
var clipboard = new RibbonBarGroup { Text = "Clipboard" };
clipboard.Items.Add(new RibbonBarItemButton { Name = "paste", Text = "Paste", ImageSource = "icon-paste" });
clipboard.Items.Add(new RibbonBarItemButton { Name = "cut", Text = "Cut", Orientation = Orientation.Horizontal });
clipboard.Items.Add(new RibbonBarItemButton { Name = "copy", Text = "Copy", Orientation = Orientation.Horizontal });
home.Groups.Add(clipboard);
ribbonBar.Pages.Add(home);

ribbonBar.ItemClick += (s, e) =>
{
    AlertBox.Show("Clicked: " + e.Item.Name);
};

this.Controls.Add(ribbonBar);

Constructors

RibbonBar()

Initializes a new instance of the RibbonBar control.

The new control is docked to the top (Top), has AutoSize set to true, is not focusable and doesn't cause validation (CausesValidation is false).

Properties

AppButton

RibbonBarAppButton: Returns the application button displayed before the first RibbonBarPage.

The RibbonBarAppButton instance is always available and created on first use, but it's hidden by default: set Visible to true to show it. Clicking the button fires the AppButtonClick event.

Example:

Showing the application button and opening a menu page when it's clicked:

this.ribbonBar1.AppButton.Text = "File";
this.ribbonBar1.AppButton.BackColor = Color.SteelBlue;
this.ribbonBar1.AppButton.ForeColor = Color.White;
this.ribbonBar1.AppButton.Visible = true;

this.ribbonBar1.AppButtonClick += (s, e) =>
{
    new FileMenuDialog().ShowDialog();
};

AutoSize

Boolean: Returns or sets a value that indicates whether the control resizes based on its contents. (Default: False)

Value: true if the control automatically resizes based on its contents; otherwise, false. The default is true.

When true, the height of the RibbonBar is measured on the client (it depends on the theme and on the content of the pages) and sent back to the server, see GetPreferredSize. The measured height is limited by MinimumSize and MaximumSize. The height is not adjusted when the control is docked to the left, right or fill, or when it's anchored to both the top and the bottom.

CausesValidation

Boolean: Returns or sets whether clicking RibbonBar items causes validation to be performed on the active control. (Default: False)

Value: true if clicking RibbonBar items causes validation to be performed on the active control; otherwise, false. The default is false.

When true, the active control is validated before the ItemClick and MenuButtonItemClick events (and the corresponding events on the items) are fired. If the validation is cancelled, the events are not fired. The GroupClick and ItemValueChanged events are not affected. Note that the Checked and Checked values are updated before the validation takes place.

Example:

Validating the field being edited before executing a ribbon command:

this.ribbonBar1.CausesValidation = true;

private void textBoxAmount_Validating(object sender, CancelEventArgs e)
{
    if (!decimal.TryParse(this.textBoxAmount.Text, out _))
    {
        AlertBox.Show("Please enter a valid amount.");
        e.Cancel = true;
    }
}

// not called when textBoxAmount fails validation.
private void ribbonBar1_ItemClick(object sender, RibbonBarItemEventArgs e)
{
    if (e.Item.Name == "save")
        SaveDocument();
}

CompactView

Boolean: Returns or sets the compact view mode. (Default: False)

Value: true if only the tab strip is visible; otherwise, false. The default is false.

In compact view only the tab buttons are displayed and no page is shown as selected. When the user clicks a tab, the page is displayed temporarily on top of the content below the RibbonBar and it collapses again when the user clicks anywhere outside of the ribbon (clicks on its drop down menus and popups are ignored). The server-side SelectedPage keeps the last page selected by the user. The height of the control is saved when entering the compact view and restored when leaving it. Changing the value fires the CompactViewChanged event.

Example:

Toggling the compact view from a button:

private void buttonCollapse_Click(object sender, EventArgs e)
{
    this.ribbonBar1.CompactView = !this.ribbonBar1.CompactView;
}

private void ribbonBar1_CompactViewChanged(object sender, EventArgs e)
{
    this.buttonCollapse.ImageSource = this.ribbonBar1.CompactView ? "icon-down" : "icon-up";
}

DefaultSize

Size:

Value: The default Size of the control.

ImageList

ImageList: Returns or sets the collection of images available to the RibbonBar items. (Default: null)

Value: An ImageList that contains images available to the RibbonBarItem controls. The default is null.

The images in the list are referenced by the ImageIndex and ImageKey properties of the items and by ImageIndex and ImageKey.

Example:

Assigning images to the ribbon items using an ImageList:

this.ribbonBar1.ImageList = this.imageList1;
this.buttonSave.ImageKey = "save.png";
this.buttonPrint.ImageIndex = 2;

Pages

RibbonBarPageCollection: Returns the collection of RibbonBarPage pages in the RibbonBar.

Each page is displayed as a tab in the ribbon. Adding a page to the collection sets its Parent to this RibbonBar. When the selected page is removed, the first visible page becomes the SelectedPage. Pages can be retrieved by index or by name (case insensitive).

Example:

Adding a page with a group and finding it again by name:

var insert = new RibbonBarPage { Name = "insert", Text = "&Insert" };
var tables = new RibbonBarGroup { Text = "Tables" };
tables.Items.Add(new RibbonBarItemButton { Name = "insertTable", Text = "Table", ImageSource = "icon-table" });
insert.Groups.Add(tables);
this.ribbonBar1.Pages.Add(insert);

// later...
this.ribbonBar1.Pages["insert"].Enabled = false;

SelectedPage

RibbonBarPage: Returns or sets the currently active RibbonBarPage.

When no page has been selected yet, the getter returns the first visible page in Pages, or null when there are no visible pages. Changing the value, either in code or when the user clicks a tab, fires the SelectedPageChanged event. You can also use Selected.

Throws:

• ArgumentNullException The value is null.
• ArgumentException The RibbonBarPage doesn't belong to this RibbonBar.

Example:

Switching to a contextual page when the user selects a picture:

private void pictureBox1_Click(object sender, EventArgs e)
{
    var page = this.ribbonBar1.Pages["pictureTools"];
    page.Visible = true;
    this.ribbonBar1.SelectedPage = page;
}

private void ribbonBar1_SelectedPageChanged(object sender, EventArgs e)
{
    this.labelStatus.Text = "Page: " + this.ribbonBar1.SelectedPage?.Text;
}

Tools

ComponentToolCollection: Returns the instance of ComponentToolCollection associated with this control.

The tools are displayed as small icon buttons in the tab strip, next to the RibbonBarPage tabs. Clicking a tool fires the ToolClick event.

Example:

Adding a help tool to the tab strip:

this.ribbonBar1.Tools.Add(new ComponentTool
{
    Name = "help",
    ImageSource = "icon-help",
    ToolTipText = "Help"
});

this.ribbonBar1.ToolClick += (s, e) =>
{
    if (e.Tool.Name == "help")
        Application.Navigate("https://docs.wisej.com", "_blank");
};

Methods

Dispose(disposing)

Disposes of the resources (other than memory) used by the RibbonBar.

Parameter	Type	Description
disposing	Boolean	true when this method is called by the application rather than a finalizer.

GetPreferredSize(proposedSize)

Retrieves the size of a rectangular area into which a control can be fitted.

Parameter	Type	Description
proposedSize	Size	The custom size specified for the control.

Returns: Size. The Size representing the preferred size of the control.

The proposedSize is ignored. The returned size is the current size of the control with the height replaced by the height measured on the client, limited by MinimumSize and MaximumSize. The current size is returned unchanged when the height is not known yet or when the control is docked to the left, right or fill, or anchored to both the top and the bottom.

Example:

Reading the height that the RibbonBar needs:

var size = this.ribbonBar1.GetPreferredSize(Size.Empty);
this.panelContent.Top = size.Height;

OnAddReferences(items)

Returns a collection of referenced components or collection of components.

Parameter	Type	Description
items	IList

OnAppButtonClick(e)

Fires the AppButtonClick event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnCompactViewChanged(e)

Fires the CompactViewChanged event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnGroupClick(e)

Fires the GroupClick event.

Parameter	Type	Description
e	RibbonBarGroupEventArgs	A RibbonBarGroupEventArgs that contains the event data.

OnItemClick(e)

Fires the ItemClick event.

Parameter	Type	Description
e	RibbonBarItemEventArgs	A RibbonBarItemEventArgs that contains the event data.

OnItemValueChanged(e)

Fires the ItemValueChanged event.

Parameter	Type	Description
e	RibbonBarItemEventArgs	A RibbonBarItemEventArgs that contains the event data.

OnMenuButtonItemClick(e)

Fires the MenuButtonItemClick event.

Parameter	Type	Description
e	RibbonBarMenuItemEventArgs	A MenuButtonItemClickedEventArgs that contains the event data.

OnSelectedPageChanged(e)

Fires the SelectedPageChanged event.

Parameter	Type	Description
e	EventArgs	A EventArgs that contains the event data.

OnToolClick(e)

Fires the ToolClick event.

Parameter	Type	Description
e	ToolClickEventArgs	A ToolClickEventArgs that contains the event data.

OnWebEvent(e)

Processes the event from the client.

Parameter	Type	Description
e	WisejEventArgs	Event arguments.

OnWebRender(config)

Renders the client component.

Parameter	Type	Description
config	Object	Dynamic configuration object.

ValidateActiveControl()

Validates the current control.

Returns: Boolean. true if the active control is validated.

Events

AppButtonClick

EventHandler Fired when the AppButton is clicked.

CompactViewChanged

EventHandler Fired when the property CompactView changes value.

GroupClick

RibbonBarGroupEventHandler Fired when the user clicks on a RibbonBarGroup button.

ItemClick

RibbonBarItemEventHandler Fired when the user clicks on a RibbonBarItem.

ItemValueChanged

RibbonBarItemEventHandler Fired when the user changes the value of a RibbonBarItem.

MenuButtonItemClick

RibbonBarMenuItemEventHandler Fired when the user clicks one of the drop down menu items of a RibbonBarItemButton or RibbonBarItemSplitButton.

SelectedPageChanged

EventHandler Fired when the value of the SelectedPage property changes.

ToolClick

ToolClickEventHandler Fired when a ComponentTool is clicked.

Implements

Name	Description
IWisejDesignTarget
IUserData
IBindableComponent
IDropTarget
IWisejComponent
IWisejControl
IWisejSerializable