Infragistics UltraWinToolbars Readme

UltraWinToolbars(TM)

.NET Windows Forms Control

v3.00.20033.16.00 - October, 2003

Infragistics, Inc., Windsor Corporate Park, 50 Millstone Road, Building 200 - Suite 150, East Windsor, NJ 08520

Voice (609) 448-2000, Fax (609) 448-2017, http://www.infragistics.com

.NET Framework Compatibility:
All included assemblies have been built against the Microsoft .NET framework 1.0 RTM build. You must have either the 1.0 or 1.1 RTM build of the framework installed for the product to work.

New Features in v3.00.20033:
-Handedness support menus

New Features in v2.00.5001:
UltraWinTabbedMdi:
The UltraTabbedMdi component provides a Visual Studio .Net style tabbed interface for managing mdi child forms. The component will be responsible for the arrangement and organization of the mdi child forms. Each child form will be represented by an MdiTab object which exposes properties for the appearance of the associated tab.

The component will expose the same functionality as that of Visual Studio. For example, tabs may be repositioned within the collection of tabs by depressing the left mouse button on a tab and dragging over other tabs. Also, tabs may be dragged to the edges of a tab group to create a new “tab group”.

We will maintain the same restriction that Visual Studio does – all tab groups must be in the same orientation. The control exposes a single Orientation property. This property may be changed to switch the orientation of the current tab groups. MdiTabs are organized within a TabGroup object. Each tab group is a separate group of MdiTab instances and has its own SelectedTab. There is an ActiveTab property on the component which returns the MdiTab for the currently active mdi child form.

When a tab is dragged and released within the bounds of a tab group, the context menu displayed above is presented to determine where the tab is repositioned.

Right clicking on a tab will cause the context menu for the tab to be displayed. The default menu items allow the end user to close the tab or move it to another TabGroup.

UltraWinTabControl & UltraWinTabStripControl:
The 2 new controls, UltraTabControl and UltraTabStripControl, are very similar and expose almost identical object models. The following highlights the main differences:

UltraTabControl is designed as a replacement for the Microsoft supplied tab control. As such it automatically creates a tab page child control (UltraTabPageControl) for each tab. The tab page is used to contain controls that are unique to each tab. UltraTabControl exposes all the functionality of the inbox Tab control plus many new features including support for mnemonics, hiding and disabling tabs, shared controls, multiple tabs styles and orientations (including wizard and note page styles). UltraTabControl offers all of the functionality of ActiveTabs as well.

UltraTabStripControl exposes all of the features of the UltraTabControl except that it doesn’t create an UltraTabPageControl for each tab. Therefore the only thing that changes visually when a new tab is selected is the tab header area. Events are raised for both controls that give the developer the opportunity to initialize the tab area. Since the UltraTabStripControl doesn’t do any per-tab child control manipulation it can be data bound. It exposes DataSource, DataMember, TabKeyMember, TabTextMember and ToolTipTextMember properties. When bound, it automatically generates a tab for each row in the data source. It also fires a TabInitialized event for each tab that is loaded from the data source.

Both UltraTabControl and UltraTabStripControl derive from a common base class, UltraTabControlBase, which derives from UltraControlBase.

Key features of the controls include:

The overall architecture of the UltraTabControl will be the similar to the inbox tab control. At design time, tabs will be added or removed via context menu verbs. When a tab is added an UltraTab object is created along with a corresponding UltraTabPageControl control that will be made a child control of the UltraTabControl. The UltraTabPageControl is a container control that is derived from System.Windows.Forms.Panel so that other controls can be positioned on it. Tab visibility will be controlled internally by moving non-selected pages to non-visible locations. At runtime, the Visible property of the tab page controls for non-selected tabs will be set to false to prevent their controls from participating in tab order navigation.

Instead of the inbox tab control’s TabPages collection, UltraTabControl exposes a Tabs property which is a collection of UltraTab objects. The UltraTab exposes a TabPage property that returns its corresponding UltraTabPageControl. Note that the UltraTabStripControl also exposes the same collection of UltraTab objects. However, those objects return the SharedControlsPage (see below) for the TabPage property since individual tab page controls are not created for each tab in the UltraTabStripControl.

