Provide Functionality to Bar Items

  • 3 minutes to read

This document explains how to supply bar items with functionality.

Base Bar Item Events

All bar items provide the BarItem.ItemClick event that allows you to respond to end-users clicking this item. At design time, double-click a bar item link to automatically create a handler for this event and switch to this handler's code.


private void barEditItem1_ItemClick(object sender, ItemClickEventArgs e) {
   //do something
}

The item - item link concept allows you to re-use a bar item in multiple separate locations and grant individual appearances for each bar item link. It is presumed however that item functionality is shared across all links of the same bar item. Thus, links do not provide their own Click events and clicking a link always raises events of its parent item.

The BarItem.ItemClick event receives an argument of the ItemClickEventArgs type, which provides read-only ItemClickEventArgs.Item and ItemClickEventArgs.Link properties. Using these properties, you can identify the clicked link and its parent bar item.

Apart from the BarItem.ItemClick event, simple bar items also provide the BarItem.ItemPress and BarItem.ItemDoubleClick events.

Bar Edit Item Events

BarEditItem objects provide the BarEditItem.ShowingEditor, BarEditItem.ShownEditor and BarEditItem.HiddenEditor events, which raise when the editor within the target bar edit item is opened or closed. The BarEditItem.ShowingEditor event can be canceled, which allows you to prevent the editor from opening.


private void eItem1_ShowingEditor(object sender, ItemCancelEventArgs e) {
    e.Cancel = true;
}

For other tasks, handle events provided by embedded editors themselves. For instance, the RepositoryItem.EditValueChanging and RepositoryItem.EditValueChanged events are core events shared among all editors. These events allow you to track the editor's BaseEdit.EditValue property, which reflects the current editor state (entered text for TextEdit editors, active tokens for TokenEdit editors, boolean values for CheckEdit editors, checked items for CheckedComboBoxEdit editors, etc.). The editor EditValueChanged event is also exposed to parent bar edit items, see the BarEditItem.EditValueChanged link to learn more.

Global Bar Manager Events

The BarManager component provides global events raised when any link that belongs to this manager is clicked, pressed, checked, double-clicked, etc. These are the BarManager.ItemClick, BarManager.ItemPress, BarManager.ItemDoubleClick, ComponentEditorContainer.EditorKeyPress and ComponentEditorContainer.EditorKeyUp events. Handle these events to perform actions common to multiple bar item links.


void barManager_ItemClick(object sender, ItemClickEventArgs e) {
    BarSubItem subMenu = e.Item as BarSubItem;
    if (subMenu != null) return;
    MessageBox.Show("Item '" + e.Item.Caption + "' has been clicked");
}

MVVM Command Binding

Most DevExpress controls and components provide the built-in support for the WinForms MVVM pattern. This includes multiple BindCommand and BindCommand[Type] method overloads, which allow you to associate a clickable UI element with the DelegateCommand object. For instance, BarButtonItem objects provide BarButtonItem.BindCommand and BarButtonItem.BindCommand<T> methods.

Delegate commands support the CanExecute condition. If the specific criteria is not met and the boolean CanExecute method returns false, a UI element bound to this command renders as disabled. For instance, end-users will be unable to press the "Edit Record" button if no Data Grid row is currently selected.

Refer to the Commands article to learn more.

See Also