The What, Why, and How of Layers

The Layers feature has been around since ActiveReports version 9, but maybe you haven't really checked it out yet. It is a feature that is exclusive to ActiveReports, and revolutionizes a number of scenarios, so I thought I'd share some of these with you.

What?

Layers are lockable sets of controls that you can overlay with other lockable sets of controls on a single Page or RDL report for different purposes. You can only work on the currently selected layer--controls on other layers are not editable. Every Page and RDL report has a default layer. This is the only layer that cannot be deleted, so remember to avoid putting conditional content on the default layer. Layers Window and Properties Window Each layer has several properties that you can set at design time in the Layers window, or in the Properties window when you select the layer.

Property

Description

DesignerLock
(Lock checkbox)

Locks all of the controls on the selected layer at design time to prevent accidental changes. Note that this has no effect at run time.

DesignerTransparency

Lets you set the transparency percentage for the selected layer where 1 is 100% transparent, .5 is 50% transparent, and 0 is not transparent. This is handy when you want to see where controls are located on other layers while working on a new layer, but don't want to confuse them with controls on the selected layer. This property has no effect at run time.

DesignerVisible (Visibility checkbox)

Toggles the visibility of the selected layer at design time. This lets you toggle layers to see what controls are on each layer. Note that this does not affect the visibility of the layer at run time.

Name

Sets the name of the selected layer as it appears in the list. Each layer name must be unique within the report's LayerCollection.

TargetDevice

Lets you specify whether the selected layer is visible in different types of report output. Select (or multi-select) from: None, Screen, Paper, Export, and All. This is the only one of these properties that affects the layer at run time.

There are also buttons for several actions that you can perform on the selected layer in the Layers window.

Button

Description

Add

Adds a new layer to the bottom of the list.

Delete

Deletes the selected layer.

Bring to front

Puts the selected layer in front of all other layers. Keep in mind that if you have any opaque background colors in controls on this layer, they will hide controls behind them.

Send to back

Puts the selected layer behind all other layers. If you have any background colors in controls on those layers, they will hide controls in this layer.

You can do more with layers at run time using the LayerCollection class in the API.

Why?

There are a number of scenarios in which report layers come in handy. Here are some examples. [gallery columns="2" ids="661615,661614,661616,661617"]

  • Printing on a pre-printed form: Scan the form and insert it as an image on a layer as in the images above so that you can easily align controls with printable areas. You can delete the layer once you're finished designing the report, or set the TargetDevice to None or Screen.
  • Showing different output by device: Set the TargetDevice property of each layer to control where it displays. For example, you could add a logo and company address for reports shown in a viewer or exported, and remove it for reports printed on letterhead paper.
  • Separating design and data: Using layers, you can easily keep all of your design controls, such as lines, images, and static text, on one layer, and add data bound controls on another layer.
  • Designing complex reports: You can place controls that are close together on different layers to avoid accidentally moving or resizing the ones you've already finished designing. (Snap lines still allow you to align to controls on other layers.)

How?

You can check out some of the uses of layers in our product samples. Read more about the Layer sample and how to find it in our User Guide: Layer Sample There are also a number of topics in the User Guide that go into more detail about how to use them:

Those don't cover how to use it in code, so I'll add that here. This example renders a layer, Layer 1, only on Wednesdays. We'll just pretend that I took the time to add a very fancy Happy Wednesday coupon to Layer 1 in my Page report.


private void button1_Click(object sender, EventArgs e)  
{  
    string file_name = @"..\\..\\PageReport1.rdlx";  
    GrapeCity.ActiveReports.PageReport pageReport = new GrapeCity.ActiveReports.PageReport(new System.IO.FileInfo(file_name));  
    GrapeCity.ActiveReports.Document.PageDocument pageDocument = new GrapeCity.ActiveReports.Document.PageDocument(pageReport);  
    if (DateTime.Today.DayOfWeek == DayOfWeek.Wednesday)  
    {  
        pageReport.Report.Layers[1].TargetDevice = TargetDevices.Paper;  
    }  
    else  
        pageReport.Report.Layers[1].TargetDevice = TargetDevices.None;  
    pageDocument.Print(true, true, false);  
}


Private Sub Button1_Click(sender As Object, e As EventArgs) Handles Button1.Click  
    Dim file_name As String = "..\\..\\PageReport1.rdlx"  
    Dim pageReport As New GrapeCity.ActiveReports.PageReport(New System.IO.FileInfo(file_name))  
    Dim pageDocument As New GrapeCity.ActiveReports.Document.PageDocument(pageReport)  
    If DateTime.Today.DayOfWeek = DayOfWeek.Wednesday Then  
        pageReport.Report.Layers(1).TargetDevice = TargetDevices.Paper  
    Else  
        pageReport.Report.Layers(1).TargetDevice = TargetDevices.None  
    End If  
    pageDocument.Print(True, True, False)  
End Sub

I know that our endlessly creative ActiveReports users will come up with much better real-world use cases for this API. Please share yours in the comments. We love to see how you use our features!

MESCIUS inc.

comments powered by Disqus