Working with Text Formulas

3 4

Modifying a shape's text formulas allows you to define sophisticated behavior for shapes in the solutions you develop. You can display the values from the formulas you enter, as well as format the values to better reflect the shape's role. This section outlines some of the more advanced approaches you can use when modifying a shape's text formulas, and it also provides information on protecting the formulas you create and testing your shapes to ensure that they behave as you intend.

Displaying and Formatting Formula Results

You can display the results of a formula and format the output appropriately. When you select the text block, and then click Field on the Insert menu, the text field created is really the value from the evaluated formula in a ShapeSheet cell converted to text. You can use the same techniques to develop custom text fields as those you use in the ShapeSheet window, and you can display the formatted results in the shape itself.

When you create a formula for a text field, the formula appears in the Text Fields section of the shape's ShapeSheet window. The formulas are displayed in the order they were inserted in the text, not necessarily the order in which they appear in the text.

Displaying a shape's width in different units

You can use text fields to show a shape's current width in inches, centimeters, points, or other units. To do this, you can use the formatex function to specify the units you want to display for the result.

The formatex function takes this syntax:

 FORMATEX(expression, "formatpicture" [,"inputunit"] [,"outputunit"]) 

This function returns the result of expression evaluated in inputunit as a string formatted according to formatpicture expressed in outputunit. The formatpicture is a code that indicates how the result should be formatted. If you specify the optional inputunit and outputunit, use a numerical value or a valid spelled-out or abbreviated unit of measure (in, in., inch, and so on). If you don't specify inputunit, the units of the expression are not converted. If you don't specify outputunit, the input unit is used.

To use the FORMATEX function to display the shape's width in a text field

1. Select a shape.
2. On the Insert menu, click Field.
3. In the Field dialog box, under Category, click Custom Formula.
4. In the Custom Formula box, enter an expression using the formatex function, specifying the desired format picture, and input and output units.

For example, if Width is in inches and you want to display it in centimeters, enter:

 = FORMATEX(Width,"0.00 u", "in.", "cm.") 

5. Click OK.

The Microsoft Visio engine formats the value of Width using two decimal places, abbreviates the units, and converts inches to centimeters. For example, if Width is 1.875 in., Visio displays 4.76 cm.

For details about valid format pictures, search the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Displaying normalized angular values

You can design a shape that displays the current angle of rotation as part of its text. For example, shapes representing lines of bearing on a nautical chart or slope indicators in a property line diagram display the current angle. By default, the Visio engine returns angular values from "180 to +180 degrees. You can use the ang360( ) function to convert the value of the shape's angle to a value from 0 to 360 degrees (or from 0 to 2pi radians), and then display the value in the shape.

To display the value of a normalized angle in a text field

1. Select a shape.
2. On the Insert menu, click Field.
3. In the Field dialog box, under Category, click Custom Formula.
4. In the Custom Formula box, enter:

 = ANG360(Angle) 

5. Under Format, click Degrees.
6. Click OK.

Formatting Strings and Text Output

When you display strings, such as formula results in a text field or custom property values, you can specify a format for the output. Text output can be formatted as a number-unit pair, string, date, time, duration, or currency. The Visio engine recognizes a set of format pictures that format the text as you want it to appear. For example, the format picture ["0 #/10 uu"] formats the number-unit pair 10.9cm as ["10 9/10 centimeters"] .

Format pictures appear in the list of formats when you use the Field command (on the Insert menu, click Field), as arguments to the FORMAT and FORMATEX functions, and as formulas you can use in the Format cell of the Custom Properties section of the ShapeSheet window. For details about all the format pictures that you can use, including date, time, duration, currency, and scientific notations, search for "format pictures" in the Microsoft Visio Developer Reference (on the Help menu, click Developer Reference).

Using the FORMAT function

In any formula that resolves to a string, including custom text field formulas, you can use the FORMAT function to format the output. The FORMAT function uses the following syntax:

 FORMAT(expression, "formatpicture") 

The result of expression is formatted according to the style specified by formatpicture. The function returns a string of the formatted output. The format picture must be compatible with the type of expression used, and you cannot mix expression types. For example, if you combine the formatting of a date and a number by using the number and date format pictures together ["#.## mmddyy"] , the Visio engine ignores the "mmddyy" portion and tries to evaluate the expression using the first part ["#.##"] of the format picture.

