Iterating through specific style runs

You can also choose whether to differentiate style runs that share a style name but may have different values. For example, if a range of text includes both red and blue characters, you could either handle the red and blue ranges separately or as a single run.

This figure shows the classes that allow you to iterate through style runs:

TStyleRunIterator provides the protocol for searching through a text object for specific style runs. TStyleRunIterator takes a filter that describes the style runs you want the iterator to return.

TStyleFilter is the base class for all style filters. Several concrete subclasses are provided:

• TSingleStyleFilter, TSingleStyleTypeFilter, and TSingleStyleValueFilter return specific style runs based on a particular type of style (for example, any colored text) or a particular value (for example, red text).
• TNullStyleFilter returns style runs as they currently exist within the text instance.

Style filters

• TSingleStyleFilter extracts runs with a specific type of style, separating runs that contain that type of style but with a different value.
• TSingleTypeStyleFilter extracts runs with a specific type of style, concatenating runs that contain that type of style regardless of the values.
• TSingleValueStyleFilter extracts runs with a specific type of style and a specific value.
• TNullStyleFilter returns each style run as stored by the text object. This is the default setting.

Using the default filter--TNullStyleFilter--returns the style runs as shown in Figure 12.

As shown in Figure 13, using a TSingleStyleFilter with a color style extracts the runs containing characters 0-9 and 15-19. Using a TSingleStyleFilter with a point size style extracts the runs containing characters 0-4 and 5-14.

As shown in Figure 14, using a TSingleTypeStyleFilter with a color style extracts the runs containing characters 0-9 and 15-19. Using a TSingleTypeStyleFilter with a point size style identifies a single run containing characters 0-14.

As shown in Figure 15, using a TSingleValueStyleFilter with a point size 9 style extracts the run containing characters 5-14.

Combining filters

Two classes for combining filters are provided:

• TNotStyleFilter inverts the behavior of its base filter, ignoring what the base filter normally selects and selecting what it normally ignores.
• TBoundaryStyleFilter returns runs selected by a base filter and runs between what is selected by the base filter. This filter breaks the runs both between included and excluded runs and anywhere the base filter breaks its selected runs.

For example, if you iterate through the text object shown in figures 12 through 15 using a TBoundaryStyleFilter with a TSingleStyleFilter that filters for a point size style, the results are three runs as shown in Figure 16:

Example: Using TStyleRunIterator

1. Create a style filter (if you do not create a style filter, a TNullStyleFilter is used).
   You can construct a filter using either a style name or an actual style object.
   
2. Create a TStyleRunIterator, setting a pointer to the text and attaching the filter.
   
3. Call First, Last, or Set to establish the starting point for the search.
   
4. Call Next or Previous to iterate through the text.
   

  void
  GetColorRuns(TText& styledText)
  {
      TTextColorStyle style;
      TSingleStyleFilter colorFilter(style);
  
      TStyleRunIterator findColors(&styledText,colorFilter);
  
      TTextRange foundRange;
      Boolean status = findColors.First(foundRange);
  
      while(status) {
          // Do something interesting...
          status = findColors.Next(foundRange);
      }
  }