Windows provides developers with many useful controls. Many of us just got into the habit of building a GUI with those controls, relying that they are available on various versions of Windows and development environments.
But, not all Windows common controls (or their wrappers) are shipped with the .NET Framework. Once, I needed a header control for a Windows Forms application but just could not find it, so I had to implement a .NET wrapper myself. Now I can share it with you.
Unfortunately, I did not have enough time to provide support for all available features of a standard header control, so I've implemented just the common things used most often. Actually, I just did not implement owner draw and filters.
So, for those who need to use a header control in a .NET Windows Forms applications, here it is.
I've made the control's API similar to other .NET Framework controls; if you have used them before, it will 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 a 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 the Toolbox context menu, select "Add/Remove items;" in the dialog box that appears, activate the ".NET Framework components" tab, and then click the "Browse" button and open the SpHeader.dll file.
Also, I've made a simple application to demonstrate and test the control's features.
Here is short description of the main classes. I don't have to write a long manual because you can learn it faster from the source code.
This represents the header section (or item). It holds text, image index, bitmap, and other attributes supported by the Windows header control's item. The class is derived from Component; that makes it possible for you to edit the object at design time and it implements the ICloneable interface, allowing the creation of shallow copies of self instance.
- 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 the 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 a bitmap on the section. Sort-marks are shown only when the control is used with Comctl32.dll of version 6.0 shipped with Microsoft Windows XP or later.
- 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)
- public virtual object Clone()—Creates a shallow copy of the section.
This represents a collection of the sections (or items) located in the header control. To add, delete, and modify the control's sections, use this collection.
In contrast to the logic of the 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 confusion 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 the WinAPI header item index is not needed at all.
* It would be better to use handles instead of indexes, as it's done in ListView.
- 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 a section in the collection. The section being set cannot be already attached to this or another header control.
- public void Insert(int index, HeaderSection item)—Inserts a new section to the collection at the specified position. The section being inserted cannot be already attached to this or another header control.
- public int Add(HeaderSection item)—Adds a new section to the end of the collection. The section being added cannot be already attached to this or another header control.
- public void RemoveAt(int index)—Removes a section at the specified position from the collection.
- public virtual void Remove(HeaderSection item)—Removes a given section from the collection.
- public void Move(int iFrom, int iTo)—Moves a section from one position to another.
- public void Clear()—Removes all sections from the collection.
- public int IndexOf(HeaderSection item)—Defines the index of given section in the collection or returns -1 if section is not found. This index corresponds to the order of the section in which it is displayed in the header control.
- public bool Contains(HeaderSection item)—Defines whether the section is kept in the collection.
- public void CopyTo(Array aDest, int index)—Copies all elements to the array.
- Clickable—Gets or sets "Clickable" style. If set to true, the section generates events when the user clicks on it.
- HotTrack—Gets or sets "HotTrack" style. If set to true, the section is highlighted when the 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 whether the user will be able to drag the header column to another position.
- FullDragSections—When set to true, causes the header control to display column contents even while the user resizes a column.
- Sections—Gets a collection 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.
- SectionClick—Raised when the user clicks on the section.
- SectionDblClick—Raised when the user performs a double-click on the section.
- DividerDblClick—Raised when the user performs a double-click on the divider of the section.
- BeforeSectionTrack—Raised when the user is about to start resizing the section. The action can be canceled.
- SectionTracking—Raised when the user is resizing the section. The action can be canceled.
- AfterSectionTrack—Raised when the user has the section resized.
- BeforeSectionDrag—Raised when the user is about to start dragging the section to another position. The action can be canceled.
- AfterSectionDrag—Raised when the user is dragging the section to another position.
- 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 rectange 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.
Known Problems and Bugs
- When using Visual Studio.NET, it is not possible to resize sections with the mouse in design mode; however, it works fine in Visual Studio 2003.
- 06/17/2004—Release of version 220.127.116.11