StringFormat::SetMeasurableCharacterRanges Method (array<CharacterRange>^)

 

Specifies an array of CharacterRange structures that represent the ranges of characters measured by a call to the MeasureCharacterRanges method.

Namespace:   System.Drawing
Assembly:  System.Drawing (in System.Drawing.dll)

public:
void SetMeasurableCharacterRanges(
	array<CharacterRange>^ ranges
)

Parameters

ranges
Type: array<System.Drawing::CharacterRange>^

An array of CharacterRange structures that specifies the ranges of characters measured by a call to the MeasureCharacterRanges method.

Exception Condition
OverflowException

More than 32 character ranges are set.

Setting more than 32 character ranges is not allowed and will cause an System::OverflowException.

The following example is designed for use with Windows Forms, and it requires PaintEventArgs e, which is a parameter of the Paint event handler. The code performs the following actions:

  • Sets the character ranges of the StringFormat.

  • Measures the character ranges for a given string and layout rectangle.

  • Draws the string and layout rectangle.

  • Paints the regions. Each Region specifies an area that is occupied by a range of characters. The values in the regions are set when the character ranges are measured by the MeasureCharacterRanges method.

  • Repeats the first four steps, but includes trailing spaces in the measurement of each character range.

  • Clears the format flags of the StringFormat so that trailing spaces are not included in the measurement of each character range.

  • Repeats the first four steps, but uses a different layout rectangle just to demonstrate that the layout rectangle affects the measurements of the character ranges. The size of the font will also affect the measurement.

void SetMeasCharRangesExample( PaintEventArgs^ e )
{
   Graphics^ g = e->Graphics;
   SolidBrush^ redBrush = gcnew SolidBrush( Color::FromArgb( 50, 255, 0, 0 ) );

   // Layout rectangles, font, and string format used for displaying string.
   Rectangle layoutRectA = Rectangle(20,20,165,80);
   Rectangle layoutRectB = Rectangle(20,110,165,80);
   Rectangle layoutRectC = Rectangle(20,200,240,80);
   System::Drawing::Font^ tnrFont = gcnew System::Drawing::Font( "Times New Roman",16 );
   StringFormat^ strFormat = gcnew StringFormat;

   // Ranges of character positions within a string.
   array<CharacterRange>^ charRanges = {CharacterRange(3,5),CharacterRange(15,2),CharacterRange(30,15)};

   // Each region specifies the area occupied by the characters within a
   // range of positions. the values are obtained by using a method that
   // measures the character ranges.
   array<System::Drawing::Region^>^charRegions = gcnew array<System::Drawing::Region^>(charRanges->Length);

   // String to be displayed.
   String^ str = "The quick, brown fox easily jumps over the lazy dog.";

   // Set the char ranges for the string format.
   strFormat->SetMeasurableCharacterRanges( charRanges );

   // loop counter (unsigned 8-bit integer)
   Byte i;

   // Measure the char ranges for a given string and layout rectangle. Each
   // area occupied by the characters in a range is stored as a region. Then
   // draw the string and layout rectangle, and paint the regions.
   charRegions = g->MeasureCharacterRanges( str, tnrFont, layoutRectA, strFormat );
   g->DrawString( str, tnrFont, Brushes::Blue, layoutRectA, strFormat );
   g->DrawRectangle( Pens::Black, layoutRectA );

   // Paint the regions.
   for ( i = 0; i < charRegions->Length; i++ )
      g->FillRegion( redBrush, charRegions[ i ] );

   // Repeat the above steps, but include trailing spaces in the char
   // range measurement by setting the appropriate string format flag.
   strFormat->FormatFlags = StringFormatFlags::MeasureTrailingSpaces;
   charRegions = g->MeasureCharacterRanges( str, tnrFont, layoutRectB, strFormat );
   g->DrawString( str, tnrFont, Brushes::Blue, layoutRectB, strFormat );
   g->DrawRectangle( Pens::Black, layoutRectB );
   for ( i = 0; i < charRegions->Length; i++ )
      g->FillRegion( redBrush, charRegions[ i ] );

   // Clear all the format flags.
   strFormat->FormatFlags = StringFormatFlags(0);

   // Repeat the steps, but use a different layout rectangle. the dimensions
   // of the layout rectangle and the size of the font both affect the
   // character range measurement.
   charRegions = g->MeasureCharacterRanges( str, tnrFont, layoutRectC, strFormat );
   g->DrawString( str, tnrFont, Brushes::Blue, layoutRectC, strFormat );
   g->DrawRectangle( Pens::Black, layoutRectC );

   // Paint the regions.
   for ( i = 0; i < charRegions->Length; i++ )
      g->FillRegion( redBrush, charRegions[ i ] );
}

.NET Framework
Available since 1.1
Return to top
Show: