Controlling Displayed Precision via Parameters in Visual Report Designer
When creating a report template using Visual Report Designer, it is sometimes impossible to know what precision an end user may want to use to display a particular value. In these situations, you can use report parameters to allow the user to select the desired precision. While it is not difficult to do this, it does require a little bit of extra effort.
First, let’s establish our goal here: We are attempting to format a numeric value (decimal) with a fixed number of decimal places in the range of 0 to 6. For example, if we have the value 1.23456789, we might want to display it with 2 fixed decimal places, resulting in the text ‘1.23’.
To accomplish this, we need to understand a little about ‘Format Strings’. Visual Report Designer uses .NET format strings for formatting values…Microsoft has given us a good description of how to form both standard and custom format strings on the MSDN website. Typically, when you are creating a report in Visual Report Designer, you will simply be using the format string editor built in to the application user interface:
Selecting a value here will place a string (text) in the ‘Format String’ field of the Task Pane from which the dialog was launched:
This value may be copied and reused, however, the format string is static – i.e. we cannot change it as the report is running. To do this, we will need to take a different, less direct approach.
First, we’ll clear the format string above from our label properties as we do not want it to ‘stack’ on top of what we are about to do.
Next, we need to create the parameter which will be used to specify the desired precision. To do this, we right-click on the ‘Parameters’ collection at the bottom of the field list and select the ‘Add Parameter’ context menu command:
This will launch the ‘Add New Parameter’ dialog in which we will define our parameter:
As shown, we have configured the parameter called ‘Precision’ to be an integer, and we set the parameter so that the user must choose a value from the pre-defined, static list as shown. This prevents the user from entering a value that is out of the allowable range.
Next, we need to use an expression (via a calculated field) in order to actually construct and apply the format string. To do this, we right-click on the entity that contains the field we want to format and select the option to ‘Add Calculated Field’:
This creates a calculated field called ‘calculatedField1’ and sets the data binding so that this field will be able to access fields defined for the current entity type:
We can now right-click on this field and select ‘Edit Calculated Fields’:
This will bring up the ‘Calculated Field Collection Editor’:
Here we can rename the field, change the field type, define an expression, etc. First, let’s rename this field to ‘FormattedLength’, then define an expression to perform the actual formatting operation (click in the expression field and then on the button that appears to access the ‘Expression Editor’.
For our current purposes, we will be able to use a simple format string for ‘Fixed Decimal’. For 2 fixed decimal places, the format string would be ‘F2’; for 5, it would be ‘F5’. This pattern is advantageous in that we already have a numeric (integer) parameter that holds the precision value…all we need to do is append an ‘F’ in front of the parameter value to get the desired format string. The other portion of the expression that we will be adding is the part that actually retrieves the desired source value and then applies the format string – we do this using the ‘_FormattedValue’ function:
Double click on this function to insert it into the expression editor box.
To reference the value source field, we set the cursor in the proper position (immediately after the ‘(‘ character in the ‘_FormattedValue’ function call) in the expression editor, then select the ‘Fields’ category and double-click on the desired field:
After setting the value source, we next have to assemble the format string. We start by positioning the cursor immediately after the first single quote character following the ‘,’ in the ‘_FormattedValue’ function call. We then add the single character ‘F’. Next, we use the arrow keys or the mouse to relocate the cursor to the right of the second single quote character now encompassing the ‘F’…we can add a space if we like, and then a ‘+’ character (no quotes). We can optionally add another space and then the parameter reference. To reference the parameter, we select the ‘Parameters’ category and double click on the desired parameter (with the cursor in the correct position in the editor of course…).
The end result should look similar to this:
From here, we close the commit the changes and close the editor. We then must set the proper binding on our label in our report so that it calls the calculated field instead of the ‘Length’ field the label was previously bound to:
We can now test our results. In your DWG, make sure you have an entity to test against…in this case any polyline with at least a few segments…then ‘preview’ your report. In the ‘Report Parameters’ tab of the ‘Edit Queries’ dialog, you will see the parameter which controls precision…set this to the desired value and click the ‘OK’ button…
The results in the generated report document will look similar to this:
If we repeat with a different setting for the parameter, we will see the results change accordingly: