mirror of https://github.com/Stone-Red-Code/docs-desktop.git synced 2026-09-04 09:06:04 +02:00

Files

T

Andy De George 99e90fa162 Update metadata rules and individual articles (#142 )

* Add conceptual topic type for framework

* Add NET WPF article topic types

* Framework winforms overview topic types

* Update metadata

* Update walkthrough-my-first-wpf-desktop-application.md

2020-12-03 09:58:46 -08:00

13 KiB

Raw Blame History

title, ms.date, ms.topic, helpviewer_keywords, ms.assetid

title

ms.date

ms.topic

helpviewer_keywords

ms.assetid

Controls with Built-In Owner-Drawing Support

03/30/2017

overview

drawing [Windows Forms], owner

drawing [Windows Forms], custom

controls [Windows Forms], changing appearance

custom drawing

owner drawing

3823d01e-9610-43e6-864d-99f9b7c2b351

Controls with Built-In Owner-Drawing Support

Owner drawing in Windows Forms, which is also known as custom drawing, is a technique for changing the visual appearance of certain controls.

Note

The word "control" in this topic is used to mean classes that derive from either xref:System.Windows.Forms.Control or xref:System.ComponentModel.Component.

Typically, Windows handles painting automatically by using property settings such as xref:System.Windows.Forms.Control.BackColor%2A to determine the appearance of a control. With owner drawing, you take over the painting process, changing elements of appearance that are not available by using properties. For example, many controls let you set the color of the text that is displayed, but you are limited to a single color. Owner drawing enables you to do things like display part of the text in black and part in red.

In practice, owner drawing is similar to drawing graphics on a form. For example, you could use graphics methods in a handler for the form's xref:System.Windows.Forms.Control.Paint event to emulate a ListBox control, but you would have to write your own code to handle all user interaction. With owner drawing, the control uses your code to draw its contents but otherwise retains all its intrinsic capabilities. You can use graphics methods to draw each item in the control or to customize some aspects of each item while you use the default appearance for other aspects of each item.

Owner Drawing in Windows Forms Controls

To perform owner drawing in controls that support it, you will typically set one property and handle one or more events.

Most controls that support owner drawing have an OwnerDraw or DrawMode property that indicates whether the control will raise its drawing-related event or events when it paints itself.

Controls that do not have an OwnerDraw or DrawMode property include the DataGridView control, which provides drawing events that occur automatically, and the ToolStrip control, which is drawn using an external rendering class that has its own drawing-related events.

There are many different kinds of drawing events, but a typical drawing event occurs in order to draw a single item within a control. The event handler receives an EventArgs object that contains information about the item being drawn and tools you can use to draw it. For example, this object typically contains the item's index number within its parent collection, a xref:System.Drawing.Rectangle that indicates the item's display boundaries, and a xref:System.Drawing.Graphics object for calling paint methods. For some events, the EventArgs object provides additional information about the item and methods that you can call to paint some aspects of the item by default, such as the background or a focus rectangle.

To create a reusable control that contains your owner-drawn customizations, create a new class that derives from a control class that supports owner drawing. Rather than handling drawing events, include your owner-drawing code in overrides for the appropriate OnEventName method or methods in the new class. Make sure that you call the base class OnEventName method or methods in this case so that users of your control can handle owner-drawing events and provide additional customization.

The following Windows Forms controls support owner drawing in all versions of the .NET Framework:

The following controls support owner drawing only in .NET Framework 2.0:

The following controls support owner drawing and are new in .NET Framework 2.0:

The following sections provide additional details for each of these controls.

ListBox and ComboBox Controls

The xref:System.Windows.Forms.ListBox and xref:System.Windows.Forms.ComboBox controls enable you to draw individual items in the control either all in one size, or in varying sizes.

Note

Although the xref:System.Windows.Forms.CheckedListBox control is derived from the xref:System.Windows.Forms.ListBox control, it does not support owner drawing.

To draw each item the same size, set the DrawMode property to xref:System.Windows.Forms.DrawMode.OwnerDrawFixed and handle the DrawItem event.

To draw each item using a different size, set the DrawMode property to xref:System.Windows.Forms.DrawMode.OwnerDrawVariable and handle both the MeasureItem and DrawItem events. The MeasureItem event lets you indicate the size of an item before the DrawItem event occurs for that item.

For more information, including code examples, see the following topics:

MenuItem Component

The xref:System.Windows.Forms.MenuItem component represents a single menu item in a xref:System.Windows.Forms.MainMenu or xref:System.Windows.Forms.ContextMenu component.

To draw a xref:System.Windows.Forms.MenuItem, set its OwnerDraw property to true and handle its DrawItem event. To customize the size of the menu item before the DrawItem event occurs, handle the item's MeasureItem event.