WinForms › Checked Image List Box › CheckedImageListBoxItem

CheckedImageListBoxItem

class.NET 6 / 8 / 10.NET Framework 4.8Binarymission.WinForms.Controls.ListControls

An 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.

public sealed class CheckedImageListBoxItem

Remarks

Add it to the list's Items. The control draws what is set: an item with no title is content text alone, and one whose IsChecked is null has no check box.

The colour, font and border properties override the list's for this item only; their defaults (Color.Empty, null, -1) mean "use the list's". The list does not watch its items: after changing one in place, call the list's CheckedImageListBox.PerformRefreshMeasurePaint.

Examples

var overdue = new CheckedImageListBoxItem
{
    Title = "Invoice INV-2291 is overdue",
    ContentText = "Northwind Traders - 1,240.00 GBP, due 14 days ago.",
    Image = Image.FromFile(@"icons\invoice-32.png"),
    IsChecked = false,
    BackgroundStartColor = Color.MistyRose,
    TitleTextColor = Color.DarkRed,
    TooltipTitle = "Account manager",
    TooltipContent = "Priya Shah, ext. 4410",
    Tag = invoiceId,
};
invoiceList.Items.Add(overdue);

Members at a glance

Constructors
`CheckedImageListBoxItem`	Initialises an empty, enabled item with no check box, no image and no overrides.
Properties
`BackgroundEndColor`	Gets or sets the second colour of this item's background gradient when it is not selected.
`BackgroundGradientFactor`	Gets or sets the direction of this item's background gradient when it is not selected.
`BackgroundStartColor`	Gets or sets the first colour of this item's background gradient when it is not selected.
`BorderColor`	Gets or sets the colour of this item's border when it is not selected.
`BorderThickness`	Gets or sets the width of this item's border when it is not selected.
`CheckedStateImage`	Gets or sets the image shown for this item when it is checked and its check state is drawn as an image.
`ContentText`	Gets or sets the item's descriptive text, drawn below the title and wrapped to the list's width.
`ContentTextColor`	Gets or sets the colour of this item's content text in every state.
`ContentTextFont`	Gets or sets the font of this item's content text.
`Image`	Gets or sets the image drawn between the check box and the text.
`IsChecked`	Gets or sets the item's check state, and whether it has a check box at all.
`IsEnabled`	Gets or sets whether the item is drawn as available.
`IsItemInFullView`	Gets whether the list last drew the item with its content text showing.
`ShouldDrawItemBorder`	Gets or sets whether this item has a border, overriding the list's `CheckedImageListBox.ShouldDrawItemBorder`.
`ShouldUseImageForCheckState`	Gets or sets whether this item shows its check state as an image rather than a check box, whatever the list's `CheckedImageListBox.ShouldUseImageForCheckState` says.
`Tag`	Gets or sets any object you want to keep with the item, such as the record it stands for.
`Title`	Gets or sets the item's title, drawn in bold above its content text.
`TitleFont`	Gets or sets the font of this item's title.
`TitleTextColor`	Gets or sets the colour of this item's title in every state.
`TooltipContent`	Gets or sets the text of the item's tool tip.
`TooltipTitle`	Gets or sets the title of the item's tool tip.
`UncheckedStateImage`	Gets or sets the image shown for this item when it is unchecked and its check state is drawn as an image.
Methods
`ToString`	Returns the item's title and content text on two lines, each followed by a line break – the text the list copies to the clipboard for Ctrl+C.

Constructors

CheckedImageListBoxItem

public CheckedImageListBoxItem()

Initialises an empty, enabled item with no check box, no image and no overrides.

Properties

BackgroundEndColor

public Color BackgroundEndColor

Gets or sets the second colour of this item's background gradient when it is not selected.

Value: The default, Color.Empty, uses the list's colour for the item's state.

BackgroundGradientFactor

public float BackgroundGradientFactor

Gets or sets the direction of this item's background gradient when it is not selected.

Value: In degrees clockwise from left-to-right (90 runs top to bottom). The default, -1 or any negative value, uses the list's. The list's CheckedImageListBox.ItemAlternateGradientFactor wins while alternating colours are on.

BackgroundStartColor

public Color BackgroundStartColor

Gets or sets the first colour of this item's background gradient when it is not selected.

Value: The default, Color.Empty, uses the list's colour for the item's state.

Remarks

Used whenever the item is not selected, under the pointer or not; a selected item uses the list's selected colours.

BorderColor

public Color BorderColor

Gets or sets the colour of this item's border when it is not selected.

Value: The default, Color.Empty, uses the list's colour for the item's state.

BorderThickness

public int BorderThickness

Gets or sets the width of this item's border when it is not selected.

Value: In pixels. The default, -1 or any negative value, uses the list's.

CheckedStateImage

public Image CheckedStateImage

Gets or sets the image shown for this item when it is checked and its check state is drawn as an image.

