CheckedImageListBox .NET

for  WinForms

  • A custom built "Owner-draw variable" drawn Listbox control for Windows Forms
  • At the simplest level, simply supply the strings (items), and you are all set to go  to use the control
  • Specialized custom listbox item class that exposes various item level properties
  • Provides two specialized modes of display: Full-view and Partial-view modes
  • Supports advanced item anatomy: An Item image, checkbox, title and content sections in the item
  • Supports annotation image and Side-bar rendering upon mouse-hover on items  
  • Heavily customizable: Almost all aspects of the drawing are customizable




We have all been there, one time or the other, i.e. having to wire up into the stock .NET ListBox control to owner-draw the items per our needs, only to find very soon that:


  • It becomes a nightmare to manage the custom paint and item measurement / sizing code that we need to write, in order to cater to various of the advanced UI aspects we may need in the control
  • Its almost impossible to deterministically request the control to re-measure the items as and when we need it (rather than when the standard .NET ListBox determines it necessary)



Our CheckedImageListBox .NET control is specifically designed to completely remove the hard and complex work around the above described core issues such that you will never need to tackle them yourself, and in addition, also provide an extensive User-interface rich features such that your code simply sets the appropriate properties in the control and get the much desired UI you always wanted to have, without ever having to worry about the intricacies of making the features yourself.




What is the CheckedImageListBox .NET control



CheckedImageListBox .NET control is a custom written WinForms .NET Listbox control that presents your data items in a list-box style display, and in addition provides may extended modern User-interface features, including...


  • Ready to use OwnerDrawVariable mode item drawing, such that there is no need for your code to custom draw items: You simply set property values to say how you want the items to look and feel, and the control does the rest for you.
  • Draws an (optional) image, (optional) check-state, (optional) Title and a main content piece for the items
  • Draws a side-bar upon mouse-hover
  • Draws annotation upon mouse-hover, on a per item basis
  • Supports drawing an Outlook style User-interface as is seen in its messages list view style of rendering items
  • Supports extended item display modes, viz., Full View and Partial View
  • Provides automatic multi-line formatting of item content and title text, as the controls size changes at run-time
  • Provides built-in support for displaying alternate colored items
  • Allows customizing background color and gradient drawing brush for control's various visual states viz., Enabled, Disabled and Read-only, and also across item's visual states viz., Selected, Unselected, and Hot (Mouse-hovered)
  • Allows extensive customization of many UI aspects of the control, including colors, gradients, padding, sizing, and many more.



Core Features

Advanced ListBox User-interface


The control is designed from ground-up to provide an exciting rich modern User-interface to display list of data items.


