Home COM GDI+ WebBrowser Data Access 

String Format Functions (GDI+)

 

 

The StringFormat functions allow to set and get text layout information (such as alignment, orientation, tab stops, and clipping) and display manipulations (such as trimming, font substitution for characters that are not supported by the requested font, and digit substitution for languages that do not use Western European digits). A StringFormat object can be passed to the GdipDrawString function to format a string.

 

Return Values

If the function succeeds, it returns Ok, which is an element of the Status enumeration.

 

If the function fails, it returns one of the other elements of the Status enumeration.

 

GdipCloneStringFormat

 

Description

Creates a new StringFormat object and initializes it with the contents of this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipCloneStringFormat(

    GDIPCONST GpStringFormat *format,

    GpStringFormat **newFormat

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCloneStringFormat ( _

    BYVAL pFormat AS DWORD, _

    BYREF newFormat AS DWORD _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

newFormat

[in] Pointer to a variable that receives a pointer to the new StringFormat object.

 

GdipCreateStringFormat

 

Description

Creates a StringFormat object based on string format flags and a language.

Syntax

GpStatus WINGDIPAPI GdipCreateStringFormat(

    INT formatAttributes,

    LANGID language,

    GpStringFormat **format

);

PowerBASIC Syntax

DECLARE FUNCTION GdipCreateStringFormat ( _

    BYVAL formatAttributes AS LONG, _

    BYVAL language AS WORD, _

    BYREF pFormat AS DWORD _

) AS LONG

Parameter

 

formatAttributes

[in] Value that specifies the format flags that control most of the characteristics of the StringFormat object. The flags are set by applying a bitwise OR to elements of the StringFormatFlags enumeration. The default value is 0 (no flags set).

language

[in] Sixteen-bit value that specifies the language to use. The default value is LANG_NEUTRAL, which is the user's default language.

format

[out] Pointer to a variable that receives a pointer to the new StringFormat object.

 

GdipDeleteStringFormat

 

Description

Deletes the specified StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipDeleteStringFormat(

    GpStringFormat *format

);

PowerBASIC Syntax

DECLARE FUNCTION GdipDeleteStringFormat ( _

    BYVAL pFormat AS DWORD _

) AS LONG 

Parameters

 

format

[in] Pointer to the StringFormat object.

 

GdipGetStringFormatAlign

 

Description

Gets the string format flags for this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatAlign(

    GDIPCONST GpStringFormat *format,

    StringAlignment *align

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatAlign ( _

    BYVAL pFormat AS DWORD, _

    BYREF align AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

align

[out] Pointer to a value that receives a value that indicates which string format flags are set for this StringFormat object. This value can be any combination (the result of a bitwise OR applied to two or more elements) of elements of the StringFormatFlags enumeration.

 

GdipGetStringFormatDigitSubstitution

 

Description

Gets an element of the StringDigitSubstitute enumeration that indicates the digit substitution method that is used by this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatDigitSubstitution(

    GDIPCONST GpStringFormat *format,

    LANGID *language,

    StringDigitSubstitute *substitute

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatDigitSubstitution ( _

    BYVAL pFormat AS DWORD, _

    BYREF language AS WORD, _

    BYREF substitute AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

language

[in] A 16-bit value that specifies the language to use.

substitute

[out] Pointer to a variable that receives an element of the StringDigitSubstitute enumeration.

Remarks

The digit substitution method replaces, in a string, Western European digits with digits that correspond to a user's locale or language.

 

GdipGetStringFormatFlags

 

Description

Gets the string format flags for this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatFlags(

    GDIPCONST GpStringFormat *format,

    INT *flags

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatFlags ( _

    BYVAL pFormat AS DWORD, _

    BYREF flags AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

flags

[out] Pointer to a variable that receives a 16-bit value that specifies the language to use.

 

GdipGetStringFormatHotkeyPrefix

 

Description

Gets an element of the HotkeyPrefix enumeration that indicates the type of processing that is performed on a string when a hot key prefix, an ampersand (&), is encountered.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatHotkeyPrefix(

    GDIPCONST GpStringFormat *format,

    INT *hotkeyPrefix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatHotkeyPrefix ( _

    BYVAL pFormat AS DWORD, _

    BYREF hotkeyPrefix AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

hotkeyPrefix

[out] Pointer to a variable that receives an element of the HotkeyPrefix enumeration that indicates the type of hot key prefix processing that is performed on a string.

 

GdipGetStringFormatLineAlign

 

Description

Gets an element of the StringAlignment enumeration that indicates the line alignment of this StringFormat object in relation to the origin of the layout rectangle. The line alignment setting specifies how to align the string vertically in the layout rectangle. The layout rectangle is used to position the displayed string.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatLineAlign(

    GDIPCONST GpStringFormat *format,

    StringAlignment *align

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatLineAlign ( _

    BYVAL pFormat AS DWORD, _

    BYREF align AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

align

[out] Pointer to a variable that receives an element of the StringAlignment enumeration.

 

GdipGetStringFormatMesurableCharacterRangeCount

 

Description

Gets the number of measurable character ranges that are currently set. The character ranges that are set can be measured in a string by using the GdipMeasureCharacterRanges function.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatMeasurableCharacterRangeCount(

    GDIPCONST GpStringFormat *format,

    INT *count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatMeasurableCharacterRangeCount ( _

    BYVAL pFormat AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

count

[out] Pointer to a variable that receives the number of character ranges that can be measured by MeasureCharacterRanges.

 

GdipGetStringFormatTabStopCount

 

Description

Gets the number of tab-stop offsets in this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatTabStopCount(

    GDIPCONST GpStringFormat *format,

    INT * count

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatTabStopCount ( _

    BYVAL pFormat AS DWORD, _

    BYREF count AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

count

[out] Pointer to a variable that receives the number of tab stops in this StringFormat object.

 

GdipGetStringFormatTabStops

 

Description

Gets the offsets of the tab stops in this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatTabStops(

    GDIPCONST GpStringFormat *format,

    INT count,

    REAL *firstTabOffset,

    REAL *tabStops

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatTabStops ( _

    BYVAL pFormat AS DWORD, _

    BYVAL count AS LONG, _

    BYREF firstTabOffset AS SINGLE, _

    BYREF tabStops AS SINGLE _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

count

[out] Integer that specifies the number of tab-stop offsets in the tabStops array.

firstTabOffset

[out] Pointer to a SINGLE that receives the initial offset position. This initial offset position is relative to the string's origin and the offset of the first tab stop is relative to the initial offset position.

tabStops

[out] Pointer to an array of type SINGLE that receives the tab-stop offsets. The offset of the first tab stop is the first value in the array, the offset of the second tab stop, the second value in the array, and so on.

Remarks

Each tab-stop offset in the tabStops array, except the first one, is relative to the previous one. The first tab-stop offset is relative to the initial offset position indicated by firstTabOffset. For example, if the initial offset position is 8 and the first tab-stop offset is 50, then the first tab stop is at position 58. If the initial offset position is zero, then the first tab-stop offset is relative to position 0, the string origin.

 

GdipGetStringFormatTrimming

 

Description

Gets an element of the StringTrimming enumeration that indicates the trimming style of this StringFormat object. The trimming style determines how to trim characters from a string that is too large to fit in the layout rectangle.

Syntax

GpStatus WINGDIPAPI GdipGetStringFormatTrimming(

    GDIPCONST GpStringFormat *format,

    StringTrimming *trimming

);

PowerBASIC Syntax

DECLARE FUNCTION GdipGetStringFormatTrimming ( _

    BYVAL pFormat AS DWORD, _

    BYREF trimming AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

trimming

[out] Pointer to a variable that receives an element of the StringTrimming enumeration.

 

GdipSetStringFormatAlign

 

Description

Sets the character alignment of this StringFormat object in relation to the origin of the layout rectangle. A layout rectangle is used to position the displayed string.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatAlign(

    GpStringFormat *format,

    StringAlignment align

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatAlign ( _

    BYVAL pFormat AS DWORD, _

    BYVAL align AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

align

[in] Element of the StringAlignment enumeration that specifies how a string is aligned in reference to the bounding rectangle.

 

GdipSetStringFormatDigitSubstitution

 

Description

Sets the digit substitution method and the language that corresponds to the digit substitutes.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatDigitSubstitution(

    GpStringFormat *format,

    LANGID language,

    StringDigitSubstitute substitute

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatDigitSubstitution ( _

    BYVAL pFormat AS DWORD, _

    BYVAL language AS WORD, _

    BYVAL substitute AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

language

[in] Sixteen-bit value that forms a national language support (NLS) language identifier. The identifier specifies the language associated with the substitute digits. For example, if this StringFormat object uses Arabic substitution digits, then this method will return a value that indicates an Arabic language.

substitute

[in] Element of the StringDigitSubstitute enumeration that specifies the digit substitution method to be used.

 

GdipSetStringFormatFlags

 

Description

Sets the format flags for this StringFormat object. The format flags determine most of the characteristics of a StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatFlags(

    GpStringFormat *format,

    INT flags

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatFlags ( _

    BYVAL pFormat AS DWORD, _

    BYVAL flags AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

flags

[in] Thirty-two bit value that specifies the format flags that control most of the characteristics of the StringFormat object. The flags are set by applying a bitwise OR to elements of the StringFormatFlags enumeration.

 

GdipSetStringFormatHotkeyPrefix

 

Description

Sets the type of processing that is performed on a string when the hot key prefix, an ampersand (&), is encountered. The ampersand is called the hot key prefix and can be used to designate certain keys as hot keys.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatHotkeyPrefix(

    GpStringFormat *format,

    INT hotkeyPrefix

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatHotkeyPrefix ( _

    BYVAL pFormat AS DWORD, _

    BYVAL hotkeyPrefix AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

hotkeyPrefix

[in] Element of the HotkeyPrefix enumeration that specifies how to process the hot key prefix.

 

GdipSetStringFormatLineAlign

 

Description

Sets the line alignment of this StringFormat object in relation to the origin of the layout rectangle. The line alignment setting specifies how to align the string vertically in the layout rectangle. The layout rectangle is used to position the displayed string.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatLineAlign(

    GpStringFormat *format,

    StringAlignment align

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatLineAlign ( _

    BYVAL pFormat AS DWORD, _

    BYVAL align AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

align

[in] Element of the StringAlignment enumeration that specifies how to align a string in reference to the layout rectangle.

 

GdipSetStringFormatMeasurableCharacterRanges

 

Description

Sets a series of character ranges for this StringFormat object that, when in a string, can be measured by the MeasureCharacterRanges method.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatMeasurableCharacterRanges(

    GpStringFormat *format,

    INT rangeCount,

    GDIPCONST CharacterRange *ranges

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatMeasurableCharacterRanges ( _

    BYVAL pFormat AS DWORD, _

    BYVAL rangeCount AS LONG, _

    BYREF ranges AS CharacterRange _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

rangeCount

[in] Long integer value that specifies the number of character ranges in the ranges array.

ranges

[in] Pointer to an array of CharacterRange objects that specify the character ranges to be measured.

 

GdipSetStringFormatTabStops

 

Description

Sets the offsets for tab stops in this StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatTabStops(

    GpStringFormat *format,

    REAL firstTabOffset,

    INT count,

    GDIPCONST REAL *tabStops

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatTabStops ( _

    BYVAL pFormat AS DWORD, _

    BYVAL firstTabOffset AS SINGLE, _

    BYVAL count AS LONG, _

    BYREF tabStops AS SINGLE _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

firstTabOffset

[in] Single precision value that specifies the initial offset position. This initial offset position is relative to the string's origin and the offset of the first tab stop is relative to the initial offset position.

count

[in] Long integer value that specifies the number of tab-stop offsets in the tabStops array.

tabStops

[in] Pointer to an array of real numbers that specify the tab-stop offsets. The offset of the first tab stop is the first value in the array, the offset of the second tab stop, the second value in the array, and so on.

Remarks

Each tab-stop offset in the tabStops array, except the first one, is relative to the previous one. The first tab-stop offset is relative to the initial offset position specified by firstTabOffset. For example, if the initial offset position is 8 and the first tab-stop offset is 50, then the first tab stop is at position 58. If the initial offset position is zero, then the first tab-stop offset is relative to position 0, the string origin.

 

GdipSetStringFormatTrimming

 

Description

Sets the trimming style for this StringFormat object. The trimming style determines how to trim a string so that it fits into the layout rectangle.

Syntax

GpStatus WINGDIPAPI GdipSetStringFormatTrimming(

    GpStringFormat *format,

    StringTrimming trimming

);

PowerBASIC Syntax

DECLARE FUNCTION GdipSetStringFormatTrimming ( _

    BYVAL pFormat AS DWORD, _

    BYVAL trimming AS LONG _

) AS LONG

Parameters

 

format

[in] Pointer to the StringFormat object.

trimming

[in] Element of the StringTrimming enumeration that specifies the style of trimming to be performed on the string.

 

GdipStringFormatGetGenericDefault

 

Description

Creates a generic, default StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipStringFormatGetGenericDefault(

    GpStringFormat **format

);

PowerBASIC Syntax

DECLARE FUNCTION GdipStringFormatGetGenericDefault ( _

    BYREF pFormat AS DWORD _

) AS LONG

Parameter

 

format

[out] Pointer to a variable that receives a pointer to the new StringFormat object.

 

GdipStringFormatGetGenericTypographic

 

Description

Creates a generic, typographic StringFormat object.

Syntax

GpStatus WINGDIPAPI GdipStringFormatGetGenericTypographic(

    GpStringFormat **format

);

PowerBASIC Syntax

DECLARE FUNCTION GdipStringFormatGetGenericTypographic ( _

    BYREF pFormat AS DWORD _

) AS LONG

Parameter

 

format

[out] Pointer to a variable that receives a pointer to the new StringFormat object.

 

Page last updated on Monday, 11 December 2006 11:11:39 +0100