As in ActiveTabs, there will be a shared control area. Any controls placed in this area at design time will appear on every tab. When the UltraTabControl is first created a special UltraTabPageControl will be created internally as a child control to act as a container for the controls to be shared. The UltraTabControl will expose a SharedControlsPage property which will return this control. There will be a context menu verb available at design time to display the shared controls area. The SharedControlsPage control will display a set of instructions at design time to let the developer know how to add/remove tabs and how to use this feature. Shared controls will be made visible on the selected tab by re-parenting them to the selected tab’s UltraTabPageControl. The UltraTabStripControl will use this SharedControlsPage as its permanent child control area. Both controls will expose a collection of the shared controls through the SharedControls property.

A new feature of UltraTabControl that wasn’t available in ActiveTabs will be the ability to exclude shared controls for specific tabs. Shared controls can be excluded from one or more tabs at design time by clicking the ‘Exclude shared controls’ context menu verb which will bring up a dialog which lists the shared controls on one side and the tabs on the other. Selecting a shared control in the list will allow the developer to exclude that control from one or more tabs via a checked listbox of tabs. The UltraTab object will expose an ExcludedSharedControls collection so that this functionality can be exposed at runtime through code. This feature will not be supported for the UltraTabStripControl.

Multiple tab styles will be supported throughout the control’s Style property:

UltraTabControlStyle
PropertyPage	1	Raised borders (property page).
PropertyPageSelected	2	Property Page style tab for the selected tab and hot tracked tab when hot tracking is enabled. All other tabs display no borders.
PropertyPageFlat	3	Single pixel rounded borders.
PropertyPage2003	4	Leading edge slopes to the top of the tab and the trailing edge has a rounded corner.
StateButtons	5	State button style tabs. The button style is determined by the TabButtonStyle property setting.
VisualStudio	6	Only the selected tab appears raised. The others look flat with a vertical line separating 2 adjacent non-selected tabs. Also their captions appear grayed out
Flat	7	All tabs appear flat. The selected tab is highlighted via the caption color with the other tab captions appearing grayed out.
Wizard	8	No UI is provided at runtime to navigate between tabs and there are no borders around the control.
Excel	9	The tabs have straight inwardly sloping sides (in the shape of a rhombus). The right side of each tab overlaps its neighboring tab half way up except for the selected tab which overlaps its neighboring tabs on both sides.
NotePage	10	Page curl images appear in the upper right and left hand corners to turn the pages. A raised border is drawn around the tab.
NotePageFlat	11	Page curl images appear in the upper right and left hand corners to turn the pages. No border is drawn around the tab.

The MultiRowSelectionStyle property allows the developer to control whether the selected tab’s row is swapped with the row next to the tab page area or not. If swapping is not chosen the selected tab will be highlighted by alpha-blending the other tabs out so they appear dim.

The TabLayoutStyle property offers support for new multi-row metaphors for handling large numbers of tabs while conserving screen real estate. For example, scrolling tab rows or popping up multi-row selection windows.

Visible and Enabled properties on the UltraTab object.

Index and Key properties on the UltraTab object. The Index property determines the order of the tab in the collection as well as its initial visible position. The Key property is used as an additional indexer into the Tabs collection. Both of these properties are read/write.

The control can take focus and as a result provides full support for keyboard navigation and mnemonics. It exposes the standard TabStop and TabIndex properties. Setting TabStop to false prevents the tab control from taking focus.

Drag and drop support for moving tabs at design time. The UltraTabControl’s boolean AllowTabMoving property determines if this support is available at runtime.

The TabPageMargins property on UltraTabControlBase manages the spacing around the UltraTabPageControls.

Tooltips can be displayed for tabs. The UltraTab object exposes a ToolTipText property and the UltraTabStripControl exposes a ToolTipTextMember property so that when bound the ToolTipText property can be automatically initialized from the data source.

The ImageSize property on the control determines the space allocated for images.

Note: The inbox tab control raises a DrawItem event to support owner-drawing of the tabs. We will not duplicate this event since the DrawFilter interface provides much better capabilities.

UltraToolbarsManager:
Office2003 style for UltraToolbarsManager
Tool events for UltraToolbars Manager
DesignTime Support For Adding Custom Tools

