A Tool is an item that appear on menus and toolbars. Tools are rendered differently depending on whether they appear on a menu or toolbar. When tools appear on a toolbar they are rendered as buttons that display an image and/or text. When a tool appears on a menu it is rendered as a list entry with text and/or an image.
WinToolbarsManager™ supports twelve native tool types. Internally in UltraToolbarsManager, each tool type is represented by a class that is derived from the ToolBase class. For more information, see Working with Tool Types.
Toolbars are 'tool containers' that can contain zero or more tools. The tools are rendered as buttons and arranged horizontally or vertically depending on the orientation of the toolbar. Toolbars can be docked in one of 4 dock areas on a form or floated in their own window.
Internally in UltraToolbarsManager, toolbars are represented by the UltraToolbar class.
UltraToolbar objects have a Tools property which is a collection of ToolBase derived objects (i.e., Tools). The tools that reside in this collection are Instance Tools ( see below )
A menu is a special type of tool (called a PopupMenuTool ) that can contain other tools, and as such is a 'tool container' just like toolbars. Tools contained in a menu are rendered in typical menu fashion - as a vertical series of entries containing text and optionally an image. Tools on an UltraToolbarsManager Menu are analogous to MenuItems on a standard .NET menu. Within this documentation, the terms Menu and PopupMenu are used interchangeably.
PopupMenu Tools can be placed on Toolbars, or 'popped-up' as context menus anywhere on the desktop. When used in this fashion the menus are referred to as top-level menus. If a PopupMenuTool is added to another PopupMenuTool, it is referred to as a submenu
Internally in UltraToolbarsManager, menus are represented by the PopupMenuTool class. The PopupMenuTool class, like all tool classes, is ultimately derived from the ToolBase class.
PopupMenuTool objects have a Tools property which is a collection of ToolBase derived objects (i.e., Tools). The tools that reside in this collection are Instance Tools ( see below )
A submenu is the term for a menu that is embedded inside another menu. It is represented by the same PopupMenuTool class as a 'top-level' menu and the only difference between it and a top-level menu is its location.
The term container is used to refer to the object within which the UltraToolbarsManager displays and docks its toolbars. The container can be a form or a container control on a form. Since the UltraToolbarsManager is a Windows.Forms.Component which sits in the component tray beneath the forms designer in Visual Studio .NET IDE, it cannot be 'drawn' inside a container the way you would a control like a checkbox or button. Instead, UltraToolbarsManager has a property called DockWithinContainer that lets you specify the form or container control that the UltraToolbarsManager should target.
A dock area is a visual area of the container that is used to hold toolbars that have been docked. When an UltraToolbarsManager element is assigned to a container, it automatically creates four dock areas - one each at the top, bottom, left and right edges of the container. If no toolbars are docked in a particular dock area, the dock area does not use any space in the container and is, in effect, invisible. If 1 or more toolbars are docked in a particular dock area, the dock area automatically expands in size to accommodate the toolbars, encroaching on the container’s space as needed.
The DockAreas are actually UltraToolbarsDockArea elements. These are special elements created automatically by the UltraToolbarsManager to serve as docking targets for toolbars. There are no properties, events or methods on the UltraToolbarsDockArea element that are of interest to the developer, and generally you should never have to interact with them.
Understanding the simple but powerful concept of root tools vs. instance tools is central to using UltraToolbarsManager.
A Root Tool is a tool that resides in the Tools collection directly off the UltraToolbarsManager. You will typically define 1 Root Tool for each unique tool that you require in your application.
For example, if your application requires a 'File Save' tool that appears in multiple places (e.g., on a 'File' menu and on a toolbar) you would create 1 Root Tool that defines the basic attributes you want the 'File Save' tool to have. When you then place 1 occurrence of the tool on the 'File' menu and another occurrence of the tool on a toolbar, UltraToolbarsManager will use the 'File Save' Root Tool as a template or 'cookie cutter' to create the 2 tools. The 2 tools that are created are referred to as Instance Tools.
Root Tools are used as the blueprint to create 1 or more Instance Tools of the same type (i.e., Button Tool, ComboBox Tool, ColorPicker Tool etc.). Root Tools keep track of all Instance Tools created from them, and Instance Tools always know the Root Tool they were created from.
By dividing the universe of tools into Root Tools and Instance Tools, UltraToolbarsManager gives you great flexibility in manipulating tools. For example, to change the text that is displayed for all occurrences of the 'File Save' tool mentioned above, simply set the Caption property of the Root Tool. When you do so, all Instance Tools created from that Root Tool that have not had their Caption explicitly set will inherit the Caption change on the Root Tool. In addition, any new Instance Tools you create from the 'File Save' Root Tool will also inherit the Caption Change
Similarly, if you wanted to change the Caption property on the 'File Save' tool residing on the toolbar and not the one residing on the menu, simply change the Caption property on the Instance Tool that resides on the toolbar.
Root Tools can only be created by the developer, and not by the end-user. As a developer, you can create Root Tools by:
Clicking the 'New' button on the design-time customizer dialog’s Tools tab
Programmatically creating a tool and adding it to the Tools collection of the UltraToolbarsManager.
Instance Tools can be created by the developer or the end user. As a developer, you can create Instance Tools by:
Dragging a tool from the Tools list on the Tools tab of the design time customizer dialog to a toolbar or menu on the UltraToolbarManager’s container
Programmatically creating a tool and adding it to the Tools collection of a Toolbar or a PopupMenu Tool.
An end-user can create Instance Tools by:
Dragging a tool from the Commands list on the Tools tab of the run-time customizer dialog to a toolbar or menu on the UltraToolbarManager’s container
When you create Root Tools you are defining the set of tools that can be used in the UltraToolbarsManager by the developer and the end-user.
To summarize, root tools do not appear on toolbars or menus, rather they serve as 'templates' for creating 1 or more instances of the root tools on toolbars and menus.
Every tool has two important properties that relate to their status as either Root Tools or Instance Tools. They are called SharedProps and InstanceProps .
The SharedProps property on each tool returns the SharedProps object which contains properties that are shared across all instances of the tool. As a result, the SharedProps property of a Root Tool and the SharedProps property of all its related Instance Tools returns the same SharedProps object. The SharedProps object contains properties such as Appearance, Caption and Category.
The InstanceProps property on each tool returns the InstanceProps object which contains properties that only affect the instance of the tool to which they are attached.
The InstanceProps object contains properties such as Appearance, Caption and Visible.
Some properties, such as Appearance and Caption, are duplicated on both the SharedProps and InstanceProps objects. For properties that appear on both SharedProps and InstanceProps, the SharedProps version serves as a 'global' setting for the property, affecting all related tool instances, whereas the InstanceProps version affects just the instance to which it is attached. This gives the developer great flexibility in setting these kind of tool properties. For example, a tool’s Appearance can be set using its SharedProps.Appearance property, and doing so would affect all instances of the tool. If you then wanted a particular instance of the tool to appear differently, you would change that tool instance’s InstanceProps.Appearance property.
The SharedProps and InstanceProps objects give you the power to apply settings globally across all instances of a tool and the flexibility to override selected settings for specific tool instances.