BarManager.CustomDrawItem Event

Allows you to manually paint bar item links.

Namespace: DevExpress.XtraBars

Assembly: DevExpress.XtraBars.v24.1.dll

NuGet Package: DevExpress.Win.Navigation

Declaration

C#

[DXCategory("Events")]
public event BarItemCustomDrawEventHandler CustomDrawItem

VB.NET

<DXCategory("Events")>
Public Event CustomDrawItem As BarItemCustomDrawEventHandler

Event Data

The CustomDrawItem event's data class is BarItemCustomDrawEventArgs. The following properties provide information specific to this event:

Property	Description
Bounds	Returns this bar item link’s bounds.
Cache	Provides access to this bar item link’s graphics cache.
DrawOnlyText	Gets whether or not this bar item link should display only its caption.
DropDownBounds	Gets the area occupied by the drop-down menu for this bar item link.
Glyph	Gets the icon that should be displayed for this bar item link by default.
GlyphBounds	Gets the area occupied by this bar item link’s default icon.
Graphics	Provides access to the Graphics object associated with this bar item link.
Handled	Gets or sets whether or not this item link is painted manually.
LinkInfo	Specifies the info for the bar item link related to this event.
RibbonItemInfo	Specifies the info for the ribbon item related to this event.
ShouldDrawCheckBox	Gets whether or not this bar item link should display a check box.
ShouldDrawDropDown	Gets whether or not this bar item link should display its drop-down menu by default.
ShouldDrawEditor	Gets whether or not this bar item link should display an editor.
State	Gets the current bar item link state (normal, selected, pressed, checked, disabled etc.).
Text	Gets the default text that should be displayed by this bar item link.
TextBounds	Gets the area occupied by this bar item link’s default text.

The event data class exposes the following methods:

Method	Description
Draw()	Draws the related item link entirely with its default appearance.
DrawArrow()	Draws a drop-down arrow with its default appearance.
DrawBackground()	Draws the default background for the current bar item link.
DrawBorder()	Draws a border with its default appearance.
DrawCheckBox()	Draws a checkbox with its default appearance for this bar item link.
DrawDropDownBackground()	Draws the default background for this bar item link’s drop-down menu.
DrawEditor()	Draws a required editor with default appearance settings within this bar item link.
DrawGlyph()	Draws the default icon for this bar item link.
DrawHtml(HtmlTemplate, DxHtmlPainterContext, Action<DxHtmlPainterArgs>)	Paints the required HTML template inside an element that raised this event. The context parameter allows you to assign an object that transfers mouse events to template elements.
DrawHtml(HtmlTemplate, Action<DxHtmlPainterArgs>)	Paints the required HTML template inside an element that raised this event.
DrawText()	Draws the default text for this bar item link.
DrawText(AppearanceObject)	Draws the default text with custom appearance settings for this bar item link.

Remarks

The CustomDrawItem event occurs each time a bar manager needs to display an item link. This event should be used as follows.

• Use read-only properties provided by the BarItemCustomDrawEventArgs object to get the required info about the link that fired this event (e.g., the BarItemCustomDrawEventArgs.ShouldDrawDropDown and BarItemCustomDrawEventArgs.State properties).
• Set the BarCustomDrawEventArgs.Handled property to true for desired bar item links. This will prohibit these links from being painted automatically.
• Call required Draw… methods to force related link elements to be painted in the way they would be painted automatically. For instance, the BarItemCustomDrawEventArgs.DrawGlyph method will paint the link’s icon (the BarItemCustomDrawEventArgs.Glyph property) as it would normally be drawn. Do this for all elements that you do not want to paint on your own.
• Manually draw all remaining elements by using default painting methods provided by the Graphics object stored in the BarCustomDrawEventArgs.Graphics property.

Note that the CustomDrawItem event does not allow you to modify link properties - change its style, assign a new caption or icon. You can only use methods accessed through e.Cache and e.Graphics objects to draw lines and shapes or paint text with the specified appearance.

Example

The following code illustrates how to custom draw the last clicked item within a menu. The example suggests two possible options: use the item’s default “Pressed” appearance (left screenshot) or provide custom appearance settings (right screenshot).

C#

