Graphics.MeasureCharacterRanges Method (String, Font, RectangleF, StringFormat)

 

Gets an array of Region objects, each of which bounds a range of character positions within the specified string.

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

Public Function MeasureCharacterRanges (
	text As String,
	font As Font,
	layoutRect As RectangleF,
	stringFormat As StringFormat
) As Region()

Parameters

text
Type: System.String

String to measure.

font
Type: System.Drawing.Font

Font that defines the text format of the string.

layoutRect
Type: System.Drawing.RectangleF

RectangleF structure that specifies the layout rectangle for the string.

stringFormat
Type: System.Drawing.StringFormat

StringFormat that represents formatting information, such as line spacing, for the string.

Return Value

Type: System.Drawing.Region()

This method returns an array of Region objects, each of which bounds a range of character positions within the specified string.

The regions returned by this method are resolution-dependent, so there might be a slight loss of accuracy if strings are recorded in a metafile at one resolution and later played back at a different resolution.

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

  • Sets a string "First and Second ranges" and a font for display of the string ("Times New Roman", 16 point).

  • Sets two character ranges within the string (which correspond to the words "First" and "Second").

  • Creates a rectangle in which to display the string.

  • Sets the formatting of the string ¾ including the two character ranges.

  • Draws the string to the screen.

  • Measures the character ranges, determines rectangles that bound the two specified ranges.

  • Draws the two rectangles to the screen.

The result is the displayed string with the first range ("First") bounded by a red rectangle and the second range ("Second") bounded by a blue rectangle.

   Private Sub MeasureCharacterRangesRegions(ByVal e As PaintEventArgs)

       ' Set up string.
       Dim measureString As String = "First and Second ranges"
       Dim stringFont As New Font("Times New Roman", 16.0F)

       ' Set character ranges to "First" and "Second".
       Dim characterRanges As CharacterRange() = _
       {New CharacterRange(0, 5), New CharacterRange(10, 6)}

       ' Create rectangle for layout.
       Dim x As Single = 50.0F
       Dim y As Single = 50.0F
       Dim width As Single = 35.0F
       Dim height As Single = 200.0F
       Dim layoutRect As New RectangleF(x, y, width, height)

       ' Set string format.
       Dim stringFormat As New StringFormat
       stringFormat.FormatFlags = StringFormatFlags.DirectionVertical
       stringFormat.SetMeasurableCharacterRanges(characterRanges)

       ' Draw string to screen.
       e.Graphics.DrawString(measureString, stringFont, Brushes.Black, _
       x, y, stringFormat)

       ' Measure two ranges in string.
       Dim stringRegions() As [Region] = e.Graphics.MeasureCharacterRanges(measureString, _
stringFont, layoutRect, stringFormat)

       ' Draw rectangle for first measured range.
       Dim measureRect1 As RectangleF = _
       stringRegions(0).GetBounds(e.Graphics)
       e.Graphics.DrawRectangle(New Pen(Color.Red, 1), _
       Rectangle.Round(measureRect1))

       ' Draw rectangle for second measured range.
       Dim measureRect2 As RectangleF = _
       stringRegions(1).GetBounds(e.Graphics)
       e.Graphics.DrawRectangle(New Pen(Color.Blue, 1), _
       Rectangle.Round(measureRect2))
   End Sub

.NET Framework
Available since 1.1
Return to top
Show: