Graphics::MeasureCharacterRanges method (gdiplusgraphics.h)
The Graphics::MeasureCharacterRanges method gets a set of regions each of which bounds a range of character positions within a string.
Syntax
Status MeasureCharacterRanges(
[in] const WCHAR *string,
[in] INT length,
[in] const Font *font,
[in, ref] const RectF & layoutRect,
[in] const StringFormat *stringFormat,
[in] INT regionCount,
[out] Region *regions
);
Parameters
[in] string
Type: const WCHAR*
Pointer to a wide-character string.
[in] length
Type: INT
Integer that specifies the number of characters in the string array. If the string parameter points to a NULL-terminated string, this parameter can be set to –1.
[in] font
Type: const Font*
Pointer to a Font object that specifies the font characteristics (the family name, size, and style of the font) to be applied to the string.
[in, ref] layoutRect
Type: const Rectf
Reference to a rectangle that bounds the string.
[in] stringFormat
Type: const StringFormat*
Pointer to a StringFormat object that specifies the character ranges and layout information, such as alignment, trimming, tab stops, and so forth.
[in] regionCount
Type: INT
Integer that specifies the number of regions that are expected to be received into the regions array. This number should be equal to the number of character ranges currently in the StringFormat object.
[out] regions
Type: Region*
Pointer to an array of Region objects that receives the regions, each of which bounds a range of text.
Return value
Type: Status
If the method succeeds, it returns Ok, which is an element of the Status enumeration.
If the method fails, it returns one of the other elements of the Status enumeration.
Remarks
A character range is a range of character positions within a string of text. The area of the display that is occupied by a group of characters that are specified by the character range, is the bounding region. A character range is set by SetMeasurableCharacterRanges. The number of ranges that are currently set can be determined by calling GetMeasurableCharacterRangeCount. This number is also the number of regions expected to be obtained by the MeasureCharacterRanges method.
Examples
The following example defines three ranges of character positions within a string and sets those ranges in a StringFormat object. Next, the MeasureCharacterRanges method is used to get the three regions of the display that are occupied by the characters that are specified by the ranges. This is done for three different layout rectangles to show how the regions change according to the layout of the string. Also, on the third repetition of this, the string format flags are changed so that the regions measured will include trailing spaces.
VOID MeasureCharRanges(HDC hdc)
{
Graphics graphics(hdc);
// Brushes and pens used for drawing and painting
SolidBrush blueBrush(Color(255, 0, 0, 255));
SolidBrush redBrush(Color(100, 255, 0, 0));
Pen blackPen(Color(255, 0, 0, 0));
// Layout rectangles used for drawing strings
RectF layoutRect_A(20.0f, 20.0f, 130.0f, 130.0f);
RectF layoutRect_B(160.0f, 20.0f, 165.0f, 130.0f);
RectF layoutRect_C(335.0f, 20.0f, 165.0f, 130.0f);
// Three different ranges of character positions within the string
CharacterRange charRanges[3] = { CharacterRange(3, 5),
CharacterRange(15, 2),
CharacterRange(30, 15), };
// Font and string format to apply to string when drawing
Font myFont(L"Times New Roman", 16.0f);
StringFormat strFormat;
// Other variables
Region* pCharRangeRegions; // pointer to CharacterRange regions
short i; // loop counter
INT count; // number of character ranges set
WCHAR string[] = L"The quick, brown fox easily jumps over the lazy dog.";
// Set three ranges of character positions.
strFormat.SetMeasurableCharacterRanges(3, charRanges);
// Get the number of ranges that have been set, and allocate memory to
// store the regions that correspond to the ranges.
count = strFormat.GetMeasurableCharacterRangeCount();
pCharRangeRegions = new Region[count];
// Get the regions that correspond to the ranges within the string when
// layout rectangle A is used. Then draw the string, and show the regions.
graphics.MeasureCharacterRanges(string, -1,
&myFont, layoutRect_A, &strFormat, count, pCharRangeRegions);
graphics.DrawString(string, -1,
&myFont, layoutRect_A, &strFormat, &blueBrush);
graphics.DrawRectangle(&blackPen, layoutRect_A);
for ( i = 0; i < count; i++)
{
graphics.FillRegion(&redBrush, pCharRangeRegions + i);
}
// Get the regions that correspond to the ranges within the string when
// layout rectangle B is used. Then draw the string, and show the regions.
graphics.MeasureCharacterRanges(string, -1,
&myFont, layoutRect_B, &strFormat, count, pCharRangeRegions);
graphics.DrawString(string, -1,
&myFont, layoutRect_B, &strFormat, &blueBrush);
graphics.DrawRectangle(&blackPen, layoutRect_B);
for ( i = 0; i < count; i++)
{
graphics.FillRegion(&redBrush, pCharRangeRegions + i);
}
// Get the regions that correspond to the ranges within the string when
// layout rectangle C is used. Set trailing spaces to be included in the
// regions. Then draw the string, and show the regions.
strFormat.SetFormatFlags(StringFormatFlagsMeasureTrailingSpaces);
graphics.MeasureCharacterRanges(string, -1,
&myFont, layoutRect_C, &strFormat, count, pCharRangeRegions);
graphics.DrawString(string, -1,
&myFont, layoutRect_C, &strFormat, &blueBrush);
graphics.DrawRectangle(&blackPen, layoutRect_C);
for ( i = 0; i < count; i++)
{
graphics.FillRegion(&redBrush, pCharRangeRegions + i);
}
// Delete memory for the range regions.
delete [] pCharRangeRegions;
}
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows XP, Windows 2000 Professional [desktop apps only] |
| Minimum supported server | Windows 2000 Server [desktop apps only] |
| Target Platform | Windows |
| Header | gdiplusgraphics.h (include Gdiplus.h) |
| Library | Gdiplus.lib |
| DLL | Gdiplus.dll |