0 out of 1 rated this helpful - Rate this topic

ToolStripRenderer Class

Handles the painting functionality for ToolStrip objects.

Namespace:  System.Windows.Forms
Assembly:  System.Windows.Forms (in System.Windows.Forms.dll)
public abstract class ToolStripRenderer

The ToolStripRenderer type exposes the following members.

  Name Description
Protected method ToolStripRenderer Initializes a new instance of the ToolStripRenderer class.
Top
  Name Description
Public method Static member CreateDisabledImage Creates a gray-scale copy of a given image.
Public method DrawArrow Draws an arrow on a ToolStripItem.
Public method DrawButtonBackground Draws the background for a ToolStripButton.
Public method DrawDropDownButtonBackground Draws the background for a ToolStripDropDownButton.
Public method DrawGrip Draws a move handle on a ToolStrip.
Public method DrawImageMargin Draws the space around an image on a ToolStrip.
Public method DrawItemBackground Draws the background for a ToolStripItem.
Public method DrawItemCheck Draws an image on a ToolStripItem that indicates the item is in a selected state.
Public method DrawItemImage Draws an image on a ToolStripItem.
Public method DrawItemText Draws text on a ToolStripItem.
Public method DrawLabelBackground Draws the background for a ToolStripLabel.
Public method DrawMenuItemBackground Draws the background for a ToolStripMenuItem.
Public method DrawOverflowButtonBackground Draws the background for an overflow button.
Public method DrawSeparator Draws a ToolStripSeparator.
Public method DrawSplitButton Draws a ToolStripSplitButton.
Public method DrawStatusStripSizingGrip Draws a sizing grip.
Public method DrawToolStripBackground Draws the background for a ToolStrip.
Public method DrawToolStripBorder Draws the border for a ToolStrip.
Public method DrawToolStripContentPanelBackground Draws the background of the ToolStripContentPanel.
Public method DrawToolStripPanelBackground Draws the background of the ToolStripPanel.
Public method DrawToolStripStatusLabelBackground Draws the background of the ToolStripStatusLabel.
Public method Equals(Object) Determines whether the specified Object is equal to the current Object. (Inherited from Object.)
Protected method Finalize Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
Public method GetHashCode Serves as a hash function for a particular type. (Inherited from Object.)
Public method GetType Gets the Type of the current instance. (Inherited from Object.)
Protected method Initialize When overridden in a derived class, provides for custom initialization of the given ToolStrip.
Protected method InitializeContentPanel Initializes the specified ToolStripContentPanel.
Protected method InitializeItem When overridden in a derived class, provides for custom initialization of the given ToolStripItem.
Protected method InitializePanel Initializes the specified ToolStripPanel.
Protected method MemberwiseClone Creates a shallow copy of the current Object. (Inherited from Object.)
Protected method OnRenderArrow Raises the RenderArrow event.
Protected method OnRenderButtonBackground Raises the RenderButtonBackground event.
Protected method OnRenderDropDownButtonBackground Raises the RenderDropDownButtonBackground event.
Protected method OnRenderGrip Raises the RenderGrip event.
Protected method OnRenderImageMargin Draws the item background.
Protected method OnRenderItemBackground Raises the OnRenderItemBackground event.
Protected method OnRenderItemCheck Raises the RenderItemCheck event.
Protected method OnRenderItemImage Raises the RenderItemImage event.
Protected method OnRenderItemText Raises the RenderItemText event.
Protected method OnRenderLabelBackground Raises the RenderLabelBackground event.
Protected method OnRenderMenuItemBackground Raises the RenderMenuItemBackground event.
Protected method OnRenderOverflowButtonBackground Raises the RenderOverflowButtonBackground event.
Protected method OnRenderSeparator Raises the RenderSeparator event.
Protected method OnRenderSplitButtonBackground Raises the OnRenderSplitButtonBackground event.
Protected method OnRenderStatusStripSizingGrip Raises the RenderStatusStripSizingGrip event.
Protected method OnRenderToolStripBackground Raises the RenderToolStripBackground event.
Protected method OnRenderToolStripBorder Raises the RenderToolStripBorder event.
Protected method OnRenderToolStripContentPanelBackground Raises the RenderToolStripContentPanelBackground event.
Protected method OnRenderToolStripPanelBackground Raises the RenderToolStripPanelBackground event.
Protected method OnRenderToolStripStatusLabelBackground Raises the RenderToolStripStatusLabelBackground event.
Public method ToString Returns a string that represents the current object. (Inherited from Object.)
Top
  Name Description
Public event RenderArrow Occurs when an arrow on a ToolStripItem is rendered.
Public event RenderButtonBackground Occurs when the background for a ToolStripButton is rendered
Public event RenderDropDownButtonBackground Occurs when the background for a ToolStripDropDownButton is rendered.
Public event RenderGrip Occurs when the move handle for a ToolStrip is rendered.
Public event RenderImageMargin Draws the margin between an image and its container.
Public event RenderItemBackground Occurs when the background for a ToolStripItem is rendered.
Public event RenderItemCheck Occurs when the image for a selected ToolStripItem is rendered.
Public event RenderItemImage Occurs when the image for a ToolStripItem is rendered.
Public event RenderItemText Occurs when the text for a ToolStripItem is rendered.
Public event RenderLabelBackground Occurs when the background for a ToolStripLabel is rendered.
Public event RenderMenuItemBackground Occurs when the background for a ToolStripMenuItem is rendered.
Public event RenderOverflowButtonBackground Occurs when the background for an overflow button is rendered.
Public event RenderSeparator Occurs when a ToolStripSeparator is rendered.
Public event RenderSplitButtonBackground Occurs when the background for a ToolStripSplitButton is rendered.
Public event RenderStatusStripSizingGrip Occurs when the display style changes.
Public event RenderToolStripBackground Occurs when the background for a ToolStrip is rendered.
Public event RenderToolStripBorder Occurs when the border for a ToolStrip is rendered.
Public event RenderToolStripContentPanelBackground Draws the background of a ToolStripContentPanel.
Public event RenderToolStripPanelBackground Draws the background of a ToolStripPanel.
Public event RenderToolStripStatusLabelBackground Draws the background of a ToolStripStatusLabel.
Top

Use the ToolStripRenderer class to apply a particular style or theme to a ToolStrip. Rather than custom painting a ToolStrip and the ToolStripItem objects it contains, you set the ToolStrip.Renderer property to an object that inherits from ToolStripRenderer. The painting specified by the ToolStripRenderer is applied to the ToolStrip, as well as the items it contains.

You can do custom painting in ToolStrip controls in several ways. As with other Windows Forms controls, the ToolStrip and ToolStripItem both have overridable OnPaint methods and Paint events. As with regular painting, the coordinate system is relative to the client area of the control; that is, the upper left-hand corner of the control is 0, 0. The Paint event and OnPaint method for a ToolStripItem behave like other control paint events.

The ToolStripRenderer class has overridable methods for painting the background, item background, item image, item arrow, item text, and border of the ToolStrip. The event arguments for these methods expose several properties such as rectangles, colors, and text formats that you can adjust as desired.

To adjust just a few aspects of how an item is painted, you typically override the ToolStripRenderer.

If you are writing a new item and want to control all aspects of the painting, override the OnPaint method. From within OnPaint, you can use methods from the ToolStripRenderer.

By default, the ToolStrip is double buffered, taking advantage of the OptimizedDoubleBuffer setting.

The following code example demonstrates how to implement a custom ToolStripRenderer class. The GridStripRenderer class customizes three aspects of the GridStrip control's appearance: GridStrip border, ToolStripButton border, and ToolStripButton image. For a full code listing, see How to: Implement a Custom ToolStripRenderer.


// This class implements a custom ToolStripRenderer for the 
// GridStrip control. It customizes three aspects of the 
// GridStrip control's appearance: GridStrip border, 
// ToolStripButton border, and ToolStripButton image.
internal class GridStripRenderer : ToolStripRenderer
{   
    // The style of the empty cell's text.
    private static StringFormat style = new StringFormat();

    // The thickness (width or height) of a 
    // ToolStripButton control's border.
    static int borderThickness = 2;

    // The main bitmap that is the source for the 
    // subimagesthat are assigned to individual 
    // ToolStripButton controls.
    private Bitmap bmp = null;

    // The brush that paints the background of 
    // the GridStrip control.
    private Brush backgroundBrush = null;

    // This is the static constructor. It initializes the
    // StringFormat for drawing the text in the empty cell.
    static GridStripRenderer()
    {
        style.Alignment = StringAlignment.Center;
        style.LineAlignment = StringAlignment.Center;
    }

    // This method initializes the GridStripRenderer by
    // creating the image that is used as the source for
    // the individual button images.
    protected override void Initialize(ToolStrip ts)
    {
        base.Initialize(ts);

        this.InitializeBitmap(ts);
    }

    // This method initializes an individual ToolStripButton
    // control. It copies a subimage from the GridStripRenderer's
    // main image, according to the position and size of 
    // the ToolStripButton.
    protected override void InitializeItem(ToolStripItem item)
    {
        base.InitializeItem(item);

        GridStrip gs = item.Owner as GridStrip;

        // The empty cell does not receive a subimage.
        if ((item is ToolStripButton) &&
            (item != gs.EmptyCell))
        {
            // Copy the subimage from the appropriate 
            // part of the main image.
            Bitmap subImage = bmp.Clone(
                item.Bounds,
                PixelFormat.Undefined);

            // Assign the subimage to the ToolStripButton
            // control's Image property.
            item.Image = subImage;
        }
    }

