The requested page is not available for the requested platform. You are viewing the content for Default platform.

XRLabel Class

A Label control.

Namespace: DevExpress.XtraReports.UI

Assembly: DevExpress.XtraReports.v19.1.dll

Declaration

[DefaultBindableProperty("Text")]
public class XRLabel :
    XRFieldEmbeddableControl,
    IEditOptionsContainer
<DefaultBindableProperty("Text")>
Public Class XRLabel
    Inherits XRFieldEmbeddableControl
    Implements IEditOptionsContainer

Remarks

Drag the XRLabel item from the DX:19.1: Report Controls Toolbox tab onto your report to add a Label control to it.

report-control-label-0

Use the XRControl.Text property to specify the label text. Double-click the label to invoke its in-place editor and type the desired text. Press CTRL+Enter to submit text changes and exit the label's in-place edit mode.

xrlabel-inplace-editor

You can use markup in a label caption to change the text appearance. Set the label's AllowMarkupText property to true to enable this behavior. Refer to AllowMarkupText for more information.

Adjust the Label Size and Static Content

You can change label size at design time to fit its static text (XRControl.Text). Right-click the label and select the Fit Bounds To Text command in the context menu:

  • If the XRControl.WordWrap option is enabled, the command displays control content on multiple lines. It reduces control height and adjusts the width to fit its content.

    vs-rd-label-control-fit-bounds-to-text\

  • If the XRControl.WordWrap option is disabled and the control's content is partially visible, the command adjusts the control size to display this content.

    vs-rd-label-control-fit-bounds-to-text-word-wrap-disabled

The command's effect also depends on the control's XRControl.TextAlignment and XRControl.RightToLeft settings.

Use the Fit Text To Bounds option to adjust the control's font size to fit its area. The XRControl.WordWrap option defines whether the text will display on multiple lines or a single line.

vs-rd-label-control-fit-text-to-bounds

These commands are not available in the following cases:

You can also use the BestSizeEstimator class methods to adjust label size at runtime.

Bind Labels to Data

You can bind the label's Text property to a data field from a report's data source. Click the control's smart tag, expand the Expression drop-down list and select the data field.

report-control-label-3

You can click the ellipsis button in the Expression field. This invokes the Expression Editor in which you can construct a complex expression that involves two or more data fields.

report-control-label-3

Refer to Bind Report Controls to Data (Expression Bindings) for more information.

You can use label controls to create summaries. See the Calculate a Summary topic for more information.

The XRLabel.CanGrow and XRLabel.CanShrink properties allow you to increase or decrease the control's height to display all contents in Print Preview mode.

CanGrow = true CanGrow = false
cangrow-true cangrow-false
CanShrink = true CanShrink = false
canshrink-true canshrink-false

The XRLabel.AutoWidth property specifies whether or not to adjust a data-bound label's width to its content.

You can also use the XRLabel.TextFitMode property to adjust a control's font size to fit its boundaries in Print Preview mode.

TextFitMode = None TextFitMode = GrowOnly TextFitMode = ShrinkOnly TextFitMode = ShrinkAndGrow
label-text-fit-mode-none label-text-fit-mode-grow-only label-text-fit-mode-shrink-only label-text-fit-mode-shrink-and-grow

See the Arrange Dynamic Report Contents topic for more information.

To adjust dynamic data to fit within a control at runtime, use the BestSizeEstimator class methods.

Interactivity

Set the EditOptions.Enabled option to true to enable users to edit a label's content in Print Preview mode.

editing-fields-label-edit-options-new

Click the label in a previewed document to invoke the editor.

EditOptions_StandardMemoEditor

Use the label's XRLabel.InteractiveSorting option to enable users to click the label and sort report data in Print Preview mode. Set the SortingOptions.TargetBand property to the Group Header or Detail band, and the SortingOptions.FieldName property to the data field.

interactive-sorting-header

Refer to Sort a Report in Print Preview for a step-by-step tutorial.

Examples

The code sample below illustrates how to create an XRLabel object and bind it to data. You should bind your report to the Northwind database's Products table for this example to work properly.

To learn about the events available for a report and its controls, see Report Events.

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

public partial class XtraReport1 : XtraReport {

    public XRLabel CreateXRLabel() {
        // Create a new label object.
        XRLabel label = new XRLabel();

        // Bind the label to the UnitPrice data field. 
        // Change the label's foreground color depending on the UnitPrice data field value.
        label.ExpressionBindings.AddRange(new ExpressionBinding[] {
        new ExpressionBinding("BeforePrint", "Text", "[UnitPrice]"),
        new ExpressionBinding("BeforePrint", "ForeColor", "Iif([UnitPrice]>20, \'Red\', \'Green\')")});

        // Apply a currency format to the label's text.
        label.TextFormatString = "{0:c2}";

        // Automatically adjust the label's width to its content.
        label.AutoWidth = true;

        // Align the label's text to the bottom right corner.
        label.TextAlignment = TextAlignment.BottomRight;

        return label;
    }

    public XtraReport1() {
        // ...
        // Add the label to the report's Detail band.
        XRLabel label = CreateXRLabel();
        this.Detail.Controls.Add(label);
    }
}

Implements

DevExpress.XtraPrinting.IBrickOwner
DevExpress.Utils.Serializing.Helpers.IXtraSupportDeserializeCollectionItem
DevExpress.Utils.Serializing.IXtraSerializable
See Also