Windows API Guide - Reference - Volume 1: Version 3.0 For the MS-DOS and PC-DOS Operating Systems

2017-07-07 02:10:07

Declare Function GetCurrencyFormat Lib "kernel32.dll" Alias "GetCurrencyFormatA" (ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat As Any, ByVal lpCurrencyStr As String, ByVal cchCurrency As Long) As Long

Platforms

Windows 95: Supported.
Windows 98: Supported.
Windows NT: Requires Windows NT 3.5 or later.
Windows 2000: Supported.
Windows CE: Requires Windows CE 1.0 or later.

Description & Usage

GetCurrencyFormat formats a currency value for display. By default, the function formats the currency according to the specified locale's settings. However, custom formatting preferences can instead be used. The end result of GetCurrencyFormat is a currency amount displayed according to the user's preferences.

Return Value

If an error occured, the function returns 0 (use GetLastError to get the error code). If successful, the function returns the number of characters copied into the string passed as lpNumberStr, not including the terminating null character.

Visual Basic-Specific Issues

When passing 0 for the lpFormat parameter, the expression ByVal CLng(0) must be used. See the example code for a demonstration of this.

Parameters

Locale

The locale identifier of the locale to format the currency value according to. This identifier could be generated by the MAKELCID macro. Alternatively, this could be one of the following flags specifying a locale:

LOCALE_SYSTEM_DEFAULT: The system's default locale.
LOCALE_USER_DEFAULT: The user's default locale.

dwFlags

If no structure is passed as lpFormat, this parameter determines the settings used to format the currency value. If this is 0, the current locale settings are used. Or, this could be the following flag:

LOCALE_NOUSEROVERRIDE: Use the system's default settings for the locale, regardless of any modifications the user may have made to it.

lpValue

A string containing the number to format. The only allowable characters in this string are the digits 0-9 and at most a single decimal point character (.). If the number is negative, the first character in the string must be a minus sign character (-). Any other characters are invalid. Notice how you must not include a currency symbol!

lpFormat

To override the locale's formatting settings, pass a CURRENCYFMT structure that contains the appropriate formatting information. To use the locale's settings instead, pass 0 for this parameter.

lpCurrencyStr

String that receives the null-terminated formatted currency string. This string must have enough room to receive the string.

cchCurrency

The number of characters in the string passed as lpCurrencyStr.

Constant Definitions

Const LOCALE_SYSTEM_DEFAULT = &H400 Const LOCALE_USER_DEFAULT = &H800 Const LOCALE_NOUSEROVERRIDE = &H80000000

Example

' This code is licensed according to the terms and conditions listed here. ' Declarations and such needed for the example: ' (Copy them to the (declarations) section of a module.) Public Type CURRENCYFMT NumDigits As Long LeadingZero As Long Grouping As Long lpDecimalSep As String lpThousandSep As String NegativeOrder As Long PositiveOrder As Long lpCurrencySymbol As String End Type Public Declare Function GetCurrencyFormat Lib "kernel32.dll" Alias "GetCurrencyFormatA" _ (ByVal Locale As Long, ByVal dwFlags As Long, ByVal lpValue As String, lpFormat _ As Any, ByVal lpCurrencyStr As String, ByVal cchCurrency As Long) As Long Const LOCALE_USER_DEFAULT = &H800 ' Display the amount of $1,234,567.89 according to two formatting rules. ' 1. Use the format specified by the current user locale. ' 2. Use a custom format specified by a structure passed to the function. Dim cft As CURRENCYFMT ' custom formatting settings Dim formatted As String ' receives the formatted number strings Dim strlen As Long ' the length of the formatted string ' Display the value formatted according to the current locale. formatted = Space(256) strlen = GetCurrencyFormat(LOCALE_USER_DEFAULT, 0, "1234567.89", ByVal CLng(0), _ formatted, Len(formatted)) formatted = Left(formatted, strlen) Debug.Print "User locale format: "; formatted ' Now display according the format we specify below. With cft ' Display three digits after the decimal point (like in US gasoline prices). .NumDigits = 3 ' Display zeros after the decimal point. .LeadingZero = 1 ' Group every three digits to the left of the decimal. .Grouping = 3 ' Use a comma to as the decimal point (like they do in France and Spain). .lpDecimalSep = "," ' Likewise, use a period as the grouping separator. .lpThousandSep = "." ' For negative values, place it in parentheses and put the $ sign after the digits. .NegativeOrder = 4 ' For positive values, place the $ sign after the digits. .PositiveOrder = 1 ' Use the $ sign to represent the currency. .lpCurrencySymbol = "$" End With formatted = Space(256) strlen = GetCurrencyFormat(LOCALE_USER_DEFAULT, 0, "-1234567.89", cft, formatted, _ Len(formatted)) formatted = Left(formatted, strlen) Debug.Print "Custom format: "; formatted