Microsoft DirectX 9.0 SDK Update (October 2004)

Font.DrawText Method

Language:

Note: This documentation is preliminary and is subject to change.

Draws formatted text.

Definition

Visual Basic .NET Public Function DrawText( _
    ByVal sprite As Sprite, _
    ByVal text As String, _
    ByRef rect As Rectangle, _
    ByVal format As DrawTextFormat, _
    ByVal color As Integer _
) As Integer
C# public int DrawText(
    Sprite sprite,
    string text,
    ref Rectangle rect,
    DrawTextFormat format,
    int color
);
Managed C++ public: int DrawText(
    Sprite *sprite,
    String *text,
    Rectangle *rect,
    DrawTextFormat format,
    int color
);
JScript .NET public function DrawText(
    sprite : Sprite,
    text : String,
    rect : Rectangle,
    format : DrawTextFormat,
    color : int
) : int;

Parameters

sprite Microsoft.DirectX.Direct3D.Sprite. A Sprite object that contains the string. Can be null, in which case Microsoft® Direct3D® renders the string with its own sprite object.

If Font.DrawText will be called more than once in a row, a sprite object should be specified to improve efficiency.
text System.String. String to draw.
rect System.Drawing.Rectangle. A reference to a Rectangle Leave Site structure that contains the rectangle, in logical coordinates, in which the text is being formatted. Also used to return modified values when calling Font.DrawText with the value of DrawTextFormat.CalculateRect in the format parameter.
format Microsoft.DirectX.Direct3D.DrawTextFormat. Method of formatting the text; can be any combination of values from the DrawTextFormat enumeration.
color System.Int32. Integer color value.

Return Value

System.Int32 . If the function succeeds, the return value is the height of the text in logical units. If DrawTextFormat.Center or DrawTextFormat.Bottom is specified in the format parameter, the return value is the offset from rect.Top Leave Site to the bottom of the drawn text. If the function fails, the return value is 0.

Remarks

This method must be called from inside of a Device.BeginScene ... Device.EndScene block. The only exception is when an application calls DrawText with CalculateRect to calculate the size of a given block of text.

Unless the NoClip format is used, this method clips the text so that it does not appear outside of the specified rectangle. All formatting is assumed to have multiple lines unless the SingleLine format is specified.

If the selected font is too large for the rectangle, this method does not attempt to substitute a smaller font.

This method supports only fonts whose escapement and orientation are both zero.


© 2004 Microsoft Corporation. All rights reserved. Terms of use.

Feedback? Please provide us with your comments on this topic.
For more help, visit the DirectX Developer Center