To use the format function in a text field, specify a custom formula as described in Displaying and Formatting Formula Results earlier in this section. In the Custom formula box, include the format function in your formula. (To enter a formula in the Custom formula box, open the shape's text block, click Field on the Insert menu, select Custom Formula under Category, and then type the formula in the Custom formula box.)

The following table provides examples for formatting common number-unit pairs.

Custom text formats for number-unit pairs

Syntax	Display output
FORMAT( 0ft. 11.53in., "0.## U")	0 FT. 11.53 IN.
FORMAT( 260.632 cm, "0.## u")	260.63 cm.
FORMAT( 0 ft. 11.53 in. , "# #/# u")	11 5/9 in.
FORMAT( 260.632 cm, "0 #/# uu")	260 5/8 centimeters
FORMAT( 260.632 cm, "0 #/5 uu")	260 3/5 centimeters
FORMAT( 0ft. 11.53in., "0.000 u")	0 ft. 11.530 in.

Displaying formatted custom properties

You can format the displayed value of a custom property so that it appears the way you want in the Custom Properties dialog box. To do this, you use a format picture in the Format cell in the Custom Properties section of the shape's ShapeSheet window. For example, a project timeline shape can have a custom property called Cost that measures the cost of a process. To format "1200" as currency, you can specify the following format picture in the Format cell of the shape's Custom Properties section:

 Format = "$###,###.00" 

The Visio engine uses the current Regional Options settings in Control Panel to determine the currency symbol, decimal character, and thousands separator to display. Under the U.S. English version of Microsoft Windows, the value is displayed in the Custom Properties dialog box as ["$1,200.00"] .

In addition, you can display the value of a custom property in a text field. By clicking Field on the Insert menu when the shape is selected, you can specify a custom property and a format picture for the value of that property. In the Field dialog box, you can specify a custom property under Category. The Visio engine displays a list of appropriate format pictures based on the custom property's data type. The value of the custom property is then displayed in the shape's text block using the format picture you assigned.

If you intend to perform calculations with custom properties, you can define a data type other than string for the property value, such as number, currency, date or time, and duration. For details, see Custom Properties in Chapter 7, Enhancing Shape Behavior.

Protecting Text Formulas

You can protect custom text formulas you create for a shape so that user actions cannot overwrite them. Many common user actions on the drawing page—applying a font, setting margins, applying a text style—affect the values of the Text Transform, Text Block Format, Character, Paragraph, and Tab sections. If you write formulas to customize these text attributes, you can do the following:

• Protect the formula using the guard function
• Prevent users from making changes using a protection lock

Use guard to protect formulas in cells that control the position or location of the text block. For example, protect formulas that customize text width and text height so that resizing a shape won't overwrite your formulas. When you use guard to protect a formula in a cell that controls text formatting, users cannot locally format the text. For details about how applying styles affects the shape's formulas, see Chapter 10, Managing Styles, Formats, and Colors.

Use a protection lock to prevent users from formatting a shape or typing in it. Set the LockFormat cell in the Protection section to 1 to keep users from applying any formatting or styles. Set the LockTextEdit cell in the Protection section to 1 to keep users from typing in a shape (but to allow them to apply a text style). It's best to use LockTextEdit only in cases where entering text would cause the shape to behave in unexpected ways (as can happen with very small shapes).

You can hide text completely by setting the HideText cell to TRUE in the Miscellaneous section. You can still type in the shape: The text is visible as you type, but it won't show in the shape when you're finished typing.

Of course, the more protection you use, the less your users can modify a shape. You want to be able to give users enough flexibility to accomplish their tasks while preserving customized shape formulas.

Testing Text Block Formulas

Use the following steps to test the positioning and resizing of a shape's text block. To ensure that the position of the text block remains correct as a user manipulates the shape, you need to test all combinations of flipping, rotating, and reversing ends.

To test a shape's text block positioning

1. Create an instance of the master you want to test, and then type some text in it.
2. Duplicate the instance seven times. Rotate each instance by increments of 45 degrees. Arrange the eight instances in a rosette. Group the instances for easier handling.



Figure 9-11 This is a test set, and illustrates how the shape normally behaves under various rotations.

3. Duplicate the test set two times (for 2-D objects) or five times (for 1-D objects), and arrange as rows with three columns.
4. If testing a 1-D shape, select the three groups in the bottom row. On the Shape menu, point to Operations, and then click Reverse Ends.
5. Select the group(s) in the middle column. On the Shape menu, point to Rotate or Flip, and then click Flip Vertical.
6. Select the group(s) in the right column. On the Shape menu, point to Rotate or Flip, and then click Flip Horizontal.
7. Print the results and examine them in detail. Fix any problems and test again as needed.

Next, test your shape's ability to handle text. To do this, you replace the test text in every shape, and then check the results.

To test how a shape resizes as text is added

1. Select one of the shapes, and then type new text.

Type enough text to stretch the text block in a manner appropriate to the intended use of the shape.

2. Click away from the shape, and then press CTRL+A to select all the shapes.
3. Press F4 to repeat the new text in all the selected shapes.
4. Print the results and examine them. Fix any problems and test until you get the results you want.
5. As a final test, resize each group. Try both moderate and extreme sizes.

Do the shapes work the way you expected? Does the text still look good? Can you at least read it? If not, maybe you should specify a minimum text width. For details, see Constraining Text Block Size in Controlling Text Rotation earlier in this chapter.