Not logged in▾
Log In Register
Forgot Password Resend Validation E-mail
In This Article

NavigationBar Class

Namespace:
ActiproSoftware.UI.WinForms.Controls.Navigation
Assembly:
ActiproSoftware.Navigation.WinForms.dll

Represents a navigation bar control.

[ToolboxBitmap(typeof(NavigationBar))]
public class NavigationBar : UIControl, IUIControl, IUIElement, ILogicalTreeNode, IDpiAwareElement, IDisposable, IWeakEventListener
Inheritance:
object MarshalByRefObject Component Control ScrollableControl UIControl object
Implements:
IUIControl IUIElement ILogicalTreeNode IDpiAwareElement IDisposable IWeakEventListener

Constructors

NavigationBar()

Initializes an instance of the class.

public NavigationBar()

Properties

CanShowFewerBarButtons

Indicates whether the showing of fewer bar buttons is permitted.

[Browsable(false)]
public bool CanShowFewerBarButtons { get; }

Property Value

bool:

true if the showing of fewer bar buttons is permitted; otherwise, false.

CanShowMoreBarButtons

Indicates whether the showing of more bar buttons is permitted.

[Browsable(false)]
public bool CanShowMoreBarButtons { get; }

Property Value

bool:

true if the showing of more bar buttons is permitted; otherwise, false.

DefaultSize

Gets the default size of the control.

protected override Size DefaultSize { get; }

Property Value

Size:

The default Size of the control.

DisplayRectangle

Gets the rectangle that represents the virtual display area of the control.

public override Rectangle DisplayRectangle { get; }

Property Value

Rectangle:

A Rectangle that represents the display area of the control.

LargeImageList

The ImageList used for large pane images.

public ImageList? LargeImageList { get; set; }

Property Value

ImageList:

The default value is null.

Remarks

The size of the images should be 32x32 however it looks best to leave some outer padding in the images themselves.

LayoutData

The current layout of all the panes managed by this NavigationBar.

[Browsable(false)]
public XmlDocument LayoutData { get; set; }

Property Value

XmlDocument:

An XmlDocument containing the layout data of the NavigationBar layout.

Remarks

This property may throw an exception while loading if the layout data is invalid.

MaximumBarButtonCount

The maximum number of bar buttons to display.

public int MaximumBarButtonCount { get; set; }

Property Value

int:

The default value is 5.

OverflowMenuButtonVisible

Indicates whether the overflow menu button is visible.

public bool OverflowMenuButtonVisible { get; set; }

Property Value

bool:

true if the overflow menu button is visible; otherwise, false.

Panes

The NavigationPaneCollection containing the panes in the control.

public NavigationPaneCollection Panes { get; }

Property Value

NavigationPaneCollection

Renderer

The control-specific INavigationBarRenderer used to render the control.

public INavigationBarRenderer? Renderer { get; set; }

Property Value

INavigationBarRenderer

Remarks

If this value is null, then the global renderer will be used instead.

RendererResolved

The INavigationBarRenderer used to render the control.

[Browsable(false)]
public INavigationBarRenderer RendererResolved { get; }

Property Value

INavigationBarRenderer

Remarks

This property will return a global renderer if there is no control instance renderer override. The registered renderer type with the UIRendererManager for this property is INavigationBarRenderer.

SelectedIndex

The index of the selected item.

[Browsable(false)]
public int SelectedIndex { get; set; }

Property Value

int:

If there are no items in the control or there is no selection, this property returns -1.

Remarks

The index is zero-based.

SelectedPane

The NavigationPane that is currently selected.

[Browsable(false)]
public NavigationPane? SelectedPane { get; set; }

Property Value

NavigationPane

SmallImageList

The ImageList used for small pane images.

public ImageList? SmallImageList { get; set; }

Property Value

ImageList:

The default value is null.

Remarks

The size of the images should be 16x16.

Methods

ArrangeOverride(Size)

Positions child elements and determines an arrange size.

protected override Size ArrangeOverride(Size finalSize)
Parameter Type Description
finalSize Size

The final area within the parent that this element should use to arrange itself and its children.

Returns

Size:

The actual size used.

Remarks

Element authors should override this method, call Arrange(Rectangle) on each visible child element and position each child element. It is required that a parent element calls Arrange(Rectangle) on each child or they won't be rendered.

CanMoveNavigationPaneDown(NavigationPane)

Tests if the given NavigationPane can be moved lower in its position within the collection.