using System.Drawing;
using DevExpress.XtraBars;

namespace FlyoutExample {
    public partial class XtraForm1 : DevExpress.XtraEditors.XtraForm {

        BarButtonItem lastClickedButton;

        public XtraForm1()
        {
            InitializeComponent();
            barManager1.CustomDrawItem += barManager1_CustomDrawItem;
            barButtonItem1.ItemClick += BarButtonItem1_ItemClick;
            barButtonItem2.ItemClick += BarButtonItem2_ItemClick;
            barButtonItem3.ItemClick += BarButtonItem3_ItemClick;
        }

        private void BarButtonItem1_ItemClick(object sender, DevExpress.XtraBars.ItemClickEventArgs e)
        {
            //...
            lastClickedButton = e.Item as BarButtonItem;
        }

        private void BarButtonItem2_ItemClick(object sender, DevExpress.XtraBars.ItemClickEventArgs e)
        {
            //...
            lastClickedButton = e.Item as BarButtonItem;
        }

        private void BarButtonItem3_ItemClick(object sender, DevExpress.XtraBars.ItemClickEventArgs e)
        {
            //...
            lastClickedButton = e.Item as BarButtonItem;
        }

        private void barManager1_CustomDrawItem(object sender, DevExpress.XtraBars.BarItemCustomDrawEventArgs e)
        {
            if (e.LinkInfo != null && e.LinkInfo.Link.Item == lastClickedButton)
            {
                //apply the default "Pressed" appearance
                e.LinkInfo.LinkState = DevExpress.XtraBars.ViewInfo.BarLinkState.Pressed;
                // or
                //custom draw last pressed buttons
                e.Cache.FillRectangle(Brushes.DarkOrange, e.Bounds);
                e.DrawArrow();
                e.DrawBorder();
                e.DrawCheckBox();
                e.DrawGlyph();
                e.DrawText();
                e.Handled = true;
            }
        }
    }
}

VB.NET

Imports System.Drawing
Imports DevExpress.XtraBars

Namespace FlyoutExample
    Partial Public Class XtraForm1
        Inherits DevExpress.XtraEditors.XtraForm

        Private lastClickedButton As BarButtonItem

        Public Sub New()
            InitializeComponent()
            AddHandler barManager1.CustomDrawItem, AddressOf barManager1_CustomDrawItem
            AddHandler barButtonItem1.ItemClick, AddressOf BarButtonItem1_ItemClick
            AddHandler barButtonItem2.ItemClick, AddressOf BarButtonItem2_ItemClick
            AddHandler barButtonItem3.ItemClick, AddressOf BarButtonItem3_ItemClick
        End Sub

        Private Sub BarButtonItem1_ItemClick(ByVal sender As Object, ByVal e As DevExpress.XtraBars.ItemClickEventArgs)
            '...
            lastClickedButton = TryCast(e.Item, BarButtonItem)
        End Sub

        Private Sub BarButtonItem2_ItemClick(ByVal sender As Object, ByVal e As DevExpress.XtraBars.ItemClickEventArgs)
            '...
            lastClickedButton = TryCast(e.Item, BarButtonItem)
        End Sub

        Private Sub BarButtonItem3_ItemClick(ByVal sender As Object, ByVal e As DevExpress.XtraBars.ItemClickEventArgs)
            '...
            lastClickedButton = TryCast(e.Item, BarButtonItem)
        End Sub

        Private Sub barManager1_CustomDrawItem(ByVal sender As Object, ByVal e As DevExpress.XtraBars.BarItemCustomDrawEventArgs)
            If e.LinkInfo IsNot Nothing AndAlso e.LinkInfo.Link.Item Is lastClickedButton Then
                'apply the default "Pressed" appearance
                e.LinkInfo.LinkState = DevExpress.XtraBars.ViewInfo.BarLinkState.Pressed
                ' or
                'custom draw last pressed buttons
                e.Cache.FillRectangle(Brushes.DarkOrange, e.Bounds)
                e.DrawArrow()
                e.DrawBorder()
                e.DrawCheckBox()
                e.DrawGlyph()
                e.DrawText()
                e.Handled = True
            End If
        End Sub
    End Class
End Namespace