本指南提供了一个创建 自定义控件 (进度条) 的示例，并提供了如何在 XtraReport 中使用该控件的操作指令。要查看总说明，请参阅创建自定义控件。

要创建一个进度条控件，则执行下列操作。

创建进度条控件
把进度条控件添加到报表
查看运行结果

创建进度条控件

在本例中，以可变宽度的填充矩形来实现进度条控件，并作为数值的图形表示。这个自定义控件有两个主要的属性 —— Position 和 MaxValue。 Position 属性为该控件经过的取值确定当前进度 (使用进度颜色填充多长的条)。 MaxValue 属性确定 Position 属性的最大值，因此它确定了进度条所使用的刻度。注意，Position 属性是可以被绑定的，允许进度条控件被用于 data-aware(数据感知) 报表。

要创建一个进度条控件，则执行下列操作。

为了新建一个类库项目，运行 MS Visual Studio (2005、2008 或 2010)，选择 "File | New | Project..." 菜单项。然后在 New Project(新建项目) 对话框中，选择 "Class Library(类库)" 模板，为新项目键入 "CustomControls" 名称，并单击 OK 按钮。
把新添加的类由 Class1 重命名为 ProgressBar。
把 System.Drawing、DevExpress.Data.v10.2、DevExpress.Utils.v10.2、DevExpress.XtraPrinting.v10.2 和 DevExpress.XtraReports.v10.2 程序集添加到项目的“引用”列表中。

下面的代码展示了 ProgressBar 类如何从 XRControl 基本类继承，增加了 Position 和 MaxValue 属性，并重写了 XRControl 基本类的少量受保护的方法，从而为进度条控件实现所有必需的功能。

C#	复制代码
using System.Drawing; using System.ComponentModel; using DevExpress.XtraPrinting; using DevExpress.XtraReports; using DevExpress.XtraReports.UI; // ... namespace CustomControls { // The DefaultBindableProperty attribute is intended to make the Position // property bindable when an item is dropped from the Field List. [ ToolboxItem(true), DefaultBindableProperty("Position") ] public class ProgressBar : XRControl { // The current position value. private float pos = 0; // The maximum value for the progress bar position. private float maxVal = 100; public ProgressBar() { this.ForeColor = SystemColors.Highlight; } // Define the MaxValue property. [DefaultValue(100)] public float MaxValue { get { return this.maxVal; } set { if (value <= 0) return; this.maxVal = value; } } // Define the Position property. [DefaultValue(0), Bindable(true)] public float Position { get { return this.pos; } set { if (value < 0 \|\| value > maxVal) return; this.pos = value; } } // Override the XRControl.CreateBrick method. protected override VisualBrick CreateBrick(VisualBrick[] childrenBricks) { // Use this code to make the progress bar control // always represented as a Panel brick. return new PanelBrick(this); } // Override the XRControl.PutStateToBrick method. protected override void PutStateToBrick(VisualBrick brick, PrintingSystemBase ps) { // Call the PutStateToBrick method of the base class. base.PutStateToBrick(brick, ps); // Get the Panel brick which represents the current progress bar control. PanelBrick panel = (PanelBrick)brick; // Create a new VisualBrick to be inserted into the panel brick. VisualBrick progressBar = new VisualBrick(this); // Hide borders. progressBar.Sides = BorderSide.None; // Set the foreground color to fill the completed area of a progress bar. progressBar.BackColor = panel.Style.ForeColor; // Calculate the rectangle to be filled by the foreground color. progressBar.Rect = new RectangleF(0, 0, panel.Rect.Width * (Position / MaxValue), panel.Rect.Height); // Add the VisualBrick to the panel. panel.Bricks.Add(progressBar); } } }

复制代码

using System.Drawing;
using System.ComponentModel;
using DevExpress.XtraPrinting;
using DevExpress.XtraReports;
using DevExpress.XtraReports.UI;
// ...

namespace CustomControls {
    // The DefaultBindableProperty attribute is intended to make the Position 
    // property bindable when an item is dropped from the Field List.
    [
    ToolboxItem(true),
    DefaultBindableProperty("Position")
    ]
    public class ProgressBar : XRControl {

        // The current position value.
        private float pos = 0;

        // The maximum value for the progress bar position.
        private float maxVal = 100;

        public ProgressBar() {
            this.ForeColor = SystemColors.Highlight;
        }

        // Define the MaxValue property.
        [DefaultValue(100)]
        public float MaxValue {
            get { return this.maxVal; }
            set {
                if (value <= 0) return;
                this.maxVal = value;
            }
        }

        // Define the Position property. 
        [DefaultValue(0), Bindable(true)]
        public float Position {
            get { return this.pos; }
            set {
                 if (value < 0 || value > maxVal) return;
                this.pos = value;
            }
        }

        // Override the XRControl.CreateBrick method.
        protected override VisualBrick CreateBrick(VisualBrick[] childrenBricks) {
            // Use this code to make the progress bar control 
            // always represented as a Panel brick.
            return new PanelBrick(this);
        }

