Class RadBindingNavigator

Represents a navigation control that provides a standardized interface for browsing and manipulating data through a BindingSource. This control includes built-in buttons for moving through records, adding new records, deleting records, and saving changes with support for both horizontal and vertical orientations.

Inheritance
System.Object
RadControl
RadBindingNavigator
Inherited Members
Namespace: Telerik.WinControls.UI
Assembly: Telerik.WinControls.UI.dll

Syntax

[TelerikToolboxCategory("Data Controls")]
public class RadBindingNavigator : RadControl, INotifyPropertyChanged, ISupportInitializeNotification, ISupportInitialize, IComponentTreeHandler, ILayoutHandler, IPCHost, IAnalyticsProvider

Constructors

RadBindingNavigator()

Initializes a new instance of the RadBindingNavigator class with auto-sizing enabled by default to accommodate the navigation controls.

Declaration
public RadBindingNavigator()

Fields

OrientationChangedEventKey

The event key used to identify and manage the OrientationChanged event in the control's event collection.

Declaration
public static readonly object OrientationChangedEventKey
Field Value
System.Object

OrientationChangingEventKey

The event key used to identify and manage the OrientationChanging event in the control's event collection.

Declaration
public static readonly object OrientationChangingEventKey
Field Value
System.Object

Properties

AutoHandleAddNew

Gets or sets a value indicating whether the control automatically handles the creation of new items when the add new button is clicked. When set to true, the control manages the add new operation internally.

Declaration
public bool AutoHandleAddNew { get; set; }
Property Value
System.Boolean

AutoSize

Gets or sets a value indicating whether the control automatically resizes to fit its contents, ensuring optimal space usage for the navigation elements.

Declaration
public override bool AutoSize { get; set; }
Property Value
System.Boolean

Overrides

BindingNavigatorElement

Gets the main binding navigator element that contains all the navigation controls and data binding functionality. This element is not accessible through the designer and provides programmatic access to the core navigation features.

Declaration
public RadBindingNavigatorElement BindingNavigatorElement { get; }
Property Value
RadBindingNavigatorElement

BindingSource

Gets or sets the BindingSource that provides the data source for navigation operations. This binding source determines which data collection the navigator controls and enables data manipulation features.

Declaration
public BindingSource BindingSource { get; set; }
Property Value
System.Windows.Forms.BindingSource

CountItemFormat

Gets or sets the format string used to display the total count of items in the data source. The format string should contain a placeholder like "{0}" which will be replaced with the actual count value.

Declaration
public string CountItemFormat { get; set; }
Property Value
System.String

CustomizeContextMenu

Gets the RadDropDownMenu that appears when right-clicking on the control, providing customization options for strip visibility and layout configuration.

Declaration
public RadDropDownMenu CustomizeContextMenu { get; }
Property Value
RadDropDownMenu

DefaultSize

Gets the default size of the control when no explicit size is specified, providing a minimum usable dimension for the navigation interface.

Declaration
protected override Size DefaultSize { get; }
Property Value
System.Drawing.Size

Dock

Gets or sets which edges of the RadBindingNavigator are docked to its parent control and determines how the control is resized with its parent. Setting this property automatically adjusts the Orientation based on the dock position.

Declaration
public override DockStyle Dock { get; set; }
Property Value
System.Windows.Forms.DockStyle

One of the System.Windows.Forms.DockStyle values. The default is System.Windows.Forms.DockStyle.None.
Exceptions
System.ComponentModel.InvalidEnumArgumentException

The value assigned is not one of the System.Windows.Forms.DockStyle values.

DragSize

Gets or sets the size of the rectangle centered on the initial mouse click point within which a drag operation will not begin, providing a tolerance area for click operations versus drag initiation.

Declaration
public Size DragSize { get; set; }
Property Value
System.Drawing.Size

Orientation

Gets or sets the orientation of the RadBindingNavigator which can be horizontal or vertical. This property is automatically controlled by the Dock property to ensure proper layout based on docking position.

Declaration
public Orientation Orientation { get; set; }
Property Value
System.Windows.Forms.Orientation

Rows