The anatomy of the control includes:


  • (Optional) A check-state, which can be represented by a (built-in) check-box, or even a by a custom supplied check/uncheck state images
  • (Optional) An item Image, that is positioned just after the check-state (or as the first item if the item's check-state feature is not enabled)
  • (Optional) An item title
  • (Mandatory) An item content text (that can run to multiple lines), and which can be custom formatted too if you need, and
  • (Optional) An item mouse-hover annotation User-interface artifact / image
  • (Optional) A side-bar that will be drawn at the left hand side of the item, whenever an item is in mouse hover or is currently selected.


The control supports automatic Multi-line text for Item content text and title text.


The control provides for rich customization of its user-interface on various counts, including:


  • Mouse hover background/foreground colors and gradients customization : This allows to you to setup different colors and gradients for different visual states of the items such as Selected, Un-selected, Hovered, Disabled, read-only, etc.
  • Image can be configured on a per item basis
  • Item check-state size can be configured so that the UI representation of it (be it the built-in check-box or a custom image) can be customized for its size (width and height)
  • The mouse-hover annotation can be customized such that you can display a custom image that can be displayed when the mouse pointer hovers over the item, and this can be setup on  per item basis
  • The Side-bar width can be configured to any width size, and also its colors, border thickness, and the sidebar fill color and gradient factor for its drawing brush
  • The Item's border thickness can be configured, and so is the border color. Also different border color can be set for different visual states of the item.
  • Gap/spacing between items also allowed to be customized
  • Item level tool-tip drawing can be customized too. The control draws item specific tool-tip when mouse pointer hovers on it and draws a rich user-interface tool-tip by itself by default, but it also allows your code to intercept a tooltip specific event and handle it in order to custom draw the tool-tip by your own application code
  • Item annotation click event is raised by the control so that your application code can custom handle it to perform some application specific commands when the user clicks on the annotation image.

Customizable Item side-bar drawing


The control supports drawing a sidebar on the item whenever the mouse pointer is moved over an item or when a given item is currently in selected state.


This gives the control, a very modern look-and-feel and also adds to the nice overall aesthetic effect.


The customization feature allows you to specify many aspects for drawing the side-bar:


  • The colors (start and end colors)
  • The border thickness and color for the side bar border
  • The size of the sidebar itself
  • The choice of different sidebar colors (start and end colors), the border color and thickness and size of the sidebar to apply when an item is currently in selected state or unselected but currently being mouse hovered.


The sidebar feature is optional, so it can be switched off by setting the appropriate property value to false.



Full-view and Partial-view mode of Items display


The items in the control can be displayed in two different modes, Full_view and Partial-View mode.


The Full-view mode is where the control renders the full contents of all the items displayed in the view.


In Partial-view mode, the control renders like so:


  • The full view of the content for the item (s) that is currently selected, and
  • The partial view of the content for all the remaining items that are not currently selected



When in partial-view mode, the control displays the most important content items from the items that are currently in partial view.

These most important content items being:


  • The checked/unchecked state of the item (if check state feature is enabled)
  • The item sidebar visual
  • The item's title text, and
  • The annotation image (when the user moves the mouse pointer over the item)



The partial-view mode helps in many ways:


  • More items displayed in the view: Since it shows the full content of only the currently selected items, many more items can be shown in the current display view size available.
  • Better User-experience: The user can focus his attention to the details in the current item of interest -i.e. the selected item, rather than viewing a lot of content from all other items displayed simultaneously.

Automatic different sized item rendering


The control automatically works out the correct item content width as appropriate for each item, depending on the UI artifacts that it needs to render for each item, i.e. whether the control is currently rendering Item image, checkbox, or Mouse-hover annotation (at the right-hand), and accordingly depending on the correct width available, it renders the item content text in the available space.


In the screen-shot below, it can be seen that item 0 (title 0) does not require the side bar, or the mouse hover-annotation image, and accordingly has more space to render the content text, but item 2 (title 2) is currently mouse-hovered, and hence has less space for rendering its content text (after allowing for the sidebar and annotation image space).


The control works out the available space for each item, and renders its content text using as much space available to it (subject to the string formatting setup that you may have setup in the control, of course).

Items building with simple strings and content format customization


The control is extremely simple to setup its items, even with standard string items as its content.

It will take your string items and format it according to your custom string format setup that you can supply to it, and it will autoamtically do all the heavy lifting to render the selection/hover/de-selection rendering user-experience with the default built in drawing setup, so that its ready to use straight out-of-the-box.


In the screen-shot below, we can see a sample screen where the control was instantiated and its items setup just by using its Items collection property, and its all ready to use. Its that simple!


You could also, optionally, as can be seen from the code screen-shot below, customize the string format of the content for items and the control will use that to render the text.

Built-in Alternate Items drawing feature


The control provides built-in feature of drawing alternate items with different colors.

With this feature, you can setup the colors (start color and end color) and gradient factor to apply for the color brush to draw the alternate items.


In the screen-shot below, we can see a sample screen where the control is setup to draw alternating colors for items, and the simple code to set the relevant properties.

Advanced design-time capabilities


A custom designer class is implemented as part of the control library which allows design-time interaction with the control (i.e. while the control is in the design mode in the Visual studio IDE designer) features, including:


  • individual list item selection
  • scrolling of the control's content / items


Extensive and simple to use customization properties and Method APIs


The control exposes numerous properties and method APIs to let you customize the control's look-and-feel to your heart's content.


You can see from the screen-shots below, a sub-set of a wide range of properties that you can use to customize the control heavily.

Almost every User-interface aspect can be custom configured.

Extensive events to subscribe


The control exposes numerous events that you can subscribe to and custom handle in your applications.

The event parameters gives you a wide range of information that you can use in your custom handler code.