Instance Settings

Customise each targetted field with the settings below (all are optional):

$(selector).calculator({showOn: 'button'});

appendText | base | buttonImage | buttonImageOnly | calculatorClass | constrainInput | cookieExpires | cookieName | cookiePath | duration | isOperator | layout | memoryAsCookie | onButton | onClose | onOpen | precision | prompt | showAnim | showFormula | showOn | showOptions | useDegrees | useThemeRoller | value

NameTypeDefaultComments
showOnstring'focus' Control when the calculator is displayed: 'focus' for only on focus of the text field, 'button' for only on clicking the trigger button, 'both' for either focus or the button, 'operator' for only when a non-numeric character is entered, or 'opbutton' for either non-numeric entry or a button.

Since 1.1.1 - added 'operator' and 'opbutton'.
buttonImagestring'' The URL of an image to use for the trigger button.
buttonImageOnlybooleanfalse Set to true to indicate that the trigger image should appear by itself and not on a button.
isOperatorfunctionnull A callback function to determine whether or not an entered character should trigger display of the calculator in 'operator' or 'opbutton' modes. The function is passed the character being typed, the corresponding key event, the current value of the input field, the current number base, and the current decimal character. By default any non-numeric character is a trigger. The example below only triggers on the basic maths operators.

$(selector).calculator({showOn: 'opbutton',
	isOperator: function(ch, event, value, base, decimalChar) {
		return '+-*/'.indexOf(ch) > -1 && !(ch === '-' && value === '');
	}});

Since 1.2.3.
showAnimstring'show' Set which animation is used to display the calculator. Choose from three standard animations: 'show', 'fadeIn', or 'slideDown', or use one of the jQuery UI effects if you include that package. For no animation use ''.

Since 1.2.4 - use '' for no animation.
showOptionsobject{} If you use one of the jQuery UI effects for the animation above, you can supply additional options for that effect via this setting.

$(selector).calculator({showAnim: 'clip',
	showOptions: {direction: 'horizontal'}});
durationstring'normal' Control the speed of the show/hide animation with this setting: 'slow', 'normal', 'fast', or a number of milliseconds.
appendTextstring'' Text that is to be appended to all affected fields, perhaps to describe the presence or purpose of the calculator.
useThemeRollerbooleanfalse Set to true to add ThemeRoller classes to the keypad to allow the calculator to integrate with other UI components using a theme.

Since 1.3.0.
calculatorClassstring'' One popup calculator is shared by all instances, so this setting allows you to apply different CSS styling by adding an extra class to the calculator for each instance.
showFormulabooleanfalse Set to true to display the formula being calculated, of false to only show the current number and result.

Since 2.0.1.
promptstring'' Text that is displayed at the top of the calculator.
layoutstring[]this. standardLayout Set the layout of the calculator by defining the keys present on each row. Use the two-character codes for each of the keys, or their equivalent constants.
valuenumber0 The initial value shown in the calculator. It only applies to inline calculators - popup calculators take their initial value from their input field.

Since 1.2.3.
basenumber10 The numeric base for values shown in the calculator. It should only be one of 2, 8, 10, or 16. Use the number base keys for controls to change this setting interactively.
precisionnumber10 The number of digits of precision to use in rounding. This value can resolve obvious rounding errors in JavaScript (e.g. 2.1 * 7), but may then affect the accuracy of other calculations. You need to strike a balance between these two requirements. Note that this setting only affects the displayed value and that the full value is retained in the calculator for further computations.

Since 1.0.1.
memoryAsCookiebooleanfalse Set to true to indicate that the memory value should be saved as a cookie and be re-initialised on page load, or false to just have it in-memory. Use the following settings to fine tune the cookie.

Since 1.3.2.
cookieNamestring'calculatorMemory' The name of the cookie to store when memoryAsCookie is true.

Since 1.3.2.
cookieExpiresnumber or Date24 * 60 * 60 The expiry period for the cookie when memoryAsCookie is true. Specify as a Date or as the number of seconds offset from now (default is one day).

Since 1.3.2.
cookiePathstring'' The path of the cookie to store when memoryAsCookie is true.

Since 1.3.2.
useDegreesbooleanfalse Set to true to indicate that values are in degrees when using trigonometric functions, or false for radians (2π per circle). Use the degrees/radians keys for controls to change this setting interactively.
constrainInputbooleantrue Indicate whether to restrict entry into the input field to numeric values only (true) or to allow anything to be typed (false).

Since 1.1.1.
onOpenfunctionnull A function that is called before a popup calculator is opened. The function receives the current field value and the calculator instance object as parameters, while this refers to the text field. The field value can be altered and will be used in the calculator. Usually this function would be used in conjunction with the onClose event.