public bool CanMoveNavigationPaneDown(NavigationPane pane)
Parameter Type Description
pane NavigationPane

The NavigationPane to test.

Returns

bool:

true if the NavigationPane can be moved down; otherwise false.

See Also

CanMoveNavigationPaneUp(NavigationPane)

Tests if the given NavigationPane can be moved higher in its position within the collection.

public bool CanMoveNavigationPaneUp(NavigationPane pane)
Parameter Type Description
pane NavigationPane

The NavigationPane to test.

Returns

bool:

true if the NavigationPane can be moved up; otherwise false.

See Also

CreateChildren()

Invoked when the collection of child elements is to be created.

protected override IList<ILogicalTreeNode> CreateChildren()

Returns

IList<ILogicalTreeNode>:

The list that should be assigned to the Children property.

Remarks

By default, no child collection is created.

CreateControlsInstance()

Creates a new instance of the control collection for the control.

protected override Control.ControlCollection CreateControlsInstance()

Returns

Control.ControlCollection:

A new instance of Control.ControlCollection assigned to the control.

Dispose(bool)

Releases the unmanaged resources used by the Control and its child controls and optionally releases the managed resources.

protected override void Dispose(bool disposing)
Parameter Type Description
disposing bool

true to release both managed and unmanaged resources; false to release only unmanaged resources.

HitTest(Point)

Hit tests to find the NavigationPane whose button contains the specified coordinates.

public NavigationPane? HitTest(Point point)
Parameter Type Description
point Point

The Point to test.

Returns

NavigationPane

LoadLayoutFromFile(string)

Load NavigationBar layout data from a layout data file.

public void LoadLayoutFromFile(string path)
Parameter Type Description
path string

Path to the NavigationBar layout data file.

Remarks

This method may throw an exception if the file is not found or if the layout data is invalid.

MeasureOverride(Graphics?, Size)

Measures the size in layout required for child elements and determines a size for the element itself.

protected override Size MeasureOverride(Graphics? g, Size availableSize)
Parameter Type Description
g Graphics

The Graphics object to use for measurement.
availableSize Size

The available size that this element can give to child elements. Infinity can be specified as a value to indicate that the element will size to whatever content is available.

Returns

Size:

The size that this element determines it needs during layout, based on its calculations of child element sizes.

Remarks

Element authors should override this method, call Measure(Graphics?, Size) on each visible child element and determine the total size required.

MoveNavigationPaneDown(NavigationPane)

Moves the given NavigationPane lower in its position within the collection.

public void MoveNavigationPaneDown(NavigationPane pane)
Parameter Type Description
pane NavigationPane

The NavigationPane to move.

Exceptions

Type Condition
ArgumentNullException

Thrown if the argument is null.
ArgumentException

Thrown if the NavigationPane is not a child of this control.
InvalidOperationException

Thrown if the NavigationPane is already at the lowest position.

See Also

MoveNavigationPaneUp(NavigationPane)

Moves the given NavigationPane higher in its position within the collection.

public void MoveNavigationPaneUp(NavigationPane pane)
Parameter Type Description
pane NavigationPane

The NavigationPane to move.

Exceptions

Type Condition
ArgumentNullException

Thrown if the argument is null.
ArgumentException

Thrown if the NavigationPane is not a child of this control.
InvalidOperationException

Thrown if the NavigationPane is already at the highest position.

See Also

OnContextMenuRequested(NavigationBarContextMenuEventArgs)

Raises the ContextMenuRequested event.

protected virtual void OnContextMenuRequested(NavigationBarContextMenuEventArgs e)
Parameter Type Description
e NavigationBarContextMenuEventArgs

The event data.

OnMaximumBarButtonCountChanged(EventArgs)

Raises the MaximumBarButtonCountChanged event.

protected virtual void OnMaximumBarButtonCountChanged(EventArgs e)
Parameter Type Description
e EventArgs

The event data.

OnMouseLeave(EventArgs)

Raises the MouseLeave event.

protected override void OnMouseLeave(EventArgs e)
Parameter Type Description
e EventArgs

An EventArgs that contains the event data.

OnMouseMove(MouseEventArgs)

Raises the MouseMove event.

protected override void OnMouseMove(MouseEventArgs e)
Parameter Type Description
e MouseEventArgs

A MouseEventArgs that contains the event data.

OnNavigationPaneActiveChanging(NavigationPaneCancelEventArgs)

