Implementation
| Implementation of the ImageListView control requires constructing the following components:
Of these four components, only three are tightly coupled: ImageListViewItem, ImageListView, and ImageListViewDesigner. The ScrollButton class is designed to be independent so that it can be reused in other projects. This of course raises another key design ideal: reusable components. During the course of developing controls, or any software, there exists a set of shared/common functionality that can be reused. All endeavors in development should look for such reusable components. Each of the following sections describes the design and implementation of the components required to build the ImageListView control. ScrollButtonLike other soft-controls developed thus far, the ScrollButton has two jobs: painting and hit-testing. The first job, painting, involves determining the orientation of the button. The ScrollButton can be used to represent either an Up or a Down orientation. The orientation of the button is used to determine the style of arrow to render on the button. Rather than using two bitmaps, or using one bitmap and rotating it, to represent the arrow, the ScrollButton uses a GraphicsPath primitive to create the polygon for the arrow. Note The GraphicsPath object allows for a polygon, or path, to be constructed from a set of points or lines. This path can then be filled in the same manner as a rectangle or an arc using standard graphics calls. Developers of custom controls would do well to learn the ins and outs of GDI+. The decision to create a soft-control rather than a full-blown Control-derived component is based on one simple fact: a full control is not needed. For the ScrollButton to serve its intended purpose, it does not need any of the services or implementation afforded by the Control base class. Sometimes figuring out what's not needed can help to determine the proper starting point for a new component or control. Note, however, that the ScrollButton could just as easily be developed as a Control-derived or event Button-derived control. The only drawback to this approach is the extra resources consumed by creating an additional window handle and any unseen overhead within the base class implementations. For die-hard ATL/C++ developers, the idea of "don't pay for what you don't use" carries over into C# and .NET. Because the ScrollButton does not use or need any features from the Control base class, why pay the price of using it? Implementation inheritance is like consuming alcoholic beverages. Do it responsibly. Because the ScrollButton class represents the smallest component, its implementation is shown here first. Listing 9.1 contains the implementation for ScrollButton. Listing 9.1 ScrollButton Implementation 1: using System; 2: using System.Drawing; 3: using System.Windows.Forms; 4: 5: namespace SAMS.ToolKit.Controls 6: { 7: public enum ScrollButtonOrientation { 8: Up, 9: Down 10: } 11: 12: public class ScrollButton { 13: 14: private static int SIZE = 16; 15: private static int PADDING = 5; 16: private Rectangle btnRect; 17: private ScrollButtonOrientation orientation; 18: 19: public Point Location { 20: get { return new Point( btnRect.X, btnRect.Y ); } 21: set { 22: btnRect = new Rectangle( ((Point)value).X, ((Point)value).Y, SIZE, By now the basic structure of soft-controls should be ingrained in your mind. The ScrollButton introduces a new Graphics primitive: the GraphicsPath. To draw the arrow or triangle that represents the arrow, a GraphicsPath object is constructed based on three points. These three points represent the path of the polygon to be later filled. The orientation of the arrow is determined by the enum ScrollButtonOrientation specified during the construction of the ScrollButton. The methods DrawUpArrow and DrawDownArrow, found in Listing 9.1 on lines 53 and 66, respectively, handle the process of creating the points used to represent the arrow to be drawn. In addition, the arrow is offset when the ScrollButton is in a pushed state. This offsetting gives the appearance of the button control being pushed into the screen. After the points for the arrow have been calculated, the RenderArrow method uses these points to construct the GraphicsPath object. Notice on line 83 the path.CloseFigure method invocation. The CloseFigure method call completes the polygon so that when the GraphicsPath is filled, a solid triangle will be the output. Now that the ScrollButton is in place, the next step in building the ImageListView control is the construction of the ImageListViewItem component. The ImageListViewItem component is used to manage information reguarding an item within the ImageListView control. ImageListViewItemSimilar to the OutlookBarTab component, an ImageListViewItem is a component that tracks various information about the item it represents within the ImageListView control. This approach is a common theme when building composite controls that contain items such as the Tab control, Menu control, or ToolBar control. Each ImageListViewItem is capable of rendering itself in either large or small image mode and provides hit testing and hover state feedback. When the mouse pointer is held over an image, the image is drawn in a popped-up style state to indicate the hover state mode, as shown in Figure 9.2. Figure 9.2. Hover state feedback.
As with other controls and components developed so far, a determination of the base class from which to begin needs to be addressed. First, the ImageListViewItem needs to be defined. Is it a control? No. What is the ImageListViewItem? An ImageListViewItem is an object that is to be used to manage the display of text and an associated icon or image. The ImageListViewItem depends on its parent, the ImageListView control, for location and mouse event processing. In addition, the ImageListViewItem needs its parent in order to access the proper ImageList, large or small, to obtain the associated image to draw. The ImageListViewItem represents a subcomponent of the ImageListView control. This basic definition and the requirements of the ImageListViewItem help to establish the base class for it. Listing 9.2 contains the implementation of the ImageListViewItem component. A vast majority of the code deals with drawing both the text and the associated image. Listing 9.2 ImageListViewItem Component 1: using System; 2: using System.ComponentModel; 3: using System.Drawing; 4: using System.Windows.Forms; 5: 6: namespace SAMS.ToolKit.Controls 7: { 8: 9: 10: public enum ListViewItemState { 11: Normal, 12: Hover, 13: Pushed 14: } 15: 16: 17: 18: 19: [ToolboxItem( false )] 20: public class ImageListViewItem : System.ComponentModel.Component { 21: 22: private static int EDGE_PADDING = 4; 23: private static int TEXT_PADDING = 12; 24: private static int LARGE = 32; 25: private static int SMALL = 16; 26: 27: private string text; 28: private int imageIndex; 29: private Rectangle imageRect; 30: private Rectangle textRect; 31: private bool drawLarge; 32: private float fontHeight; 33: private Image image; 34: private int fontLines; 35: private int height; 36: private Point location; 37: 38: internal ImageListView parent; 39: 40: [ 41: Description( "Text displayed for the current item" ), 42: Category( "Appearance" ) 43: ] 44: public string Text { 45: get { return text; } 46: set { 47: text = value; 48: } 49: } 50: 51: [ 52: Description( "Image Index used to display associated image" ), 53: Category( "Appearance" ) 54: ] 55: public int ImageIndex { 56: get { return imageIndex; } 57: set { 58: imageIndex = value; 59: } 60: } 61: 62: [ Browsable( false )] 63: public ImageListView Parent { 64: get { return parent; } 65: } 66: 67: [Browsable( false )] 68: public int Height { 69: get { return height; } 70: } 71: 72: [Browsable( false )] 73: public Point Location { 74: get { return location; } 75: } 76: 77: public ImageListViewItem( ) { 78: parent = null; 79: drawLarge = true; 80: imageIndex = -1; 81: imageRect = new Rectangle(0,0,0,0); 82: textRect = new Rectangle(0,0,0,0); 83: image = null; 84: height = 0; 85: } 86: 87: public bool HitTest( Point pt ) { 88: return (imageRect.Contains( pt ) || textRect.Contains( pt )); 89: } 90: 91: 92: public int CalcHeight( Graphics g, Font font, int width, bool LargeImage ) { 93: 94: drawLarge = LargeImage; 95: 96: height = ( LargeImage ? LARGE : SMALL ); 97: 98: //calc the height of the Text 99: SizeF fontSize = g.MeasureString( text, font ); 100: fontHeight = fontSize.Height; 101: fontLines = 1; 102: if( LargeImage ) { 103: height += TEXT_PADDING; 104: if( fontSize.Width > width ) { 105: //Need to wrap the text 106: height += (int)((float)2*fontSize.Height); 107: fontLines = 2; 108: } else 109: height += (int)fontSize.Height; 110: } 111: return height; 112: } 113: 114: 115: public void Draw( Graphics g, Font font, Brush foreBrush, Point location, As noted previously, most of the code from Listing 9.2 deals with drawing both the text and the image for the item. All drawing boils down to determining the size, position, and color of what is going to be drawn. Determining the size of the image, whether large or small, and the size of the text serve to then derive the calculations for size and placement of the text and image. Implementing various effects, such as a hovering effect when the mouse is over an item or a pushed effect when a mouse click occurs, requires subtle drawing hints. In the case of hovering, a border is added to the image, and the image itself is offset to give the appearance of movement. Stepping through the drawing code, beginning on line 115 of Listing 9.2, the basic logic is as follows:
These six steps outline the drawing logic for the ImageListViewItem component. There is no hard-and-fast rule for drawing other than that it should "look right." Defining that look, of course, is left to the developer of the control. With the ImageListViewItem component complete, the next step is to create the ImageListView control itself. ImageListView ControlThe next piece of the puzzle for the ImageListView control is implementing the container for all the components listed so far. As with the OutlookBar control, the ImageListView has one primary function: managing the subcomponents it contains. And also like the OutlookBar control, the ImageListView control contains a custom collection in order to maintain and manage the set of ImageListViewItems associated with the control. The ImageListView control manages one or more ImageListViewItems. Although the ImageListViewItems are capable of drawing themselves, the ImageListView control is responsible for managing their position, scrolling, and handling events such as mouse events. A custom event is provided to notify any observers, such as the parent form, when a particular ImageListViewItem has been clicked. This custom event provides the index for the item that has been clicked on. Again, rather than providing extraneous features, the ImageListView control features are kept to a minimum to demonstrate the processing of building a custom control. Table 9.1 lists the properties exposed by the ImageListView control.
Before the source listing for the ImageListView control is shown, it should be noted that the listing contains the code for a custom collection. Providing custom collections is a common theme and a task you should become comfortable with. The relevant sections of the custom collection will be discussed following the source listing. Without further ado, Listing 9.3 contains the source code for the ImageListView control. Following the listing is a discussion of its implementation. Listing 9.3 ImageListView Control 1: using System; 2: using System.ComponentModel; 3: using System.Collections; 4: using System.Drawing; 5: using System.Windows.Forms; 6: 7: 8: namespace SAMS.ToolKit.Controls { 9: 10: public class ImageListViewEventArgs : EventArgs { 11: private int itemIndex; 12: 13: public int ItemIndex { get { return itemIndex; } } 14: 15: public ImageListViewEventArgs( int index ) { 16: itemIndex = index; 17: } 18: } 19: 20: public delegate void ItemClickedEventHandler( object sender, Understanding the code in Listing 9.3 requires breaking it down into the various responsibilities: managing ImageListViewItems, handling mouse events, and providing scrolling. Managing ImageListViewItemsThe management of items within the control is twofold. First is the custom collection that interacts with the ImageListView control whenever an item is added or removed. Second is managing the location of the items within the drawing area of the control itself. The custom collection is fairly similar to the custom collection created from the OutlookBar control. The differences pertain to the interaction with its parent. In the case of the ImageListView control, when an item is added to the collection, the new item must calculate its size and the parent needs to be invalidated so that the new item will appear. The Insert method, on line 398 of Listing 9.3, contains this insertion logic. The next major task of managing ImageListViewItems is to determine their position within the client area of the ImageListView control. During the drawing of each item, its calculated height is used to determine the location of the next ImageListViewItem. In the event that there are more items to be drawn than space is available, scrolling buttons need to be displayed. Scrolling support is discussed later. Drawing logic is contained within the OnPaint method, on line 107 of Listing 9.3. The drawing logic is as follows:
This set of steps is repeated until there are no more items to draw or step 5 is reached. Handling Mouse EventsMouse events are the main means of interaction with the ImageListView control. In fact, the handling of mouse events represents a significant portion of the code for the ImageListView control. The mouse events used are OnMouseMove, OnMouseDown, and OnMouseUp. Starting with the OnMouseMove event, on line 153 of Listing 9.3, the logic is as follows:
The MouseMove event is used to provide visual feedback to the user. This visual feedback is accomplished by drawing the item under the mouse in hover mode. That is, the item appears to be raised up from the control. The next mouse event, OnMouseDown, on line 190, is used to determine whether an item or ScrollButton has been hit. The MouseDown method logic is as follows:
The final mouse event, OnMouseUp, on line 227 of Listing 9.3, is used to determine whether an item or ScrollButton has been clicked. If an item has been clicked, the OnItemClicked method is invoked for the current item. The OnItemClicked method in turn raises the ItemClicked event. If a ScrollButton has been hit, the topIndex member is adjusted up or down depending on the ScrollButton that was clicked. ScrollingThe scrolling functionality for the control is provided through the adjustment of the member topIndex. The topIndex member determines which ImageListViewItem will be drawn at the top of the control. Adjusting which item is drawn at the top enables the illusion of scrolling to be obtained. As seen by the implementation, there is no scrolling of the actual window contents. Rather, the item to be drawn first is adjusted. At this point, the control is functional but not well behaved within the designer, because it will not clean up any items it contains when the control itself is deleted. To realize all the work done so far, there is only one final step: creating a simple designer. This final step is discussed in the following section. ImageListViewDesignerFor the ImageListView control to be considered a well-behaved control, it must clean up after itself during design-time. Without a designer, the ImageListView control will orphan ImageListViewItems when deleted from a form. Orphaning of the ImageListViewItems happens when the ImageListView control is deleted and there is no designer logic to destroy subcomponents associated with the ImageListView control. The ImageListViewDesigner will take on the responsibility of destroying all ImageListViewItems when the ImageListView control is deleted. Subscribing to the OnComponentRemoving event of the IComponentChangeService allows for this cleanup to take place. When the component being removed is the ImageListView control, all the ImageListViewItems are destroyed. Listing 9.4 provides the implementation of the designer. Listing 9.4 ImageListViewDesigner 1: using System; 2: using System.Collections; 3: using System.ComponentModel; 4: using System.ComponentModel.Design; 5: using System.Drawing; 6: using System.Drawing.Design; 7: using System.Windows.Forms; 8: using System.Windows.Forms.Design; 9: using SAMS.ToolKit.Controls; 10: 11: 12: namespace SAMS.ToolKit.Design 13: { 14: 15: public class ItemListViewDesigner : ControlDesigner { 16: 17: 18: private void OnComponentRemoving( object sender, ComponentEventArgs e ) { 19: IDesignerHost designerHost = (IDesignerHost)GetService( Again, the only function of the designer is to remove orphaned ImageListViewItems during the removal of the ImageListView control. The OnComponentRemoving event handler, located on line 18 of Listing 9.4, accomplishes this task. To properly clean up during the removal of the ImageListView control, the designer iterates through the Items collection of the ImageListView control and has the IDesignerHost service destroy each component. It is necessary to use the IDesignerHost service to destroy these components in order for the components to be removed from the Icon Tray area as well as remove all generated code from the InitializeComponent method that relates to the now deleted components. With the completion of the designer, the process of building a basic OutlookBar control is finally finished. |
SIZE ); 23: } 24: } 25: 26: public ScrollButton( ScrollButtonOrientation sbo ) { 27: orientation = sbo; 28: 29: } 30: 31: public bool HitTest( Point pt ) { 32: return btnRect.Contains( pt ); 33: } 34: 35: public void Draw( Graphics g, ButtonState state ) { 36: DrawButton( g, state ); 37: DrawArrow( g, state ); 38: } 39: 40: private void DrawButton( Graphics g, ButtonState state ) { 41: if( btnRect.IsEmpty ) return; 42: ControlPaint.DrawButton( g, btnRect, state ); 43: } 44: 45: private void DrawArrow( Graphics g, ButtonState state ) { 46: if( orientation == ScrollButtonOrientation.Up ) 47: DrawUpArrow( g, state ); 48: else 49: DrawDownArrow( g, state ); 50: } 51: 52: 53: private void DrawUpArrow( Graphics g, ButtonState state ) { 54: Point[] pts = new Point[3]; 55: pts[0].X = btnRect.Left + (btnRect.Width / 2) + (state == ButtonState.Pushed ? 1 : 
EAN: 2147483647
Pages: 74