        // Override the XRControl.PutStateToBrick method.
        protected override void PutStateToBrick(VisualBrick brick, PrintingSystemBase ps) {
            // Call the PutStateToBrick method of the base class.
            base.PutStateToBrick(brick, ps);

            // Get the Panel brick which represents the current progress bar control.
            PanelBrick panel = (PanelBrick)brick;

            // Create a new VisualBrick to be inserted into the panel brick.
            VisualBrick progressBar = new VisualBrick(this);

            // Hide borders.
            progressBar.Sides = BorderSide.None;

            // Set the foreground color to fill the completed area of a progress bar.
            progressBar.BackColor = panel.Style.ForeColor;

            // Calculate the rectangle to be filled by the foreground color.
            progressBar.Rect = new RectangleF(0, 0, panel.Rect.Width * (Position / MaxValue), 
                panel.Rect.Height);

            // Add the VisualBrick to the panel.
            panel.Bricks.Add(progressBar);
        }
    }
}

Visual Basic	复制代码
Imports System.Drawing Imports System.ComponentModel Imports DevExpress.XtraPrinting Imports DevExpress.XtraReports Imports DevExpress.XtraReports.UI ' ... Namespace CustomControls ' The DefaultBindableProperty attribute is intended to make the Position ' property bindable when an item is dropped from the Field List. <ToolboxItem(True), _ DefaultBindableProperty("Position")> _ Public Class ProgressBar Inherits XRControl ' The current position value. Private pos As Single = 0 ' The maximum value for the progress bar position. Private maxVal As Single = 100 Public Sub New() Me.ForeColor = SystemColors.Highlight End Sub ' Define the MaxValue property. <DefaultValue(100)> _ Public Property MaxValue() As Single Get Return Me.maxVal End Get Set(ByVal value As Single) If value <= 0 Then Return End If Me.maxVal = value End Set End Property ' Define the Position property. <DefaultValue(0), Bindable(True)> _ Public Property Position() As Single Get Return Me.pos End Get Set(ByVal value As Single) If value < 0 Or value > maxVal Then Return End If Me.pos = Value End Set End Property ' Override the XRControl.CreateBrick method. Protected Overrides Function CreateBrick( _ ByVal childrenBricks As VisualBrick()) As VisualBrick ' Use this code to make the progress bar control ' always represented as a Panel brick. Return New PanelBrick(Me) End Function ' Override the XRControl.PutStateToBrick method. Protected Overrides Sub PutStateToBrick(ByVal brick As VisualBrick, _ ByVal ps As PrintingSystemBase) ' Call the PutStateToBrick method of the base class. MyBase.PutStateToBrick(brick, ps) ' Get the Panel brick which represents the current progress bar control. Dim panel As PanelBrick = CType(brick, PanelBrick) ' Create a new VisualBrick to be inserted into the panel brick. Dim myProgressBar As VisualBrick = New VisualBrick(Me) ' Hide borders. myProgressBar.Sides = BorderSide.None ' Set the foreground color to fill the completed area of a progress bar. myProgressBar.BackColor = panel.Style.ForeColor ' Calculate the rectangle to be filled by the foreground color. myProgressBar.Rect = New RectangleF(0, 0, panel.Rect.Width * (Position / MaxValue), _ panel.Rect.Height) ' Add the VisualBrick to the panel. panel.Bricks.Add(myProgressBar) End Sub End Class End Namespace

Visual Basic

复制代码

Imports System.Drawing
Imports System.ComponentModel
Imports DevExpress.XtraPrinting
Imports DevExpress.XtraReports
Imports DevExpress.XtraReports.UI
' ...