$(selector).calculator({
	onOpen: function(value, inst) {
		$(this).val(parseFloat(value) / 100);
	}});

Since 1.2.5.
onButtonfunctionnull A function that is called when a button is activated on the calculator. The function receives the button label, the current value, and the calculator instance object as parameters, while this refers to the text field. Of course, you can still have an onchange handler for the input field itself.

$(selector).calculator({
	onButton: function(label, value, inst) {
		alert('After pressing ' + label + ' the value is ' + value);
	}});
onClosefunctionnull A function that is called when the calculator is closed. The function receives the current field value and the calculator instance object as parameters, while this refers to the text field.

$(selector).calculator({
	onClose: function(value, inst) {
		alert('Closed with value ' + value);
	}});

Regional Settings

These settings comprise the regional settings that may be localised by a language package. They can be overridden for individual instances:

$(selector).calculator({useText: 'Save'});

backspaceStatus | backspaceText | base10Status | base10Text | base16Status | base16Text | base2Status | base2Text | base8Status | base8Text | buttonStatus | buttonText | clearErrorStatus | clearErrorText | clearStatus | clearText | closeStatus | closeText | decimalChar | degreesStatus | degreesText | eraseStatus | eraseText | isRTL | memAddStatus | memAddText | memClearStatus | memClearText | memRecallStatus | memRecallText | memStoreStatus | memStoreText | memSubtractStatus | memSubtractText | radiansStatus | radiansText | useStatus | useText

NameTypeDefaultComments
decimalCharstring'.' The character to use for the decimal point.

Since 1.2.0.
buttonTextstring'...' The text to display on a trigger button for the calculator.
buttonStatusstring'Open the calculator' The description of the button's purpose, used in a tool tip.
closeTextstring'Close' The text to display for the button to close the calculator.
closeStatusstring'Close the calculator' The description of the close button's purpose, used in a tool tip.
useTextstring'Use' The text to display for the button to copy the value to the text field.
useStatusstring'Use the current value' The description of the erase button's purpose, used in a tool tip.
eraseTextstring'Erase' The text to display for the button to erase the text field.
eraseStatusstring'Erase the value from the field' The description of the erase button's purpose, used in a tool tip.
backspaceTextstring'BS' The text to display for the button to erase the last digit.
backspaceStatusstring'Erase the last digit' The description of the backspace button's purpose, used in a tool tip.
clearErrorTextstring'CE' The text to display for the button to erase the entire number. Any previous number and operation are retained.
clearErrorStatusstring'Erase the last number' The description of the clear error button's purpose, used in a tool tip.
clearTextstring'CA' The text to display for the button to reset the calculator. Any value in memory is retained.
clearStatusstring'Reset the calculator' The description of the clear button's purpose, used in a tool tip.
memClearTextstring'MC' The text to display for the button to clear the memory.
memClearStatusstring'Clear the memory' The description of the clear memory button's purpose, used in a tool tip.
memRecallTextstring'MR' The text to display for the button to recall the number in memory.
memRecallStatusstring'Recall the value from memory' The description of the recall memory button's purpose, used in a tool tip.
memStoreTextstring'MS' The text to display for the button to store the current number in memory.
memStoreStatusstring'Store the value in memory' The description of the store in memory button's purpose, used in a tool tip.
memAddTextstring'M+' The text to display for the button to add the current number to memory.
memAddStatusstring'Add to memory' The description of the add to memory button's purpose, used in a tool tip.
memSubtractTextstring'M-' The text to display for the button to subtract the current number from memory.
memSubtractStatusstring'Subtract from memory' The description of the subtract from memory button's purpose, used in a tool tip.
base2Textstring'Bin' The text to display for the button to switch to binary notation (base 2).
base2Statusstring'Switch to binary' The description of the binary button's purpose, used in a tool tip.
base8Textstring'Oct' The text to display for the button to switch to octal notation (base 8).
base8Statusstring'Switch to octal' The description of the octal button's purpose, used in a tool tip.
base10Textstring'Dec' The text to display for the button to switch to decimal notation (base 10).
base10Statusstring'Switch to decimal' The description of the decimal button's purpose, used in a tool tip.
base16Textstring'Hex' The text to display for the button to switch to hexadecimal notation (base 16).
base16Statusstring'Switch to hexadecimal' The description of the hexadecimal button's purpose, used in a tool tip.
degreesTextstring'Deg' The text to display for the button to switch to degrees for trigonometric functions.
degreesStatusstring'Switch to degrees' The description of the degrees button's purpose, used in a tool tip.
radiansTextstring'Rad' The text to display for the button to switch to radians for trigonometric functions.
radiansStatusstring'Switch to radians' The description of the radians button's purpose, used in a tool tip.
isRTLbooleanfalse Set to true to indicate that the current language flows right-to-left.

