Introduction
Windows provides developers with many useful controls. Many of us just got into the habit to build GUI with those controls relying on that they are available on various versions of Windows and development environments.
But not all Windows common controls (or their wrappers) are shipped with .NET Framework. Once I needed header control for a Windows Forms application but just could not find it, so I had to implement a .NET wrapper myself and now can share it with you.
Unfortunately, I did not have enough time to provide support for all available features of standard header control, so I've implemented just common things used most often. Actually, I just did not implement owner draw and filters.
So, for those who need to use header control in .NET Windows Forms applications, here it is.
Overview
I've made the control's API similar to other .NET Framework controls, so if you have used them before, it would be easy to learn this one.
It has a collection of sections corresponding to WinAPI header control items and events being fired according to notifications. Styles of control window can be changed by corresponding properties.
Design-time support is also provided so you can install this control in your toolbox and use it in the form designer. To make it in VS.NET, click Tools->Customize Toolbox; or in VS 2003, from Toolbox context menu, select "Add/Remove items", in appeared dialog box, activate ".NET Framework components" tab, then click "Browse" button, and open SpHeader.dll file.
Also, I've made a simple application to demonstrate and test the control's features.
Control classes
Here is a short description of the main classes. I don't have to write a long manual because you can learn it from the source code faster.
HeaderSection class
Represents header section (or item). It holds text, image index, bitmap, and other attributes supported by Windows header control's item. The class is derived from Component that makes it possible to edit the object at design time, and it implements ICloneable interface allowing creation of shallow copies of self instance.
Properties
Header - Gets a reference to the header control the section is attached to.
Index - Gets the location with the header control's HeaderSectionCollection of this section.
Width - Gets or sets the width of the section in pixels.
Text - Gets or sets the text displayed on the section.
ImageIndex - Gets or sets the index to the image displayed on the section. If no image should be displayed, set this value to -1.
Bitmap - Gets or sets additional bitmap to be displayed on the section.
RightToLeft - Gets or sets a value indicating whether text of the section is displayed from right to left.
ContentAlign - Gets or sets the horizontal alignment of the text and images displayed on the section.
ImageAlign - Gets or sets the alignment of displayed images according to the text on the section.
SortMark - Gets or sets the sort-mark to be displayed instead of bitmap on the section. Sort-marks are shown only when control is used with Comctl32.dll of version 6.0 shipped with Microsoft Windows XP or later.
Constructors
public HeaderSection()
public HeaderSection(string text, int cxWidth)
public HeaderSection(string text, int cxWidth, int iImage)
public HeaderSection(string text, int cxWidth, object tag)
public HeaderSection(string text, int cxWidth, int iImage, object tag)
public HeaderSection(string text, int cxWidth, Bitmap bitmap)
public HeaderSection(string text, int cxWidth, int iImage, Bitmap bitmap)
public HeaderSection(string text, int cxWidth, int iImage, Bitmap bitmap, HorizontalAlignment enContentAlign)
public HeaderSection(string text, int cxWidth, int iImage, Bitmap bitmap, HorizontalAlignment enContentAlign, LeftRightAlignment enImageAlign)
public HeaderSection(string text, int cxWidth, int iImage, Bitmap bitmap, HorizontalAlignment enContentAlign, LeftRightAlignment enImageAlign, object tag)
public HeaderSection(string text, int cxWidth, int iImage, Bitmap bitmap, RightToLeft enRightToLeft, HorizontalAlignment enContentAlign, LeftRightAlignment enImageAlign, HeaderSectionSortMarks enSortMark, object tag)
Methods
HeaderSectionCollection class
Represents collection of the sections (or items) located in the header control. To add, delete and modify control's sections, use this collection.
In contrast to the logic of WinAPI header control, all sections in the collection are kept in the order they are displayed. You don't have to deal with indexes and orders like you do using WinAPI messages. It seems it's just made to provide backward compatibility*, and could bring unnecessary confusions and bugs for .NET developers. So, I've made it a little bit another way. Here, you deal with HeaderSection objects and their collection, the order of the section corresponds to its index in the collection so that WinAPI header item index is not needed at all.
* It would be better to use handles instead of indexes like it's done in ListView.
Properties
Header - Gets a reference to the header control that owns the collection.
Count - Gets the number of elements in the collection.
this[int index] - Gets or sets section in the collection. Section being set cannot be already attached to this or another header control.
Methods
public void Insert(int index, HeaderSection item)
Inserts new section to the collection at specified position. Section being inserted cannot be already attached to this or another header control.
public int Add(HeaderSection item)
Adds new section to the end of the collection. Section being added cannot be already attached to this or another header control.
public void RemoveAt(int index)
Removes section at specified position from the collection.
public virtual void Remove(HeaderSection item)
Removes given section from the collection.
public void Move(int iFrom, int iTo)
Moves section from one position to another.
public void Clear()
Removes all sections from the collection.
public int IndexOf(HeaderSection item)
Defines index of given section in the collection or returns null if section is not found. This index corresponds to the order of section it is displayed in the header control.
public bool Contains(HeaderSection item)
Defines if section is kept in the collection.
public void CopyTo(Array aDest, int index)
Copies all elements to the array.
Header class
Properties
Clickable - Gets or sets "Clickable" style. If set to true, section generates events when user clicks on.
HotTrack - Gets or sets "HotTrack" style. If set to true, section is highlighted when mouse pointer is located on it.
Flat - When set to true, causes the header control to be drawn flat when Microsoft Windows XP is running in Classic mode.
AllowDragSections - Determines if user will be able to drag header column on another position.
FullDragSections - When set to true, causes the header control to display column contents even while the user resizes a column.
Sections - Gets the collection of sections (or items). Use this collection to add, remove, and modify sections of the header control.
ImageList - Gets or sets an image list associated with header control. Images displayed on the sections are taken from this ImageList.
BitmapMargin - Width of the margin that surrounds a bitmap within an existing header control.
Events
SectionClick - Raised when user clicks on the section.
SectionDblClick - Raised when user performs double click on the section.
DividerDblClick - Raised when user performs double click on the divider of the section.
BeforeSectionTrack - Raised when user is about to start resizing of the section. The action can be canceled.
SectionTracking - Raised when user is resizing the section. The action can be canceled.
AfterSectionTrack - Raised when user has the section resized.
BeforeSectionDrag - Raised when user is about to start to drag the section on another position. The action can be canceled.
AfterSectionDrag - Raised when user is dragging the section on another position.
Methods
public void BeginUpdate()
Prevents the control from drawing until the EndUpdate method is called.
public void EndUpdate()
Resumes drawing of the control after drawing is suspended by the BeginUpdate method.
public Rectangle GetSectionRect(HeaderSection item)
Returns a rectangule of the section.
public void CalculateLayout(Rectangle rectArea, out Rectangle rectPosition)
Retrieves the correct size and position of a header control within the parent window.
public int SetHotDivider(int x, int y)
public int SetHotDivider(int iDevider)
Changes the color of a divider between header items to indicate the destination of an external drag-and-drop operation.
public HitTestInfo HitTest(int x, int y)
public HitTestInfo HitTest(Point point)
Tests a point to determine which header item, if any, is at the specified point.
Conclusion
Enjoy.
Known problems and bugs
- Using Visual Studio.NET, it is not possible to resize sections with mouse in design mode. However, it works fine in Visual Studio 2003.
History
- 06/17/2004 - Release of version 1.0.0.0.
- 06/24/2004 - Bugfix. Control was flickering when being resized in run-time mode.