Namespace CustomControls
    ' The DefaultBindableProperty attribute is intended to make the Position 
    ' property bindable when an item is dropped from the Field List.
    <ToolboxItem(True), _
    DefaultBindableProperty("Position")> _
    Public Class ProgressBar
        Inherits XRControl

        ' The current position value.
        Private pos As Single = 0

        ' The maximum value for the progress bar position.
        Private maxVal As Single = 100

        Public Sub New()
            Me.ForeColor = SystemColors.Highlight
        End Sub

        ' Define the MaxValue property.
        <DefaultValue(100)> _
        Public Property MaxValue() As Single
            Get
                Return Me.maxVal
            End Get
            Set(ByVal value As Single)
                If value <= 0 Then
                    Return
                End If
                Me.maxVal = value
            End Set
        End Property

        ' Define the Position property. 
        <DefaultValue(0), Bindable(True)> _
        Public Property Position() As Single
            Get
                Return Me.pos
            End Get
            Set(ByVal value As Single)
                If value < 0 Or value > maxVal Then
                    Return
                End If
                Me.pos = Value
            End Set
        End Property

        ' Override the XRControl.CreateBrick method.
        Protected Overrides Function CreateBrick( _ 
        ByVal childrenBricks As VisualBrick()) As VisualBrick
            ' Use this code to make the progress bar control 
            ' always represented as a Panel brick.
            Return New PanelBrick(Me)
        End Function

        ' Override the XRControl.PutStateToBrick method.
        Protected Overrides Sub PutStateToBrick(ByVal brick As VisualBrick, _ 
        ByVal ps As PrintingSystemBase)
            ' Call the PutStateToBrick method of the base class.
            MyBase.PutStateToBrick(brick, ps)

            ' Get the Panel brick which represents the current progress bar control.
            Dim panel As PanelBrick = CType(brick, PanelBrick)

            ' Create a new VisualBrick to be inserted into the panel brick.
            Dim myProgressBar As VisualBrick = New VisualBrick(Me)

            ' Hide borders.
            myProgressBar.Sides = BorderSide.None

            ' Set the foreground color to fill the completed area of a progress bar.
            myProgressBar.BackColor = panel.Style.ForeColor

            ' Calculate the rectangle to be filled by the foreground color.
            myProgressBar.Rect = New RectangleF(0, 0, panel.Rect.Width * (Position / MaxValue), _
                panel.Rect.Height)

            ' Add the VisualBrick to the panel.
            panel.Bricks.Add(myProgressBar)
        End Sub
    End Class
End Namespace

另外，还可以定义一个自定义图标，从而在工具箱和 Report Explorer(报表资源管理器) 窗口中表示进度条控件。为此，需要创建一个自定义的位图文件 (16x16 像素)，并把它添加到项目中。

注意，在把图像文件添加到项目中时，请确定其名称与类名称相匹配，并且把 生成操作(Build Action) 属性值设置为 嵌入的资源(Embedded Resource)。

然后使用下列代码来把此图像指定为进度条控件的图标。

C#	复制代码
// ... [ ToolboxItem(true), DefaultBindableProperty("Position"), ToolboxBitmap(typeof(ProgressBar)) // <-- Add this line ] public class ProgressBar : XRControl { // ...

Visual Basic	复制代码
' ... <ToolboxItem(True), _ DefaultBindableProperty("Position"), _ ToolboxBitmap(GetType(ProgressBar))> _ Public Class ProgressBar ' ...

重新生成此项目。在生成解决方案之后，一个包含进度条控件的 CustomControls.dll 程序集文件将出现在项目的 \Bin\Debug 目录中。

把进度条控件添加到报表

下面的示例演示了进度条控件如何被用于现实应用程序。请按照下面的步骤操作。

新建一个 Windows Application (Visual Studio 2005) 或 Windows 窗体应用程序 (Visual Studio 2008)，或者打开一个已有的应用程序。
添加新空白报表到项目中。
把 ProgressBar 控件添加到 Visual Studio 工具箱中。为完成此任务，显示工具箱，展开 DX.10.2: Report Controls 标签页，使用鼠标右键单击工具箱，并选择 Choose items(选择项)...
在被调用的 Choose Toolbox Items(选择工具箱项) 对话框中，单击 Browse(浏览)... 按钮并指定 CustomControls.dll 程序集的文件路径。勾选 ProgressBar 控件并单击“确定”按钮。进度条控件将被添加到工具箱中。

注意
如果需要学习如何把自定义控件添加到最终用户设计器的工具箱中，那么请参阅如何：使自定义控件只能用于特定的报表实例。
在本例中，我们将创建一个报表，其中以 ProgressBar 控件呈现世界上 10 个陆地面积最大的国家。此数据被存储在 Top10_Area 数据视图中，此视图在 CountriesDB 数据库 (与 XtraReports 套件安装一起提供的 CountriesDB.mdb 文件，并且位于 DevExpress 演示的安装目录) 中。要学习更多关于如何把报表绑定到数据源的内容，请参阅如何：把报表绑定到 MDB 数据库
然后构造报表。例如，把一个 XRLabel 拖放到 PageHeaderBand(页眉) 带区，并把它的文本设置为 Top 10 Countries By Area:。再把两个标签添加到 DetailBand(细节) 带区，并把它们绑定到 Country 和 Area 数据字段。

最后，把 ProgressBar 控件添加到 Detail(细节) 带区。在属性窗口中展开它的 (DataBindings.Position.Binding) 属性，并把它设置为 Area 数据字段。然后把它的 MaxValue 属性设置为 17100、BackColor 属性设置为 LightBlue、ForeColor 属性设置为 Blue。

设计报表，如下图所示。

注意
如果需要学习如何把自定义控件添加到最终用户设计器的工具箱中，那么请参阅如何：使自定义控件只能用于特定的报表实例。

查看运行结果

Show Me
在 DevExpress Code Central 数据库中可以找到完整的示例项目，网址是 http://www.devexpress.com/example=E57。取决于目标平台类型 (ASP.NET、WinForms 等)，可以在线运行本示例，或者下载自动可执行的示例。