    // This utility method creates the main image that
    // is the source for the subimages of the individual 
    // ToolStripButton controls.
    private void InitializeBitmap(ToolStrip toolStrip)
    {
        // Create the main bitmap, into which the image is drawn.
        this.bmp = new Bitmap(
            toolStrip.Size.Width,
            toolStrip.Size.Height);

        // Draw a fancy pattern. This could be any image or drawing.
        using (Graphics g = Graphics.FromImage(bmp))
        {
            // Draw smoothed lines.
            g.SmoothingMode = SmoothingMode.AntiAlias;

            // Draw the image. In this case, it is 
            // a number of concentric ellipses. 
            for (int i = 0; i < toolStrip.Size.Width; i += 8)
            {
                g.DrawEllipse(Pens.Blue, 0, 0, i, i);
            }
        }
    }

    // This method draws a border around the GridStrip control.
    protected override void OnRenderToolStripBorder(
        ToolStripRenderEventArgs e)
    {
        base.OnRenderToolStripBorder(e);

        ControlPaint.DrawFocusRectangle(
            e.Graphics,
            e.AffectedBounds,
            SystemColors.ControlDarkDark,
            SystemColors.ControlDarkDark);
    }

    // This method renders the GridStrip control's background.
    protected override void OnRenderToolStripBackground(
        ToolStripRenderEventArgs e)
    {
        base.OnRenderToolStripBackground(e);

        // This late initialization is a workaround. The gradient
        // depends on the bounds of the GridStrip control. The bounds 
        // are dependent on the layout engine, which hasn't fully
        // performed layout by the time the Initialize method runs.
        if (this.backgroundBrush == null)
        {
            this.backgroundBrush = new LinearGradientBrush(
               e.ToolStrip.ClientRectangle,
               SystemColors.ControlLightLight,
               SystemColors.ControlDark,
               90,
               true);
        }

        // Paint the GridStrip control's background.
        e.Graphics.FillRectangle(
            this.backgroundBrush, 
            e.AffectedBounds);
    }

    // This method draws a border around the button's image. If the background
    // to be rendered belongs to the empty cell, a string is drawn. Otherwise,
    // a border is drawn at the edges of the button.
    protected override void OnRenderButtonBackground(
        ToolStripItemRenderEventArgs e)
    {
        base.OnRenderButtonBackground(e);

        // Define some local variables for convenience.
        Graphics g = e.Graphics;
        GridStrip gs = e.ToolStrip as GridStrip;
        ToolStripButton gsb = e.Item as ToolStripButton;

        // Calculate the rectangle around which the border is painted.
        Rectangle imageRectangle = new Rectangle(
            borderThickness, 
            borderThickness, 
            e.Item.Width - 2 * borderThickness, 
            e.Item.Height - 2 * borderThickness);

        // If rendering the empty cell background, draw an 
        // explanatory string, centered in the ToolStripButton.
        if (gsb == gs.EmptyCell)
        {
            e.Graphics.DrawString(
                "Drag to here",
                gsb.Font, 
                SystemBrushes.ControlDarkDark,
                imageRectangle, style);
        }
        else
        {
            // If the button can be a drag source, paint its border red.
            // otherwise, paint its border a dark color.
            Brush b = gs.IsValidDragSource(gsb) ? b = 
                Brushes.Red : SystemBrushes.ControlDarkDark;

            // Draw the top segment of the border.
            Rectangle borderSegment = new Rectangle(
                0, 
                0, 
                e.Item.Width, 
                imageRectangle.Top);
            g.FillRectangle(b, borderSegment);

            // Draw the right segment.
            borderSegment = new Rectangle(
                imageRectangle.Right,
                0,
                e.Item.Bounds.Right - imageRectangle.Right,
                imageRectangle.Bottom);
            g.FillRectangle(b, borderSegment);

            // Draw the left segment.
            borderSegment = new Rectangle(
                0,
                0,
                imageRectangle.Left,
                e.Item.Height);
            g.FillRectangle(b, borderSegment);

            // Draw the bottom segment.
            borderSegment = new Rectangle(
                0,
                imageRectangle.Bottom,
                e.Item.Width,
                e.Item.Bounds.Bottom - imageRectangle.Bottom);
            g.FillRectangle(b, borderSegment);
        }
    }
}


.NET Framework

Supported in: 4, 3.5, 3.0, 2.0

.NET Framework Client Profile

Supported in: 4, 3.5 SP1

Windows 7, Windows Vista SP1 or later, Windows XP SP3, Windows XP SP2 x64 Edition, Windows Server 2008 (Server Core not supported), Windows Server 2008 R2 (Server Core supported with SP1 or later), Windows Server 2003 SP2

The .NET Framework does not support all versions of every platform. For a list of the supported versions, see .NET Framework System Requirements.
Any public static (Shared in Visual Basic) members of this type are thread safe. Any instance members are not guaranteed to be thread safe.
Did you find this helpful?
(1500 characters remaining)
Community Content Add
Annotations FAQ