UltraDockManager:
Ability to fill window with panes
Ability to undock panes to mdi child forms

Suggestions Implemented:
WTB901 - Add a way to use a WinToolbars Context Menu with the NotifyIcon Component. ContextMenuUltra extender property works for NotifyIcon components
WTB896 - Add methods to allow merging without MDI Forms. ActiveMdiChildManager and MdiParentManager properties are now settable if both the parent and child manager's MdiMergeable properties are set to false
WTB886 - ShowPopup should have an overload which does not take a point
WTB885 - Add a way to color the client area/tab area separately.Added ClientAreaAppearance properties to UltraTabControlBase and UltraTab and added ResolveClientAreaAppearance method to UltraTabControlBase”
WTB880 - Add a way to have a single (non-sunken) border around the TabGroups. We now render the border and have a BorderColor property as well.
WTB821 - Request for an Office 2003 style
WTB800 - Add an event that fires for each tab before the tab is saved so you can set the PersistedInfo
WTB530 - Request for a property to stop flyouts when hovering over a tab. I added an UnpinnedTabHoverAction, it can be set to Flyout (default), ToolTip, or None.
WTB525 - Need a method to dock a control at run-time, just like the verb at design-time. I added a CreateDockArea method that takes an array of controls, a DockedLocation and a ChildPaneStyle.
WTB473 - Ability to fill an entire area using a dockable control. There is now a LayoutStyle property on the UltraDockManager. The default is "Standard" which just does what it does now - the controls are allow docked along the edges of the container. When set to FillContainer, the inner most is treated as a Fill control and fills the remaining area.
WTB433 - Add a property to make unpinned tabs not flyout but show tooltips instead, when the mouse moves over the tab. I added an UnpinnedTabHoverAction, it can be set to Flyout (default), ToolTip, or None.
WTB429 - Add a way to have unpinned TabGroups always display the full text. I added a CompressUnpinnedTabs property, which defaults to true. I also added an UnpinnedTabStyle property to control the style of the unpinned tabs
WTB293 - Tabbed MDI manager. There's now an UltraTabbedMdiManager component
WTB262 - Customer wants floating windows to be MDI Children. There is now an IsMdiChild property on the DockableControlPane so that a pane can be hosted in an mdi child window. There is also an MdiChildIcon property to allow the icon for the form to be controlled

Updating Projects to Work with Version 3 Controls:
This topic provides important information about updating existing projects to work with the Version 3 Infragistics controls. Version 3 controls are the .NET DLL files for Infragistics products that have been updated to reference the Version 3 Shared and Win common assemblies.

Version 3 Update Overview:
The names of the assembly files for the Version 3 controls have been changed. They now have ".v3" appended to their names. So for example, the version 2 UltraWinGrid control assembly was distributed in a file called Infragistics.Win.UltraWinGrid.v2.dll. The Version 3 UltraWinGrid assembly is named Infragistics.Win.UltraWinGrid.v3.dll.

This naming convention allows both version 2 and version 3 controls to coexist in the Visual Studio toolbox. The version 3 controls will display a blue triangle in the upper left corner of their toolbox icons to distinguish them from the Version 2 versions. In order to make version upgrading as painless as possible the internal namespaces have not been changed. This means that you do not have to change any of your code when updating projects from Version 2 to Version 3.

However, since all the controls share the common framework assemblies, this also means that none of the Version 2 controls can coexist with Version 3 controls in the same project. For example, you cannot have a Version 3 UltraWinGrid control in the same project as a Version 2 UltraWinListbar control.

Procedure for Updating Projects:
To convert an existing project to use version 3 of the controls, perform the following steps:

1. Make a backup copy of the project first.

2. Open the project and in the solution explorer expand the 'References' item. Take note of all the 'Infragistics...' references present. This will include at least the Win and Shared assemblies, and possibly other assemblies as well depending on the product.

3. Remove all the old 'Infragistics...' references. Then add the references back in again, using the corresponding '.v3' assemblies. If the V3 versions do not appear in the list (as indicated by the '.v3' names) then installation of your Version 3 assembly was not completed properly. You should re-run the setup program to correct this problem.

