ControlsFactory Class

A factory that enables you to register custom controls.

Declaration

export class ControlsFactory extends AnalyticControlsFactory<DevExpress.Reporting.Designer.Internal.ControlType> implements IDisposable

Remarks

Review the following help topic for information on how to add a custom control: Register a Custom Control in the Report Designer Toolbox.

Implements

IDisposable

Methods

createPopularBindingInfo(options) Method

Creates a new object that stores information required to display element properties in the list of popular actions.

Declaration

createPopularBindingInfo(
    options: DevExpress.Reporting.Designer.Controls.Metadata.ISerializationInfoWithBindings,
    isExpression?: boolean
): DevExpress.Reporting.Designer.Controls.Metadata.ISerializationInfoWithBindings

Parameters

Name	Type	Description
options	ISerializationInfoWithBindings	An object that stores information required to serialize element properties.
isExpression	boolean	true (the default value) to create an expression binding; false to create a legacy data binding.

Returns

Type	Description
ISerializationInfoWithBindings	An object that specifies the resulting serialization info.

Remarks

In the CustomizeToolbox event handler, use the createPopularBindingInfo method to create serialization information for a custom control’s properties.

Then, add the created information to the custom control’s info collection and the corresponding binding names to the popularProperties collection as shown below.

function customizeToolbox(s, e) {
  // ...
  var controlsFactory = e.ControlsFactory;
  var expressionInfo = controlsFactory.createPopularBindingInfo({ bindingName: "BindableProperty", displayName: "Bindable Property", localizationId: "BindableProperty" }, true)
  var dataBindingInfo = controlsFactory.createPopularBindingInfo({ bindingName: "BindableProperty", displayName: "Bindable Property", localizationId: "BindableProperty" }, false)

  // Create an object containing info about a custom label toolbox item.
  var customLabelInfo = controlsFactory.inheritControl("XRLabel", {
    defaultVal: {
      "@ControlType": fullTypeName,
      "@SizeF": "100,23"
    },
    toolboxIndex: 1,
    info: [expressionInfo, dataBindingInfo],
    popularProperties: ["popularExpression", "popularDataBinding"],
  });
  // ...
}

hideExpressionBindings(type, propertyNames) Method

Hides the specified properties for the specified control from the Properties panel’s Expressions tab.

Declaration

hideExpressionBindings(
    type: DevExpress.Reporting.Designer.Internal.ControlType,
    ...propertyNames: string[]
): void

Parameters

Name	Type	Description
type	string
propertyNames	string[]	An array of strings that specify property names to hide.

Remarks

Handle the CustomizeToolbox event and use the following code to hide the Label control’s specific properties from the Expressions tab.

ASPX

<script type="text/javascript">
    function customizeToolbox(s, e) {
        e.ControlsFactory.hideExpressionBindings("XRLabel", "Font", "ForeColor", "Text", "TextAlignment");
    }
</script>

<dx:ASPxReportDesigner ID="ASPxReportDesigner1" ClientInstanceName="reportDesigner" runat="server">
    <ClientSideEvents CustomizeToolbox="customizeToolbox" />
</dx:ASPxReportDesigner>

inheritControl(parentType, extendedOptions) Method

Inherits a new control from the specified parent control and extends it with the specified options.

Declaration

inheritControl(
    parentType: DevExpress.Reporting.Designer.Internal.ControlType,
    extendedOptions: DevExpress.Analytics.Elements.IElementMetadata
): DevExpress.Analytics.Elements.IElementMetadata

Parameters

Name	Type	Description
parentType	string
extendedOptions	IElementMetadata	An object that specifies options for a new control.

Returns

Type
IElementMetadata

Remarks

The inheritControl method allows you to derive a new custom control from an existing one. Pass the parent control’s type as the first method parameter and the required control options as the second method parameter. Note that the info and popularProperties options are concatenated with the parent control’s corresponding options, while all other options replace the parent options.

The following code snippet demonstrates how to create a new custom control in the CustomizeToolbox event handler.

function customizeToolbox(s, e) {
  ...
  // Create an object containing info about a custom label toolbox item.
  var customLabelInfo = controlsFactory.inheritControl("XRLabel", {
    surfaceType: CustomLabelSurface,
    defaultVal: {
      "@ControlType": fullTypeName,
      "@SizeF": "100,23"
    },
    toolboxIndex: 1,
    info: [somePropertySerializationInfo, bindablePropertySerializationInfo],
    popularProperties: ["someProperty", "bindableProperty"],
  });
  ...
}

Use the registerControl method to register a custom control in the Toolbox.

See Register a Custom Control in the Report Designer Toolbox for a step-by-step tutorial on how to add a custom control.

registerControl(typeName, metadata) Method

Registers the specified control in the Toolbox of the Web Report Designer.

Declaration

registerControl(
    typeName: DevExpress.Reporting.Designer.Internal.ControlType,
    metadata: DevExpress.Reporting.Designer.Controls.IReportControlMetadata
): void

Parameters

Name	Type	Description
typeName	string
metadata	IReportControlMetadata	An object that provides information about a toolbox item.

Remarks

For a step-by-step tutorial on how to add a custom control, see Register a Custom Control in the Report Designer Toolbox.

setDisplayNameForExpression(propertyName, localizationId, displayName) Method

Specifies a property’s display name in the End-User Report Designer Expressions tab.

Declaration

setDisplayNameForExpression(
    propertyName: string,
    localizationId: string,
    displayName: string
): void

Parameters

Name	Type	Description
propertyName	string	A string that specifies the property name.
localizationId	string	A string that specifies the ASPxReportsStringId enumeration member.
displayName	string	A string that specifies display text.

Remarks

To display a specific string, specify it in the displayName parameter value and set the localizationId parameter to null.

Note

The localizationId parameter has priority over the displayName parameter.

Example

The following code snippet creates a new category for the Label control and adds the TextFormatString property with the “Text Format String” display name. The panel width is set to 350px to fit the display name:

Designer.cshtml

<head>
    <style>
        .dxrd-right-panel.ui-resizable {
            width: 350px !important;
        }
    </style>
</head>
<script type="text/javascript">
    function CustomizeExpressions(s, e) {
        e.ControlsFactory.setExpressionBinding("XRLabel", "TextFormatString", ["BeforePrint"], "My category");
        e.ControlsFactory.setDisplayNameForExpression("TextFormatString", null, "Text Format String");
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.CustomizeToolbox = "CustomizeExpressions";
}).BindToUrl("TestReport").GetHtml()

To serialize the added property, you should also register it at application startup:

Global.asax.cs

using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.UI;

void Application_Start(object sender, EventArgs e) {
  // ...
  ExpressionBindingDescription description = new ExpressionBindingDescription(new string[] { "BeforePrint" }, 0, new string[0], "My category");
  ExpressionBindingDescriptor.SetPropertyDescription(typeof(XRLabel), "TextFormatString", description);
    // ...
}

The following image shows the result.

setExpressionBinding(controlType, propertyName, events) Method

Adds a new property for the specified control to the End-User Report Designer’s Expressions tab.

Declaration

setExpressionBinding(
    controlType: DevExpress.Reporting.Designer.Internal.ControlType,
    propertyName: string,
    events: string[],
    group?: string,
    objectProperties?: string[]
): void

Parameters

Name	Type	Description
controlType	string
propertyName	string	A string that specifies the property name to add.
events	string[]	An array of strings that specify events in which the property should be available.
group	string	A string that specifies the category in which the property should be displayed.
objectProperties	string[]	An array of strings that specify the property’s inner properties.

Remarks

Handle the CustomizeToolbox event and use the setExpressionBinding method to add new properties to the End-User Report Designer’s Expressions tab.

Example

Designer.cshtml

<head>
    <style>
        .dxrd-right-panel.ui-resizable {
            width: 350px !important;
        }
    </style>
</head>
<script type="text/javascript">
    function CustomizeExpressions(s, e) {
        e.ControlsFactory.setExpressionBinding("XRLabel", "TextFormatString", ["BeforePrint"], "My category");
        e.ControlsFactory.setDisplayNameForExpression("TextFormatString", null, "Text Format String");
    }
</script>

@Html.DevExpress().ReportDesigner(settings =>
{
    settings.Name = "ReportDesigner1";
    settings.ClientSideEvents.CustomizeToolbox = "CustomizeExpressions";
}).BindToUrl("TestReport").GetHtml()

To serialize the added property, you should also register it at application startup:

Global.asax.cs

using DevExpress.XtraReports.Expressions;
using DevExpress.XtraReports.UI;

void Application_Start(object sender, EventArgs e) {
  // ...
  ExpressionBindingDescription description = new ExpressionBindingDescription(new string[] { "BeforePrint" }, 0, new string[0], "My category");
  ExpressionBindingDescriptor.SetPropertyDescription(typeof(XRLabel), "TextFormatString", description);
    // ...
}

The following image shows the result.