Accessing DotNetBar Items

To access any item inside of DotNetBar whether button, progress bar, control container item, label etc. simply reference the member variable that was created by Windows Forms designer as part of your form class. If you have multiple items that perform same function, like for example Save button that is displayed on toolbar and menu bar, and you want to disable the button, you do not have to disable all instances, rather use DotNetBar Global Items feature. Set the GlobalName property for each item to the same ID, like “Save” and DotNetBar will propagate certain changes on items to all items with same Name or GlobalName. For more information about this feature see Global Items topic.

You can also access the items through DotNetBarManager and there are two different paths that you can take:

  1. Access the item through collection properties, i.e. DotNetBarManager.Bars[“mybar”].Items[“myitem”]
  2. Access the item using DotNetBarManager.GetItem or DotNetBarManager.GetItems methods.

We recommend method 2. to access your items because, if you allow customization of toolbars and menus, then there is no guarantee that item that you are trying to access through collection is actually there since end-user can move it to another bar.  DotNetBarManager.GetItems methods will get the item by name no matter where the item is actually located.

The major difference between DotNetBarManager.GetItem and DotNetBarManager.GetItems methods is in number of items that each returns. DotNetBarManager.GetItem will return first item that matches specified name. If you allow customization of menus and toolbars user can create new items and place them on menus and toolbars. If you are setting properties that are not Global then you need to change the properties on all items with specific name. In that case you should use DotNetBarManager.GetItems method which will return all items with specified name.

So, if you are certain that there could be only one single instance of an item (almost always the case with DockContainerItem for example) or you intend to change BaseItem object.

About BaseItem

BaseItem class is the base class for all items in DotNetBar. You can think of it like of System.Windows.Forms.Control class in .NET framework. All controls inherit from System.Windows.Forms.Control class to add specific functionality.

In DotNetBar all items inherit from BaseItem class so most of collections in DotNetBar will always return BaseItem. You need to cast the result to the type of your item be it ButtonItem, DockContainerItem or any other item.

C# Example:

BaseItem item = DotNetBarManager1.GetItem("myitem");
 
if (item != null)
{
    ButtonItem button = item as ButtonItem;  
 
    // Now you can change button properties 
 
    button.Checked = true;
}

VB Example:

Dim item as BaseItem = DotNetBarManager1.GetItem("myitem")
 
If Not item is Nothing then
    Dim button as ButtonItem = CType(item, ButtonItem)
 
    ' Now you can change button properties

    button.Checked = True
End If

Creating menus, toolbars and dockable windows

Creating any type of bar will involve following steps:

  • Creating a new Bar object
  • Adding that object to the DotNetBarManager.Bars collection
  • Setting the LayoutType property to reflect the type of the bar you want to create
  • Setting the MenuBar property to true if you are creating main menu bar. Note that only one Bar can have MenuBar property set to true.
  • Adding the new items to the Items collection, most likely ButtonItem objects for menus and toolbars or DockContainerItem for dockable windows.
  • Setting other properties of the Bar. See How to Create Toolbar, How to Create Menu and How to Create Dockable Windows help topics.
  • Deciding where to dock the Bar, read the section below About Docking below for important information regarding this
  • If you are creating the dockable windows then you will have to assign the DockContainerItem.Control property to the new instance of the user control you want hosted by that dockable window. Note that if you add more than one DockContainerItem to the Bar.Items collection you are creating the tabbed dockable window.

Note that if you are creating the DotNetBarManager from code you must create it in form constructor since DotNetBarManager expects to be created early. This does not applies to bars and items. You can create them at any time.

Hiding/Showing items on the Bar

If you are hiding or showing items on a Bar after you set the Visible property on all the items that you want to change call  Bar.RecalcLayout() method to re-layout the Bar. Otherwise DotNetBar will not change the layout until the next resize operation. Calling RecalcLayout method applies to almost all DotNetBar controls that host instances of BaseItem object.

About Dockable Windows

When creating dockable windows from code you have to assign the DockContainerItem.Control property to the Control you want hosted on dockable window. To save any user customized layout of dockable windows and toolbars use DotNetBarManager.SaveLayout and DotNetBarManager.LoadLayout methods.

Note that if you decide that save DotNetBar definition (which describes completely the menus, toolbars and dockable windows) to the file and load it at some later time, you will have to assign the DockContainerItem.Control property again since the control assignments are not serialized. You can handle the DotNetBarManager.DefinitionLoaded  event and set the DockContainerItem.Control property there. Note that if you are using DotNetBar designer to create dockable windows you should still use the DotNetBarManager.ContainerLoadControl  event. Please also note that if you load the definition file the member variables that are created on the form will not point to the newly loaded definition and will be out of date becouse definition re-creates all items and bars.

About Toolbar Docking

When making your bar dock the most important thing to remember is that you need to assign the Bar.DockSide property last. Assigning the DockSide property last forces the dock site layout manager to layout all bars contained and effectively applies the values you have assigned to the DockOffset and DockLine properties on your bar. Please also read the Docking Concepts topic that covers DotNetBar docking including dockable windows.

If you are creating multiple bars from code we recommend to use  DotNetBarManager.SuspendLayout property to suspend dock site layout while you are adding your bars. This property when set to true will make dock sites queue the layout operations and perform them after you set the property back to false.

About Dockable Windows Docking

Dockable windows are docked using the DocumentDockUIManager class. For example to dock a bar with LayoutType=DockContainer to the bottom dock site use following code:

C# Example:

dotNetBarManager1.BottomDockSite.GetDocumentUIManager().Dock(bar);

VB Example:

dotNetBarManager1.BottomDockSite.GetDocumentUIManager().Dock(bar)

Take a look at the DockingFromCode sample that illustrates how to completely create the dockable windows from code.

About Auto-hide Dockable Windows

To place the Bar object into the auto-hide mode set the Bar.AutoHide property to true. This will automatically place the Bar onto the auto-hide panel and hide it. In the event that you want to display the Bar when in auto-hide mode simply use Bar.AutoHideVisible property. Note that this property should be used only when Bar is in auto-hide mode to make it slide out. If you want to completely hide the Bar you should still use the Bar.Visible property.

Note that when Bar is in auto-hide state and you want to hide it completely before setting Bar.Visible property you must set the Bar.AutoHide property to false or bar cannot be hidden.

Floating Bar Positioning and Size

When Bar is floating the position of the Bar is controlled by Bar.Location property. Using this property you can get or set the location of Floating Bar. Note that you should always check whether Bar is floating by inspecting its DockSide property which will be equal to eDockSide.None.

Related posts:

  1. How to create Dockable Windows
  2. How to Create Toolbars Using Code
  3. How to tear-off DockContainerItem using code
  4. How to add any control to menu, toolbar and other DotNetBar controls
  5. DotNetBar 6.0 Upgrade Instructions