XRCharacterComb Class
A Character Comb control that displays text so that each character is printed in an individual cell.
Namespace: DevExpress.XtraReports.UI
Assembly: DevExpress.XtraReports.v24.1.dll
NuGet Package: DevExpress.Reporting.Core
Declaration
Remarks
The XRCharacterComb control displays text so that each character is printed in an individual cell.
To add this control to the report, drag the XRCharacterComb item from the DX:24.1: Report Controls Toolbox tab and drop it onto the report.
The number of cells displayed by the control in Print Preview depends on the CanShrink and AutoWidth settings.
- If both these properties are enabled, the number of cells corresponds to the number of characters in the control’s text.
- Otherwise, the number of cells corresponds to the specified cell size and the control size.
See the Content Layout and Position section to learn more on using these properties.
You can also adjust the character comb’s size to match its characters at design time by right-clicking the control and using the Fit Bounds To Text command in the context menu:
If the XRControl.WordWrap option is enabled, the command keeps control content displayed in multiple lines. It decreases the control’s height and adjusts the width to fit this content.
If the XRControl.WordWrap option is disabled, the command adjusts the control’s height and width to completely display the control’s content in a single line. As a result, the number of cells corresponds to the number of characters.
When exporting this control to third-party formats, consider the following
- When a report is exported to an XLS or XLSX file, the cells of the Character Comb correspond to the cells of a resulting Excel sheet.
- When a report is exported to a CSV (or TXT) file, the content of individual cells is separated (or spaced) by a specified TextExportOptionsBase.Separator character.
In most aspects, the Character Comb is similar to the XRLabel control from which it inherits most of its properties and its basic behavior. For general information about binding these controls to data and display summary function results, see the following topic: Label.
Main Options
The following properties are specific to the XRCharacterComb control.
XRCharacterComb.CellVerticalSpacing and XRCharacterComb.CellHorizontalSpacing
Specify the spacing between adjacent cells (measured in report units). These values do not depend on the specified border width of a control.
The following image illustrates a Character Comb with CellVerticalSpacing set to 15 and CellHorizontalSpacing set to 5.
The area between cells is painted using the background color of the control’s parent container (the control’s XRControl.BackColor property is ignored for this area). In the following image, the control is assigned a gray background color, and the report’s background color is white.
The
XRCharacterComb.Paddingproperty is hidden and has no effect upon the Character Comb control. When applying a style to a Character Comb, the style’s XRControlStyle.Padding property is ignored.-
Specifies the width of cell borders in pixels, as a floating point value.
When the cell spacing is set to zero, the borders of adjacent cells are merged (i.e., the actual border width is not doubled).
The following images illustrate how cell spacing affects the BorderWidth property behavior.
Cell Spacing = 0 Cell Spacing = 1 
When the control’s content is to be printed on multiple pages, a page break horizontally splits the cell border based on the cell spacing setting, as shown below.
Cell Spacing = 0 Cell Spacing > 0 
Note
The XRCharacterComb.BorderDashStyle property of the Character Comb control does not currently support the BorderDashStyle.Double setting.
-
Specifies whether or not the cell size should depend on the current font size of a control. The following cell size modes are supported.
-
The cell size is determined by the XRCharacterComb.CellHeight and XRCharacterComb.CellWidth property values and does not depend on the assigned font size.
With this setting, the actual cell size is less than the specified CellHeight and CellWidth by the XRControl.BorderWidth value.
-
The cell size depends on the current font size of a control (the XRCharacterComb.CellHeight and XRCharacterComb.CellWidth properties are ignored).
With this setting, the actual cell size does not depend on the specified border width of a control.
-
Only the cell height depends on the current font size of a control (the XRCharacterComb.CellHeight property is ignored), and the XRCharacterComb.CellWidth value is specified manually.
With this setting, the following behavior is expected.
- The actual cell height does not depend on the specified border width of a control.
- The actual cell width is the difference between the specified XRCharacterComb.CellWidth and XRControl.BorderWidth values.
-
Only the cell width depends on the current font size of a control (the XRCharacterComb.CellWidth property is ignored), and the XRCharacterComb.CellHeight value is specified manually.
With this setting, the following behavior is expected.
- The actual cell width does not depend on the specified border width of a control.
- The actual cell height is the difference between the specified XRCharacterComb.CellHeight and XRControl.BorderWidth values.
-
Content Layout and Position
This section describes the XRCharacterComb properties that affect the control’s position on a page and content layout.
The following image illustrates the behavior of the XRLabel.AutoWidth property that specifies whether or not the width of a control depends on its text.
| AutoWidth = true | AutoWidth = false |
|---|---|
 |
 |
The following image illustrates the behavior of the XRLabel.CanShrink property that specifies whether or not the height of a control depends on its text.
| CanShrink = true | CanShrink = false |
|---|---|
 |
|
The XRCharacterComb.TextAlignment property specifies the alignment of text within a control.
| TextAlignment = TopLeft | TextAlignment = MiddleCenter | TextAlignment = BottomRight |
|---|---|---|
 |
 |
 |
Example
This example illustrates how to create a Character Comb and specify its main options in code.
using DevExpress.XtraPrinting;
using DevExpress.XtraReports.UI;
// ...
public XRCharacterComb CreateCharacterComb() {
// Create a Character Comb instance.
XRCharacterComb characterComb = new XRCharacterComb();
// Make every cell have borders on each side.
characterComb.Borders = BorderSide.All;
// Specify the spacing between cells (measured in report units).
characterComb.CellHorizontalSpacing = 2;
characterComb.CellVerticalSpacing = 2;
// Make the cell height depend on the current font size,
// and the cell width having a fixed value (measured in report units).
characterComb.CellSizeMode = SizeMode.AutoHeight;
characterComb.CellWidth = 25;
// Adjust the control's dimensions to its content.
characterComb.AutoWidth = true;
characterComb.CanShrink = true;
// Set its Multiline property to true.
characterComb.Multiline = true;
// Set its static text. This property is bindable,
// meaning that this text can be supplied from a data source.
characterComb.Text = "Line1\r\nLine2";
return characterComb;
}