Gets the collection of command bar rows that contain the navigation buttons and controls. This collection allows customization of the navigator layout and addition of custom command elements.

Declaration
[RadNewItem("", false, true, true)]
[RadEditItemsAction]
public RadCommandBarLinesElementCollection Rows { get; }
Property Value
RadCommandBarLinesElementCollection

Text

This property is not relevant for this class.

Declaration
public override string Text { get; set; }
Property Value
System.String

Overrides

Methods

ControlDefinesThemeForElement(RadElement)

Determines whether this control defines the theme for the specified element, returning true for specific element types that require themed appearance consistent with the binding navigator.

Declaration
public override bool ControlDefinesThemeForElement(RadElement element)
Parameters
RadElement element

The RadElement to check for theme definition responsibility.
Returns
System.Boolean

True if this control defines the theme for the specified element; otherwise, false.
Overrides

CreateChildItems(RadElement)

Creates the child items for the navigator control, including the main navigator element and context menu infrastructure for customization options.

Declaration
protected override void CreateChildItems(RadElement parent)
Parameters
RadElement parent

The parent element that will contain the created child items.
Overrides

CreateNavigatorElement()

Creates the RadBindingNavigatorElement element.

Declaration
protected virtual RadBindingNavigatorElement CreateNavigatorElement()
Returns
RadBindingNavigatorElement

An instance of RadBindingNavigatorElement.

CreateRootElement()

Creates the root element for the RadBindingNavigator control, providing the foundational container for all child elements.

Declaration
protected override RootRadElement CreateRootElement()
Returns
RootRadElement

A new instance of RadBindingNavigator.RadBindingNavigatorRootElement that serves as the root container.
Overrides

OnContextMenuOpening(CancelEventArgs)

Raises the ContextMenuOpening event, allowing derived classes to perform custom processing when the context menu is about to be displayed.

Declaration
protected virtual void OnContextMenuOpening(CancelEventArgs e)
Parameters
System.ComponentModel.CancelEventArgs e

A System.ComponentModel.CancelEventArgs that contains the event data and allows cancellation of the menu display.

OnContextMenuOpenting(CancelEventArgs)

This method is not relevant for this class.

Declaration
[Obsolete("Obsolete. The name of the method has a typo. Use the OnContextMenuOpening(CancelEventArgs e) method instead.")]
protected virtual void OnContextMenuOpenting(CancelEventArgs e)
Parameters
System.ComponentModel.CancelEventArgs e

The event arguments.

OnLoad(Size)

Called when the control is loaded with the specified desired size, enabling gesture support for pan operations on the navigation interface.

Declaration
protected override void OnLoad(Size desiredSize)
Parameters
System.Drawing.Size desiredSize

The desired size for the control during the load operation.
Overrides

OnMouseDown(MouseEventArgs)

Handles mouse down events, specifically processing right-click operations to display the context menu for strip customization when clicking on appropriate areas of the control.

Declaration
protected override void OnMouseDown(MouseEventArgs e)
Parameters
System.Windows.Forms.MouseEventArgs e

Mouse event arguments containing button information and click location.
Overrides

OnOrientationChanged(EventArgs)

Raises the OrientationChanged event to notify subscribers that the orientation change has been completed successfully.

Declaration
protected virtual void OnOrientationChanged(EventArgs args)
Parameters
System.EventArgs args

An System.EventArgs that contains the event data for the orientation change notification.

OnOrientationChanging(CancelEventArgs)

Raises the OrientationChanging event and determines whether the orientation change should be cancelled based on subscriber responses.

Declaration
protected virtual bool OnOrientationChanging(CancelEventArgs args)
Parameters
System.ComponentModel.CancelEventArgs args

A System.ComponentModel.CancelEventArgs that contains the event data and cancellation flag.
Returns
System.Boolean

True if the orientation change should be cancelled; otherwise, false.

OnParentChanged(EventArgs)

Called when the parent of the control changes, managing the attachment and detachment of event handlers for the parent form's size changes to handle floating strip visibility properly.

Declaration
protected override void OnParentChanged(EventArgs e)
Parameters
System.EventArgs e

