Pattern Variables

The optional pattern attribute (we also support a <pattern> child node which takes precedence over the pattern attribute) defines a pattern. Captivate can use the pattern to pre-render possible values before they are needed, improving performance and allowing each digit to animate independently from the whole.

This is especially useful for clocks and scoreboards, which usually stay in the same format for the duration of a broadcast or video and need low-latency, real-time updating and thus have less time to render.

Note: If a graphic defines a pattern, the pattern defined by the controller will take precedence.

The following is an example of a pattern for a 12-hour hour:minute clock with am/pm at the end.

<pattern>1[0-9]:[0-5][0-9][ap]m</pattern>

This is how you build a pattern:

Pattern	Interpretation
[]	denotes a character group
-	inside a character group denotes a range of characters
\	escape the next character and treat it as literal
any	all other characters are treated as literal
	don't use spaces in a pattern, spaces are always valid

Note: Variables with patterns specified are sometimes referred to as pattern variables.

How Captivate translates variable data to fit the pattern:

• When Captivate defines a pattern on a variable, it creates a format string for that pattern. The format string is generated by each literal character and the first character from each character group. In the pattern given above, the format string will be 10:00am.

• Captivate will use the font metrics of each individual character in the format string and the font metrics of the format string as a whole to calculate a “cell” on screen for each character and generates animations for all possible values of each cell.

• When Captivate receives a value for the variable, it tries to fit the new data into the proper cells based on how well the new data fits the format string.

• After Captivate computes the best match, any characters that aren't allowed for a cell will be replaced by a space character " " instead of whatever was in the related input value.

• By default, the process of finding a match will result in numeric patterns being right-justified and non-numeric patterns being left-justified. Examples will follow.

• To avoid surprises, you can send Captivate data that exactly matches the pattern in question, adding space characters intentionally where needed. Again, see the examples below.

Notes:

Space characters are always considered a possibility for every cell and should not be specified in the pattern string. If your final output requires a space character, set your pattern to use a different character of the proper width in that position.

If a variable pattern needs to include <, & or > (characters reserved by XML format), use a <![CDATA[]]> section. Here’s an example to represent Down and Distance for American Football (using a # and a . to manually tweak the spacing):

<pattern><![CDATA[ [4321][snrt][dht]#&.[0-9][0-9] ]]></pattern>

Captivate generates the width of a cell from the first character in each character group. Therefore, if you use a narrow character as the first character in a group, you might be surprised when Captivate tries to fit a wider character into that cell. A pattern like [1-5] will create a cell for the width of the 1 and the other values won't easily fit in that cell. Make sure the widest possible character shows up first in your pattern, so for digits from 1-5, you might make the pattern [51-4] just to make sure the cell is wide enough to accommodate a 5.

Captivate decides whether to use left or right justification based on the leftmost character in the format string. If that character is numeric, the pattern will adopt a right-justified scheme to keep numbers right-aligned. Otherwise, the pattern will use a left-justified scheme. For precise positioning of your variable values, see the examples below.

Example 1: Controlling the width of a cell

To always keep a small space before the am/pm designation of a clock, just use a narrow character in the pattern:

<pattern>1[0-9]:[0-5][0-9]![ap]m</pattern>

Then, in your submitted data, leave a space character where the ! would be and the on screen display will have a space only as wide as the ! character.

Example 2: Two Ways to Left-Justify a Numeric Pattern Variable

Numeric Pattern

<pattern>[0-9][0-9][0-9][0-9]</pattern>

The first item in the pattern is numeric and therefore Captivate will prefer to right-justify new values against this pattern. Consider this chart where underscore (_) characters are used to designate space characters:

Variable Input	Variable Output
"1"	___1 (right-justified 1)
"1___" (spaces)	1___ (full width input, manual spacing is honored)

Non-numeric Pattern

<pattern>i[0-9][0-9][0-9][0-9]</pattern>

Since the first character in this pattern is not a number (could be anything), Captivate will default to a left-justification scheme. Remember that all characters are optional.

Variable Input	Variable Output (spaces shown as underscores)
"1"	_1___ (small space for the missing i followed by left-justified 1)
"123"	_123 (same as above)
"i1"	i1___ (if you use the i it will be displayed)
"___i"	i____ (best fit, the i has to be first)
"____1"	____1 (full width input, manual spacing honored)
"____i"	_____ (full width input, manual data honored, but no characters are valid)

Example 3: Our Standard Clock Pattern

In most of our sports controllers, we use a standard pattern for a clock. This one pattern supports all the following formats and will keep the numbers aligned to the colon/dot if provided:

• hh:mm

• h:mm

• mm:ss

• m:ss

• ss.t (tenths)

• s.t (tenths)

• ss.hh (hundredths)

• s.hh (hundredths)

<pattern>[0-9][0-9][:.][0-9][0-9]</pattern>

Example 4: Advanced Specialty Clock

This creates a clock pattern where every cell is based on the width of the 8 character, and supports both these formats:

• 12:34

• 123.4

<pattern>[80-9][80-9][8:0-9][8.0-9][80-9]</pattern>

This pattern defines five individual cells:

• [80-9] -- 8 sets the width (8 is a little narrower than 0 in most fonts), allow all digits from 0-9

• [80-9] -- same as above

• [8:0-9] -- 8 sets the width, allow : and all digits from 0-9

• [8.0-9] -- 8 sets the width, allow . and all digits from 0-9

• [80-9] -- same as above

When the clock variable has receives the following values, it will parse and render them as follows:

Variable Input	Variable Output (spaces shown as underscores)
"01:23"	01:23
"1:23"	_1:23 (missing value populates with space)
"1:2"	_1:2_ (missing values populate with spaces)
"01.23"	01_23 (wrong value in column 3 shows as space)
"01.2"	_01.2
"1.2"	__1.2

Values

Some graphics allow variables to contain only a predefined set of values. This can also be represented in the XML definition by using <value> child nodes. These values will be pre-rendered when the controller is loaded.

Example:

<variable name="Background" type="color">
  <value>#ff00ff00</value>
  <value>#ff0000ff</value>
</variable>

As with patterns, these value elements can contain <![CDATA[]]> sections.

Note: If a graphic defines its own set of possible values, that definition will take precedence over the Controller.