HypernovaDesktop Components · docs
Binarymission
WinForms › Checked Image List Box

Checked Image List Box

.NET Framework 4.8.NET 6 / 8 / 10v3.0.0WinForms

A list box whose items carry a title, a line of description, an image and a check box – for task lists, feature pickers, notification lists and option lists that need more than one line of plain text.

7public types
154public members
1namespaces

Assembly

AssemblyBinarymission.WinForms.Controls.CheckedImageListBox.dll
Root namespaceBinarymission.WinForms.Controls.ListControls
Target frameworks.NET Framework 4.8, .NET 6 / 8 / 10

Overview

What it is for

It is a ListBox in everything but the drawing – Items, the selection modes, SelectedIndex, scrolling and the keyboard work as usual – so it can replace one directly. Every row is measured and drawn by the control, with gradients, borders, hover highlighting and per-item colours and fonts.

Items

Add CheckedImageListBoxItem objects to Items: each has a CheckedImageListBoxItem.Title, CheckedImageListBoxItem.ContentText, an CheckedImageListBoxItem.Image, a check state and its own tool tip. A plain string is shown as content text with no title and no check box. Any other object is not drawn.

Check boxes

An item shows a check box when its CheckedImageListBoxItem.IsChecked is true or false, and none when it is null (the default). With CheckOnClick on, every click on an item toggles it; off, the first click selects an item and a further click on it toggles it. Space toggles the selected item. Each toggle by the user raises ItemCheckStateChanged.

Full view and collapsed view

With EnableItemFullView on (the default) every row shows its title and content text. Off, each row is one line – check box, image, title – and only the selected rows open to show their content text, which keeps a long list compact. The collapsed view needs every item to have a title.

Sizes

Spacings, margins, the check box size and the frame are in logical pixels (96 DPI) and scale with the display; images are drawn at their own pixel size. Windows limits a list box row to 255 device pixels, so a taller item is cut short.

Tip

Many appearance properties re-measure every item when set. When configuring a long list in code, set the appearance before adding the items.

Getting started

using Binarymission.WinForms.Controls.ListControls;

var releaseTasks = new CheckedImageListBox
{
    Location = new Point(12, 12),
    Size = new Size(380, 340),
    CheckOnClick = true,
    ShouldDrawFrame = true,
    ShouldShowDefaultTooltipOnItemHover = true,
    ItemSelectedStartColor = Color.LightSteelBlue,
    ItemUnselectedStartColor = Color.WhiteSmoke,
};

releaseTasks.Items.Add(new CheckedImageListBoxItem
{
    Title = "Renew the TLS certificate",
    ContentText = "The certificate on the web server expires in 9 days.",
    Image = Image.FromFile(@"icons\certificate-32.png"),
    IsChecked = false,
    TooltipTitle = "Owner",
    TooltipContent = "Infrastructure on-call",
});
releaseTasks.Items.Add(new CheckedImageListBoxItem
{
    Title = "Publish release notes",
    ContentText = "Version 4.2 - fixes for invoicing and the export to PDF.",
    Image = Image.FromFile(@"icons\notes-32.png"),
    IsChecked = true,
});

releaseTasks.ItemCheckStateChanged += (sender, e) =>
    statusLabel.Text = e.CheckedImageListBoxItem.Title + (e.NewCheckState == true ? " - done" : " - reopened");

Controls.Add(releaseTasks);

API reference

Binarymission.WinForms.Controls.ListControls

class CheckedImageListBoxA list box whose items carry a title, a line of description, an image and a check box - for task lists, feature pickers, notification lists and option lists that need more than one line of plain text.
class CheckedImageListBoxItemAn item of a CheckedImageListBox: a title, a line of content text, an image and an optional check box, with its own tool tip and, where needed, its own colours and fonts.
class CheckedImageListBoxItemCheckStateChangedEventArgsData for ItemCheckStateChanged: the item whose check box changed, and its state before and after.
class CheckedImageListBoxItemHoverChangedEventArgsData for ItemHoverChanged: the item now under the pointer, where the pointer is, and whether the item shows its content text.
class CheckedImageListBoxItemTooltipPopupEventArgsData for ItemTooltipAboutToPopup: the tool tip's popup data and the item it is for.
class CheckedImageListBoxTooltipDrawEventArgsData for ItemTooltipAboutToDraw: the tool tip's drawing surface and the item it is for.
class CheckedImageListBoxVerticalScrollEventArgsData for VerticalScroll: how the list scrolled. The event is declared as a plain EventHandler; cast its arguments to this type.