Global Settings

NameTypeDefaultComments
regionalOptionsobject[] See regional settings The set of regional settings for the calculator fields. Entries are indexed by the country/region code with '' providing the default (English) settings. Each entry is an object with the following properties: decimalChar, buttonText, buttonStatus, closeText, closeStatus, useText, useStatus, eraseText, eraseStatus, backspaceText, backspaceStatus, clearErrorText, clearErrorStatus, clearText, clearStatus, memClearText, memClearStatus, memRecallText, memRecallStatus, memStoreText, memStoreStatus, memAddText, memAddStatus, memSubtractText, memSubtractStatus, base2Text, base2Status, base8Text, base8Status, base10Text, base10Status, base16Text, base16Status, degreesText, degreesStatus, radiansText, radiansStatus, isRTL. Language packages load new entries into this array and automatically apply them as global defaults.

<script type="text/javascript"
	src="jquery.calculator-fr.js"></script>

If necessary, you can then revert to the default language settings with

$.calculator.setDefaults(
	$.calculator.regionalOptions['']);

and apply the language settings to individual fields with

$('#frenchCalculator').calculator(
	$.calculator.regionalOptions['fr']);

Check out the list of available localisation packages.

Since 1.2.0 - added decimalChar.
Since 2.0.0 - previously called regional.
standardLayoutstring[] [' BSCECA',
'_1_2_3_+@X',
'_4_5_6_-@U',
'_7_8_9_*@E',
'_0_._=_/']		 The standard layout for a basic decimal calculator. Use this with the layout field. See the key definitions for the meanings of the codes in the layout.
scientificLayoutstring[] ['@X@U@E BSCECA', 'DGRD _ MC_ _7_8_9_+', 'SNASSRLG_ MR_ _4_5_6_-', 'CSACSQLN_ MS_ _1_2_3_*', 'TNATXYEX_ M+_ _0_.+-_/', 'PIRN1X _ M-_ _%_='] A full layout for a decimal calculator with common scientific functions and memory support. Use this with the layout field. See the key definitions for the meanings of the codes in the layout.

Functions

addKeydef | destroy | disable | enable | hide | option (get) | option (set) | setDefaults | show

SignatureReturnsComments
$.calculator.setDefaults(settings)calculator object Update the default instance settings (see above) to use with all calculator instances.
$.calculator.addKeyDef( code, label, type, func, style, constant, keystroke, keyName)calculator object Add or update the definition for a key to appear on the calculator. See the key definitions for more details on the standard keys.

code (string) is the two-character code that identifies this key and can be used within a layout to denote its position. Use lower-case characters for your names to avoid conflicts with the standard keys.