4. Rebuild the project. If you get a 'Could not transform licenses file...' error, double-click on it and modify the assembly names by appending '.v3' as in the example below:
Infragistics.Win.UltraWinGrid.UltraGrid, Infragistics.Win.UltraWinGrid.v3, Version=3.0.5000.15, Culture=neutral, PublicKeyToken=7dd5c3163f2cd0cb

5. If you get 'Resource transformation ...' errors, click on the "Show All Files" button at the top of solution explorer. This should add expansion indicators next to the form files. Expand the offending form(s) and open the associated .resx files.

You will need to delete the offending entries. Unfortunately, the error messages don't indicate which entries are bad. However, for beta 1 toolbars projects we know that entries named 'resource.Settings', 'resource.Settings1' etc. need to be deleted. Also old grid projects may have entries with 'DisplayLayout' in the name. These should be deleted. We have also found some Appearances persisted into old project .resx files; these should be deleted also. However, entries with names like 'Appearancex.Image' are valid and should not be deleted.

6. Rebuild the project to incorporate any changes you have made.

Version Numbers:
After careful input from our development team and Enterprise customers we have modified our version number system for the Vol. 3 release.

Because of issues with version in .NET the system uses a couple of parts. To avoid issues with side-by-side versioning the GAC file names contain the major version as part of the file name.

Examples

Infragistics.Win.UltraWinGrid.v3.dll
Infragistics.WebUI.UltraWebNavigator.v3.dll

The .v# in the file name is used to indicate a major new version.

The current system of version number will be changed to allow customers to easily tell a large volume of information from the version number. The first digit will contain the major version number of the control. This is different from the volume number of the entire toolset because not every control is modified in every release.

The second digits are for minor revisions to the control and will be used to denote minor modification to a control that does not reach the level of a major release but are greater than a hotfix, such as an addition of a handful of properties, methods, or events.

The third set of digits is for the year and volume number that control was last released in.

The final set of digits is the build number. This is increased each time a build is dropped to our internal QA area. All of these builds are not sent out to customers.

The final set of digits also easily notifies you that this is a full regression tested build or a hotfix. If the build number starts with 100X it is not regression tested and is a hotfix build. If the build does not start with 100X it is a fully tested release.

Examples

3.00.20033.5 = Beta 1
3.00.20033.10 = 5 drops later Beta 2
3.00.20033.11 = 1 drop later Gold 2003 Volume 3 release
3.00.20033.1012 = 1 drop later First hot fix
3.00.20033.1017 = 5 drops later hot fix
3.00.20041.18 = 1 drop later Gold 2004 Volume 1 release
3.00.20041.1019 = 1 drop later First hot fix
3.00.20041.1024 = 5 drops later hot fix
4.00.20042.1 = Beta 1 with major new features

Issues Addressed:

Use the knowledge base in the Infragistics Support Center
http://www.infragistics.com/support/supportcenter.asp
to review the history of addressed issues.
http://www.infragistics.com/process/p_knowledge.asp?product=84&articlestypebugfix=on

UltraWinToolbars 3.00.20033.16.01 – October, 2003
-------------------------------------------------------------------------------------------------------------------------------------------------------------
- Initial Release

UltraWinToolbars 2.00.5001.19.01 – June, 2003
-------------------------------------------------------------------------------------------------------------------------------------------------------------
Compiled against Infragistics.Shared.v2 and Infragisitics.Win.v2 2.00.5001.19
- Initial Release

UltraWinToolbars 2.00.5000.32.01 – January, 2003
-------------------------------------------------------------------------------------------------------------------------------------------------------------
Compiled against Infragistics.Shared.v2 and Infragisitics.Win.v2 2.00.5000.32
- Full Release containing all previous Hot Fixes

UltraWinToolbars 2.00.5000.22.01 – December, 2002
-------------------------------------------------------------------------------------------------------------------------------------------------------------
Compiled against Infragistics.Shared.v2 and Infragisitics.Win.v2 2.00.5000.22
- Full Release

UltraWinToolbars 2.00.5000.16.00 – October, 2002
-------------------------------------------------------------------------------------------------------------------------------------------------------------
Compiled against Infragistics.Shared.v2 and Infragisitics.Win.v2 2.00.5000.16
- Initial Release