Raises the NavigationPaneActiveChanging event.

protected virtual void OnNavigationPaneActiveChanging(NavigationPaneCancelEventArgs e)
Parameter Type Description
e NavigationPaneCancelEventArgs

The event data.

OnNavigationPanesReordered(EventArgs)

Raises the NavigationPanesReordered event.

protected virtual void OnNavigationPanesReordered(EventArgs e)
Parameter Type Description
e EventArgs

The event data.

OnRender(PaintEventArgs)

Renders the element.

protected override void OnRender(PaintEventArgs e)
Parameter Type Description
e PaintEventArgs

The event data.

OnSelectionChanged(EventArgs)

Raises the SelectionChanged event.

protected virtual void OnSelectionChanged(EventArgs e)
Parameter Type Description
e EventArgs

The event data.

OnSelectionChanging(NavigationPaneCancelEventArgs)

Raises the SelectionChanging event.

protected virtual void OnSelectionChanging(NavigationPaneCancelEventArgs e)
Parameter Type Description
e NavigationPaneCancelEventArgs

The event data.

ResetLargeImageList()

Resets the LargeImageList property to its default value.

public virtual void ResetLargeImageList()

ResetSmallImageList()

Resets the SmallImageList property to its default value.

public virtual void ResetSmallImageList()

SaveLayoutToFile(string)

Saves the current layout of all the panes managed by this NavigationBar to a layout data file.

public void SaveLayoutToFile(string path)
Parameter Type Description
path string

Path to the NavigationBar layout data file.

Remarks

The output layout data is stored in XML format.

ShouldSerializeLargeImageList()

Indicates whether the LargeImageList property should be persisted.

public virtual bool ShouldSerializeLargeImageList()

Returns

bool:

true if the property value has changed from its default; otherwise, false.

ShouldSerializeSmallImageList()

Indicates whether the SmallImageList property should be persisted.

public virtual bool ShouldSerializeSmallImageList()

Returns

bool:

true if the property value has changed from its default; otherwise, false.

ShowFewerBarButtons()

Decreases the value of MaximumBarButtonCount by 1 so fewer buttons are displayed.

public void ShowFewerBarButtons()

ShowMoreBarButtons()

Increases the value of MaximumBarButtonCount by 1 so more buttons are displayed.

public void ShowMoreBarButtons()

ShowNavigationBarOptionsForm(Form?)

Displays the Navigation Bar Options form.

public void ShowNavigationBarOptionsForm(Form? ownerForm = null)
Parameter Type Description
ownerForm Form

The owner Form.

WndProc(ref Message)

Processes Windows messages.

protected override void WndProc(ref Message m)
Parameter Type Description
m Message

The Windows Message to process.

Events

ContextMenuRequested

Occurs when a context menu needs to be displayed.

public event NavigationBarContextMenuEventHandler? ContextMenuRequested

Event Type

NavigationBarContextMenuEventHandler

Remarks

The display of the default menu may be cancelled by setting the Cancel property of the event arguments to true.

MaximumBarButtonCountChanged

Occurs when the value of the MaximumBarButtonCount has changed.

public event EventHandler? MaximumBarButtonCountChanged

Event Type

EventHandler

NavigationPaneActiveChanging

Occurs before the Active property on a NavigationPane changes.

public event NavigationPaneCancelEventHandler? NavigationPaneActiveChanging

Event Type

NavigationPaneCancelEventHandler

Remarks

Use this event to perform any processing that should occur before the Active property on a NavigationPane changes. The NavigationPane property of the event arguments indicates the NavigationPane that is affected. The property change may be cancelled by setting the Cancel property of the event arguments to true.

NavigationPanesReordered

Occurs when the panes are reordered via the Navigation Bar Options dialog.

public event EventHandler? NavigationPanesReordered

Event Type

EventHandler

SelectionChanged

Occurs after the selection changes.

public event EventHandler? SelectionChanged

Event Type

EventHandler

Remarks

Use this event to perform any processing that should occur after the selection changes.

SelectionChanging

Occurs before the selection changes.

public event NavigationPaneCancelEventHandler? SelectionChanging

Event Type

NavigationPaneCancelEventHandler

Remarks

Use this event to perform any processing that should occur before selection changes. The NavigationPane property of the event arguments indicates the NavigationPane about to be selected. The selection change may be cancelled by setting the Cancel property of the event arguments to true.

Inherited Members

Extension Methods