label (string) is the display text that appears on the button for this key. If prefixed by a hash (#) the rest of the label is used to look up the actual text in the regional settings. For example, '#erase' looks for an 'eraseText' setting for the button text and an 'eraseStatus' setting for a popup tool-tip.

type (enumerated) denotes the type of key and must be one of the defined constants ($.calculator.): digit for digits that make up a number, binary for binary operators (need two values), unary for unary operators (only need one value), control for special control buttons, or space for empty space between buttons.

func (function) is the function to call when this key is activated. The function accepts a single parameter, being the instance settings for the calculator, and should update its state via the curValue and prevValue (for binary operations) fields. See examples on the key definitions page.

style (string) is a space-separated list of CSS styles to apply to this button. Each style is prefixed by 'calculator-' when applied.

constant (string) is the name of a constant (within $.calculator) that can be used instead of the code to position a key within a layout.

keystroke (char or number) is the character or keycode that maps onto this button for keyboard-driven calculations.

keyName (string, optional) is the name of the keystroke above (up to three characters) that is shown when the Alt is held down. This value is not needed if the keystroke is a standard character.

Since 1.0.2 - keyName added.
Since 1.2.0 - func is now a function, previously it was only function name.
$(selector).calculator('option', options)jQuery object Update the settings for the calculator instance(s) attached to the given control(s).

options (object) the collection of new settings.

$(selector).calculator('option', {showOn: 'both', useDegrees: true});

Since 1.4.0 - previously you used the 'change' command.
$(selector).calculator('option', name, value)jQuery object Update a particular setting for the calculator instance(s) attached to the given control(s).

name (string) the name of the setting to change;
value (any) the new value of that setting.

$(selector).calculator('option', 'showOn', 'both');

Since 1.4.0 - previously you used the 'change' command.
$(selector).calculator('option', name)object or any Retrieve one or all of the current settings for the first calculator instance attached to the given control(s).

name (string, optional) the name of the setting to retrieve; omit for all settings.

var settings = $(selector).calculator('option');
var showOn = $(selector).calculator('option', 'showOn');

Since 1.4.0.
$('selector').calculator('destroy')jQuery object Remove the calculator functionality from the given field(s).
$('selector').calculator('show')jQuery object Pop up the calculator for the given field.
$('selector').calculator('hide')jQuery object Hide the calculator for the given field.
$('selector').calculator('enable')jQuery object Enable the calculator for the given field(s) as well as the field itself.
$('selector').calculator('disable')jQuery object Disable the calculator for the given field(s) as well as the field itself. Note that a field that is disabled when the calculator is applied to it causes the calculator to become disabled as well.

Since 1.3.0 - automatic disabling.
$('selector').calculator('isDisabled')boolean Determine whether the calculator functionality has been disabled for the first of the given field(s).

Key Definitions

A number of standard keys are defined for use within the calculator. They may be referenced by their two-character code or their constant name when constructing a layout for the calculator. Two common layouts are defined for your use: standardLayout and scientificLayout.

Use the addKeyDef function to add or update a key definition. The functions that implement the actions operate on the calculator instance object passed in as a parameter. Examples of a binary operation (add) and a unary operation (ln) are shown below.

function add(inst) {
	inst.curValue = inst.prevValue + inst.curValue;
}

function ln(inst) {
	inst.curValue = Math.log(inst.curValue);
}
CodeLabelTypeStylesConstantKeystrokeKey name
'_0''0'digit0'0'
'_1''1'digit1'1'
'_2''2'digit2'2'
'_3''3'digit3'3'
'_4''4'digit4'4'
'_5''5'digit5'5'
'_6''6'digit6'6'
'_7''7'digit7'7'
'_8''8'digit8'8'
'_9''9'digit9'9'
'_A''A'digithex-digitA'a'
'_B''B'digithex-digitB'b'
'_C''C'digithex-digitC'c'
'_D''D'digithex-digitD'd'
'_E''E'digithex-digitE'e'
'_F''F'digithex-digitF'f'
'_.''.'digitdecimalDECIMAL'.'
'_+''+'binaryarith addADD'+'
'_-''-'binaryarith subtractSUBTRACT'-'
'_*''*'binaryarith multiplyMULTIPLY'*'
'_/''/'binaryarith divideDIVIDE'/'
'_%''%'unaryarith percentPERCENT'%'
'_=''='unaryarith equalsEQUALS'='
'+-''±'unaryarith plus-minusPLUS_MINUS'#'
'PI''pi'unarypiPI'p'
'1X''1/x'unaryfn inverseINV'i'
'LG''log'unaryfn logLOG'l'
'LN''ln'unaryfn lnLN'n'
'EX''eⁿ'unaryfn expEXP'E'
'SQ''x²'unaryfn sqrSQR'@'
'SR''√'unaryfn sqrtSQRT'!'
'XY''x^y'binaryfn powerPOWER'^'
'RN''rnd'unaryrandomRANDOM'?'
'SN''sin'unarytrig sinSIN's'
'CS''cos'unarytrig cosCOS'o'
'TN''tan'unarytrig tanTAN't'
'AS''asin'unarytrig asinASIN'S'
'AC''acos'unarytrig acosACOS'O'
'AT''atan'unarytrig atanATAN'T'
'MC''#memClear'unarymemory mem-clearMEM_CLEAR'x'
'MR''#memRecall'unarymemory mem-recallMEM_RECALL'r'
'MS''#memStore'unarymemory mem-storeMEM_STORE'm'
'M+''#memAdd'unarymemory mem-addMEM_ADD'>'
'M-''#memSubtract'unarymemory mem-subtractMEM_SUBTRACT'<'
'BB''#base2'controlbase base2BASE_2'B'
'BO''#base8'controlbase base8BASE_8'C'
'BD''#base10'controlbase base10BASE_10'D'
'BH''#base16'controlbase base16BASE_16'H'
'DG''#degrees'controlangle degreesDEGREES'G'
'RD''#radians'controlangle radiansRADIANS'R'
'BS''#backspace'controlundoUNDOBS'BSp'
'CE''#clearError'controlclear-errorCLEAR_ERRORHOME'Hom'
'CA''#clear'controlclearCLEAREND'End'
'@X''#close'controlcloseCLOSEESC'Esc'
'@U''#use'controluseUSEENTER'Ent'
'@E''#erase'controleraseERASEDEL'Del'
'  ' (two spaces)spacespaceSPACE
'_ 'spacehalf-spaceHALF_SPACE