GRAFFITICURRENCYFIELD - GRAFFITISUITE DOCS

# GraffitiCurrencyField Class Inherits GraffitiWebUIControl ## About A powerful field for allowing users to enter formatted and validated currency values. ## Compatibility ### Framework API Version | 1.0 | 2.0 | | :---: | :---: | | True | True | ### Web | 32-Bit | 64-Bit | | :---: | :---: | | True | True | ## Enumerations | Name | Value | Description | | --- | :---: | --- | | RoundingMethods | HalfUpSymmetric HalfUpAsymmetric HalfDownSymmetric HalfDownAsymmetric HalfEven AwayFromZero TowardZero ToCeiling ToFloor Nearest Up Down | Supported value rounding methods. | | States | Unvalidated Valid Invalid | Supported validation states. | | SymbolLocations | Prefix Suffix | Supported currency symbol locations. | ## Event Definitions | Name | Parameters | Return Type | Description | | --- | :---: | :---: | --- | | GotFocus | (None) | (None) | (None) | | LostFocus | (None) | (None) | (None) | | Open | (None) | (None) | (None) | | Shown | (None) | (None) | (None) | | TextChanged | (None) | (None) | This event is fired when the text of the field is changed ( IE : when a date or range is selected in the popup). | ## Methods | Name | Parameters | Return Type | Description | | --- | :---: | :---: | --- | | Clear | (None) | (None) | Resets the value. | | FromLocale | value as locale = nil | (None) | Fills DecimalChar, ThousandsSep, and CurrencySymbol properties from the provided Xojo Locale object. If Value = Nil then the coontrol will attempt to use the current Session locale. If that fails, the current server locale will be used. | ## Properties | Name | Type | Default Value | Description | | --- | :---: | :---: | --- | | Alignment | TextAlignments | (None) | Text alignment. | | BracketNegatives | String | (None) | Determines the display format of negative numbers: (###,###) [###,###] {###,###} <###,###> | | Caption | String | (None) | Label caption. | | CurrencySymbol | String | (None) | The symbol displayed for the currency such as: $ USD EUR | | DecimalChar | String | (None) | The character used to denote the decimal position. | | DecimalCharAlternate | String | (None) | Alternate character for decimal designation in addition to DecimalChar. | | DecimalPlaces | Integer | (None) | Number of decimal places to display. | | DetectLocale | Boolean | (None) | When True, will use the detected locale of the user's browser. | | Enabled | Boolean | (None) | (None) | | GroupCount | Integer | (None) | Amount of numbers in each group, separated by the ThousandsSep. | | MaximumValue | Double | (None) | The maximum possible value the field allows. | | MinimumValue | Double | (None) | The minimum possible value the field allows. | | NegativeSignCharacter | String | (None) | Character used to denote negative numbers. | | PadDecimal | Boolean | (None) | Determines whether the decimal places will always be shown regardless of whether there is any decimal value to display. | | ReadOnly | Boolean | (None) | When True the user cannot edit the display, but the control appears enabled. | | RoundingStyle | RoundingMethods | (None) | S = Round Half Up Symmetrical A = Round Half Up Asymmetrical s = Round Half Down Symmetrical a = Round Half Down Asymmetrical B = Round Half Even U = Round Up D = Round Down C = Round to Ceiling F = Round to Floor | | State | States | (None) | Alters the control's display to convey a validation state. | | SymbolPlacement | SymbolLocations | (None) | Determines placement of the currency symbol: p = Prefix s = Suffix | | ThousandsSep | String | (None) | The character used for separating groups of thousands. | | Value | Double | (None) | The double value of the display. | | ValueString | String | (None) | Returns the current formatted value in the display. | ## Notes ### Rounding Methods #### Note that most rounding functions occur at the maximum decimal value place. You should thoroughly test rounding methods for the desired result before making your application available in production. #### HalfUpSymmetric (default) The most common method of rounding numbers is through the Round Half Up technique. This means that any decimal place .5 and above go up. Here’s a quick example: * 1.4 rounds down to 1 * 1.5 rounds up to 2 * 1.6 rounds up to 2 .5 is the marker here for the Round Up method, and any number with a decimal of .5 or higher will be rounded up to the next number. Now, when it comes to negative numbers, up by definition means going somewhere positive. So, -2 is considered higher than -3. Here’s what we mean: * -1.4 rounds up to -1 * -1.5 rounds up to -1 (because -1 is “upper” than -2) * -1.6 rounds down to -2 The opposite of this falls down to the Round Half Down method, which you’ll see below. #### HalfUpAsymmetric Similar to the Symmetric method, except negatives will round toward negative infinitity rather than positive infinity. #### HalfDownSymmetric Round Half Down is the second most common way to round numbers. Instead of .5 being the market for going up, instead, it’s the marker for numbers to go down. This should help you out: * 1.4 rounds down to 1 * 1.5 rounds down to 1 * 1.6 rounds up to 2 As you can see, the .5 decimal here was rounded down to 1 instead of the previous method, which rounded it up to 2. Again, when it comes to negative numbers, the same thing applies. We’re still going in the positive direction, but any number with a .5 decimal will round down to a higher negative value. Here’s the idea: * -1.4 rounds up to -1 * -1.5 rounds down to -2 (because -2 is a “lower” than -1, rounding down to a higher negative value) * -1.6 rounds down to -2 #### HalfDownAsymmetric Similar to the Symmetric method, except negatives will round toward positive infinitity rather than negative infinity. #### Round-Half-Even "Bankers Rounding" Rounding half to even is a brilliantly simple solution for such a compelling problem. This is how banks round numbers, and the principle behind it is simple. Every number without a .5 rounds to the nearest number as normal, but numbers with .5 round to the nearest even number. Here’s an example: * 5.5 rounds up to 6 (because 6 is closer to 5.5 than 4) * 4.5 rounds down to 4 (because 4 is closer to 4.5 than 6) The opposite of this, of course, is the next method. #### HalfEven Of course, rounding positive and negative numbers need their own set of rules. Rounding half away from zero is a rounding method that rounds .5 and -.5 away from zero. Like this: * 5.5 rounds up to 6 (because 6 is farther than 5 from 0) * -5.5 rounds down to -6 (because -6 is farther than -5 from 0) #### AwayFromZero Always rounds the result away from 0 Here’s an example: * 5.5 rounds up to 6 * -5.5 rounds down to -6 #### TowardZero Always rounds the result toward 0 Here’s an example: * 5.5 rounds down to 5 (because 5 is closer than 6 to 0) * -5.5 rounds up to -5 (because -5 is closer than -6 to 0) #### Nearest Always rounds to the nearest point. #### Up Always rounds up. #### Down Always rounds down. #### ToFloor and ToCeiling Floor and ceiling are common terms in the programming and software engineering industry. Floor simply means that every number with a decimal is always rounded down. Take this for example: * 7.4 rounds down to 7 * 7.5 rounds down to 7 * 7.6 rounds down to 7 * 7.9999 rounds down to 7 Ceiling, on the other hand, is the exact opposite, where every number is always rounded up. Like this: * 7.6 rounds up to 8 * 7.5 rounds up to 8 * 7.4 rounds up to 8 * 7.1111 rounds up to 8 #### References * [AutoNumeric.js](https://www.decorplanit.com/plugin/) * [Wayback Machine: Rounding Methods](https://web.archive.org/web/20210422180136/https://www.diycalculator.com/popup-m-round.shtml)