TEXT, NATIVE LANGUAGE SUPPORT, AND TIME MEDIA - Specifying conditional formatters

Specifying conditional formatters

TChoiceFormatter is another special formatter class that provides a set of TParameterFormatter instances that can be chosen from at run time. TChoiceFormatter contains a selection of TParameterFormatter instances identified by number. It selects the instance to use according to the value of a numeric variable. For example, for the code shown in "Creating a TParameterFormatter instance" on page 220 you could add a TChoiceFormatter that replaces are with is and files with file when the value of parameter 1, representing the number of files, is 1.

Some examples of how you might use a TChoiceFormatter are:

Mapping month numbers to month names (1 = January, and so on)
Providing text that agrees grammatically with the value of a numeric variable--for example, you might provide singular and plural forms of a noun or verb

The TChoiceFormatter constructor takes TParameterFormatter instances. You can, however, pass in a simple text string instead. The constructor uses the string to create a TParameterFormatter instance with a plain template--one with no variable ranges.

Use TChoiceFormatter instances by nesting them within a TParameterFormatter instance. Create the TChoiceFormatter and then use the TParameterFormatter::SetParameterFormat member function to attach it to the appropriate segment in the text template.

You can also implement multiple levels of nested formatters for more complex message formatting.

Creating a TChoiceFormatter instance

To create and use a TChoiceFormatter instance:

Instantiate TChoiceFormatter.
Use the SetChoice member function to specify the format for each numeric value.
Attach the TChoiceFormatter to the parameter formatter, specifying the text range for the substitute values and the parameter containing the numeric variable.

This example shows how to use TChoiceFormatter to make the parameter formatter message shown in "Creating a TParameterFormatter instance" on page 72 grammatically correct. The formatter substitutes the word is for are and the word file for files when the value of the number-of-files variable is 1.

  TChoiceFormatter myChoiceFormatter;
  myChoiceFormatter.SetChoice( TStandardText("is"), 1 );// if the variable = 1 use is
  myChoiceFormatter.SetChoice( TStandardText("are") );  // use are for all other values
  
  // Attach the TChoiceFormatter to parameter 1
  myParameterFormatter.SetParameterFormat
              (TTextRange( TTextOffset(19), TTextOffset(22)), 1, myChoiceFormatter );
  
  // Use the same TChoiceFormatter to change "files" to "file"
  myChoiceFormatter.ClearAllPatterns();
  myChoiceFormatter.SetChoice( TStandardText("file"), 1 );
  myChoiceFormatter.SetChoice( TStandardText("files") );
  myParameterFormatter.SetParameterFormat
              (TTextRange( TTextOffset(25), TTextOffset(30)), 1, myChoiceFormatter );

Nesting formatters within a TChoiceFormatter

You can create more complex formatters by attaching a formatter as an option for a TChoiceFormatter.

This example shows how to provide three options for the parameter formatter shown in "Creating a TParameterFormatter instance" on page 72, depending on the number of files:

...there aren't any files...
...there is a single file...
...there are 12 files...

It constructs a submessage for the range are n files so that the appropriate value is substituted for variable values greater than 1. For the values 0 and 1, different messages are used.

  myParameterFormatter.ClearParameterFormat(TTextRange( TTextOffset(19), TTextOffset(30) );
  
  myChoiceFormatter.ClearAllPatterns();
  myChoiceFormatter.SetChoice( TStandardText("aren't any files"), 0 );
  myChoiceFormatter.SetChoice( TStandardText("is a single file"), 1 );
  
  TParameterFormatter mySubMessage( TStandardText("are n files") );
  mySubMessage.SetParameterType( 1, TStandardText("TFormattableNumber) );
  mySubMessage.SetParameterFormat( TTextRange( TTextOffset(4), TTextOffset(5) ), 1,
                               myNumberFormat);
  myChoiceFormatter.SetChoice(mySubMessage);
  
  myParameterFormatter.SetParameterFormat( TTextRange(TTextOffset(19), TTextOffset(30)),
                                      1,myChoiceFormatter);

[Contents] [Previous] [Next]

Click the icon to mail questions or corrections about this material to Taligent personnel.

Generated with WebMaker