Value: The default, null, uses the list's CheckedImageListBox.CheckedStateImage.

ContentText

public string ContentText

Gets or sets the item's descriptive text, drawn below the title and wrapped to the list's width.

Value: The default is an empty string. In the list's collapsed view it shows only while the item is selected.

ContentTextColor

public Color ContentTextColor

Gets or sets the colour of this item's content text in every state.

Value: The default, Color.Empty, uses the list's colour for the item's state.

Remarks

Ignored while the item is disabled (IsEnabled) or the list is read-only.

ContentTextFont

public Font ContentTextFont

Gets or sets the font of this item's content text.

Value: The default, null, uses the list's CheckedImageListBox.ItemContentFont.

Image

public Image Image

Gets or sets the image drawn between the check box and the text.

Value: The default is null: no image.

Remarks

Drawn at its own pixel size, not scaled with the display; the row grows to fit it, up to the list box limit of 255 device pixels. Clicking it raises CheckedImageListBox.ItemImageClicked.

IsChecked

public bool? IsChecked

Gets or sets the item's check state, and whether it has a check box at all.

Value: true for checked, false for unchecked, null (the default) for no check box.

Remarks

Setting it in code does not raise CheckedImageListBox.ItemCheckStateChanged; call Invalidate() on the list, or use CheckedImageListBox.SetCheckState, which raises it and repaints. The list's CheckedImageListBox.IsItemCheckUncheckAllowed hides every check box when it is off.

IsEnabled

public bool IsEnabled

Gets or sets whether the item is drawn as available.

Value: The default is true.

Remarks

An item set to false has its title and content drawn in the system's grey text colour, and the user cannot check or uncheck it. It can still be selected, and code can still set its check state.

IsItemInFullView

public bool IsItemInFullView

Gets whether the list last drew the item with its content text showing.

Value: Maintained by the list as it draws: in the collapsed view, true for an open (selected) row; in the full view it is updated only for items with an Image, which it marks true.

Remarks

See CheckedImageListBox.EnableItemFullView.

ShouldDrawItemBorder

public bool? ShouldDrawItemBorder

Gets or sets whether this item has a border, overriding the list's CheckedImageListBox.ShouldDrawItemBorder.

Value: null (the default) to follow the list; false for no border while the item is unselected; true for a border, which while the list's setting is off shows only when the item is selected.

ShouldUseImageForCheckState

public bool ShouldUseImageForCheckState

Gets or sets whether this item shows its check state as an image rather than a check box, whatever the list's CheckedImageListBox.ShouldUseImageForCheckState says.

Value: The default is false: follow the list.

Remarks

The images are this item's CheckedStateImage and UncheckedStateImage, or the list's when they are null.

Title

public string Title

Gets or sets the item's title, drawn in bold above its content text.

Value: The default is an empty string: no title. The list's collapsed view needs every item to have one.

TitleFont

public Font TitleFont

Gets or sets the font of this item's title.

Value: The default, null, uses the list's CheckedImageListBox.ItemTitleFont.

TitleTextColor

public Color TitleTextColor

Gets or sets the colour of this item's title in every state.

Value: The default, Color.Empty, uses the list's colour for the item's state.

Remarks

Ignored while the item is disabled (IsEnabled) or the list is read-only.

TooltipContent

public string TooltipContent

Gets or sets the text of the item's tool tip.

Value: The default is null: no tool tip.

Remarks

An item has a tool tip only when this is set. It is drawn by the list when its CheckedImageListBox.ShouldShowDefaultTooltipOnItemHover is on, or by your handlers of CheckedImageListBox.ItemTooltipAboutToPopup and CheckedImageListBox.ItemTooltipAboutToDraw.

TooltipTitle

public string TooltipTitle

Gets or sets the title of the item's tool tip.

Value: The default is null: no title.

UncheckedStateImage

public Image UncheckedStateImage

Gets or sets the image shown for this item when it is unchecked and its check state is drawn as an image.

Value: The default, null, uses the list's CheckedImageListBox.UncheckedStateImage.

Methods

ToString

public override string ToString()

Returns the item's title and content text on two lines, each followed by a line break – the text the list copies to the clipboard for Ctrl+C.

Returns

Title: and the title, then Content: and the content text.

CheckedImageListBoxItem

Remarks

Examples

Members at a glance

Constructors

CheckedImageListBoxItem

Properties

BackgroundEndColor

BackgroundGradientFactor

BackgroundStartColor

Remarks

BorderColor

BorderThickness

CheckedStateImage

ContentText

ContentTextColor

Remarks

ContentTextFont

Image

Remarks

IsChecked

Remarks

IsEnabled

Remarks

IsItemInFullView

Remarks

ShouldDrawItemBorder

ShouldUseImageForCheckState

Remarks

Tag

Title

TitleFont

TitleTextColor

Remarks

TooltipContent

Remarks

TooltipTitle

See also

UncheckedStateImage

Methods

ToString

Returns