Event arguments containing information about the parent change.
Overrides

OnThemeChanged()

Called when the theme of the control changes, ensuring that theme settings are properly propagated to all child elements and context menu components.

Declaration
protected override void OnThemeChanged()
Overrides

ProcessAutoSizeChanged(Boolean)

Overrides the auto-size change processing to prevent default behavior, allowing the control to manage its own sizing logic for the navigation interface.

Declaration
protected override void ProcessAutoSizeChanged(bool value)
Parameters
System.Boolean value

The new auto-size value being applied.
Overrides

ProcessCodedUIMessage(ref IPCMessage)

Processes CodedUI automation messages, handling specific property requests such as "Lines" count for automated testing scenarios and delegating other requests to the base implementation.

Declaration
protected override void ProcessCodedUIMessage(ref IPCMessage request)
Parameters
IPCMessage request

The CodedUI message containing the automation request details and response data.
Overrides

ResetBackColorThemeOverrides()

Resets the background color theme overrides to their default values, removing custom background color settings and reapplying the default theme to the element tree.

Declaration
protected override void ResetBackColorThemeOverrides()
Overrides

ResetForeColorThemeOverrides()

Resets the foreground color theme overrides to their default values, removing custom foreground color settings from the binding navigator element.

Declaration
protected override void ResetForeColorThemeOverrides()
Overrides

SetBackColorThemeOverrides()

Sets theme overrides for the background color properties, applying the control's background color and solid gradient style to the binding navigator element and command bar rows.

Declaration
protected override void SetBackColorThemeOverrides()
Overrides

SetForeColorThemeOverrides()

Sets theme overrides for the foreground color property, applying the control's foreground color to the binding navigator element for consistent text appearance.

Declaration
protected override void SetForeColorThemeOverrides()
Overrides

SetOrientationCore(Orientation, Boolean)

Applies the specified orientation to the control and its child elements, managing the layout transition and event firing based on the parameters provided.

Declaration
protected virtual void SetOrientationCore(Orientation value, bool fireEvents)
Parameters
System.Windows.Forms.Orientation value

The Orientation value to apply to the control layout.
System.Boolean fireEvents

True to fire the OrientationChanging and OrientationChanged events; otherwise, false.

SetThemeCore()

Propagates the current theme name to child command bar elements and their overflow buttons, ensuring consistent visual appearance across all navigation components.

Declaration
protected virtual void SetThemeCore()

Events

ContextMenuOpening

Occurs when the context menu is about to be opened, allowing the menu display to be cancelled or customized through the event arguments.

Declaration
public event CancelEventHandler ContextMenuOpening
Event Type
System.ComponentModel.CancelEventHandler

FloatingStripCreated

Occurs after a floating toolbar strip has been successfully created, providing notification that the floating form is now available for user interaction.

Declaration
public event EventHandler FloatingStripCreated
Event Type
System.EventHandler

FloatingStripCreating

Occurs before a floating toolbar strip is created, allowing the operation to be cancelled. This event provides control over the floating strip creation process.

Declaration
public event CancelEventHandler FloatingStripCreating
Event Type
System.ComponentModel.CancelEventHandler

FloatingStripDocked

Occurs after a floating toolbar strip has been successfully docked back to the main control, confirming that the docking operation has been completed.

Declaration
public event EventHandler FloatingStripDocked
Event Type
System.EventHandler

FloatingStripDocking

Occurs before a floating toolbar strip is docked back to the main control, allowing the docking operation to be cancelled through the event arguments.

Declaration
public event CancelEventHandler FloatingStripDocking
Event Type
System.ComponentModel.CancelEventHandler

OrientationChanged

Occurs after the Orientation property has been changed, notifying subscribers that the layout orientation transition has been completed.

Declaration
public event EventHandler OrientationChanged
Event Type
System.EventHandler

OrientationChanging

Occurs before the Orientation property changes, allowing the change to be cancelled through the event arguments. This event provides an opportunity to validate or prevent orientation changes.

Declaration
public event CancelEventHandler OrientationChanging
Event Type
System.ComponentModel.CancelEventHandler

Extension Methods