Documentation for Skin Authors

Skins make it possible to configure the software as a normal calculator or as a currency converter (with or without calculator functions).

The existing skin files published by Cloanto are very good "learn by example" tutorials, and we recommend to have them available while reading this documentation. If you are in a hurry, we suggest that you read at least the checklist at the end of this page.

Skin Files

Skins consist of a "skin.ini" file describing the functionality and layout (position and size of active regions) of the calculator, and up to four bitmap (".bmp") files containing the graphics for the default and optional hover (mouseover), selected (pressed) and disabled (window not active) modes for buttons and other objects. Additional files are used for translucency effects and for Windows icons.

Instead of using individual bitmaps for each object (e.g. calculator buttons), like some programs do, and which can results in hundreds of bitmap files, each bitmap contains all objects for each state (all default graphics, all selected graphics, etc.) Each object is delimited by a rectangular box, which is used to determine the region responsive to mouse action, as well as the area that has to be changed from one bitmap to the other.

Skin Archives

The recommended organization for the distribution of a skin is a ZIP archive containing a directory (one directory, not nested directories) with a short name for the skin, and all skin files inside that directory. This allows the user to drag-and-drop the skin directory to the Skins directory of the software. When listing the skin names in the Skins tab, the software gives priority to the skin name indicated inside the skin.ini file ([General] section, Title key), which is not limited by filing system issues such as maximum name size and illegal characters. If the skin.ini file contains no name for the skin, then the software uses the directory name to name the skin.

In order to allow both users and site administrators to clearly recognize a skin's archive, and to differentiate between different skins, it is recommended to give the ZIP archive file the same name as that of the skin directory it contains. The name should consist of only lower case letters and digits, and have a maximum length of 21 characters (or 25 characters including suffixes). This name is not exposed in the user interface (unless the Title key is missing). For more details please refer to the checklist.

Automatic Installation

Skins can also be automatically installed by a setup program. The target directory can be determined by appending the "Skins" directory name to the path string which is stored in the system registry in the

• HKEY_CURRENT_USER\
  Software\
  Cloanto\
  programname\
  version\
  Path

subkey, where programname is the software name (e.g. "Calculator", "SkinCalc", "WorldCalc" or "Euro Calculator") and version is the program version (e.g. 3.0). A subdirectory named after the new skin should be created at this location (i.e. inside the Skins directory). The registry entry exists only if the software has been run at least once. If multiple versions of the program are installed, different subkeys may be present.

Logo Graphics

We appreciate the fact that many skin designers place a SkinCalc and/or Cloanto logo on a calculator skin, in which case we recommend to refer to the following high resolution files, which can be scaled and antialiased as appropriate.

• SkinCalc Logo (color bitmap)
• SkinCalc Logo (B&W bitmap)
• Cloanto Logo Page

Transparency and Translucency

Transparency and translucency make it possible to define areas through which the contents of other windows will show.

A transparent color can be set, allowing for non-rectangular shapes of the program window (based on transparent areas of the default bitmap). This type of transparency is supported on all versions of Windows.

Additional pairs of files specifying translucent skin data and alpha channel information are supported for each basic file. This type of transparency is supported on Windows 2000, Windows XP and higher (the additional data is not used on other systems).

Coordinates and Regions

All coordinates are expressed in pixels from the top-left edge of the Default bitmap, counting from position 0:0. Objects are referenced relative to their top left corner.

Sections, and the corresponding functional and visual objects and regions, have a top-to-bottom priority relative to their position in the skin.ini file. Overlapping regions are allowed. If the user selects a region which is shared by two objects, only the object with the highest priority is "triggered". In the same way, it is possible to define "fallback" regions, by defining objects with large rectangular areas at the end of the file. For example, in order to cause the appearance of the entire calculator to change when the program window is deselected, a [Title] object with a rectangular region as large as the Default bitmap, and with a DISABLE flag, can be placed at the end of the skin.ini file. If instead the same object were placed at the beginning of the file, it would have priority over all other objects, effectively preventing them from responding to pointer device events.

Keyboard Shortcuts

Keyboard shortcuts can be set in each skin. It is highly recommended to associate keyboard shortcuts to buttons (e.g. the key 1 for the button 1, etc.)

Have a look at the reference skins by Cloanto for sample arrangements of sections and keyboard shortcuts, including default shortcuts for calculator and unit conversion functionality (even if some keys are not visually present, standard shortcuts are always useful).

Shortcuts can also be associated to buttons which are not visually present on the skin, in which case the corresponding section consists of a single key defining the keyboard shortcut(s). For example, it is always useful to associate the BACKSPACE keyboard key to the KeyBackspace functionality, even if there is no corresponding visual object.

To assist skin authors, the special shortcut SHIFT+CTRL+F5 can be used at any time to force the software to reload the current skin INI and graphics files, and to issue warning messages describing potential issues which the software is able to automatically detect. SHIFT+CTRL+F6 can instead be used to test a skin with translucency features as it would appear on an operating system with no support for translucency.

The skin.ini File

The skin.ini file adheres to the INI format as documented in:

• Cloanto Implementation of INI File Format

The software is designed to ignore section and key names which may be implemented as part of future versions, so that future skin files can be used with older versions of the software.

Most sections (and many keys inside sections) are optional. In order to not include an object, it is sufficient (and recommended) not to include the corresponding section or key.

The sections and keys used in the skin.ini file are described in detail in the following parts.

Comments

As specified in the INI documentation, comments may appear almost anywhere in the file. We consider it helpful to place a comment such as the following at the beginning of the file:

;
; Cloanto Skin Definition File
;
;
; FOR USERS
;
; To install this skin copy the directory
; containing it into the Skins directory of
; the software. Press F1 or select Help in
; the Skins tab of the program options for
; additional information. Press F5 to
; directly open the Skins tab.
;
; Free software download and skin links are
; at www.skincalc.com.
;
;
; FOR AUTHORS
;
; Skin format documentation and checklists
; are at www.skincalc.com.
;
; Press SHIFT+CTRL+F5 to reload and test
; the skin after changes.
;
; Feel free to add your comments, notes
; and personal information to the
; [General] section of this file.
;
; Kindly submit a copy of new and updated
; skins to www.skincalc.com/submit/ for
; skin verification, official archiving
; and a free license key for the
; currency-enabled versions.
;
; Thank you!
;

[General]

The keys in the [General] section contain information about the skin and the author of the skin (not about the software, or the publisher of the software). The keys in this section are designed to make additional description files (e.g. "readme.txt") unnecessary.

All keys are optional, but it is highly recommended to define at least a Title, which is used by the software to display the name of the skin to the user.

Skin version numbers should start from "1.0", and be increased each time a new version of the same skin is released. All digits are significant as they would be in decimal numbers (e.g. a version number of 1.09 counts as being smaller than 1.8).

The ID field is not displayed. It is only used by SkinCalc to recognize different versions of the same skins when installing a skin (the name is unreliable, as different authors may pick the same name). Once you create a new skin you should use a public UUID/GUID generator to obtain a unique identifier for your skin. The identifier must remain the same even if you increase the version of the skin. SkinCalc is able to detect the newer version.

We recommend to use a simple Distribution clause such as "The unmodified skin may be freely redistributed and used", so as to allow for the skin to be included in magazine cover disks and similar collections. Clauses such as "ask me first", or "no commercial use" introduce additional overhead which may lead to the skin not being included (for example because a magazine is by definition a commercial publication, because the provided email address does not work any more, etc.)

The following example shows the use of all keys:

[General]
Title = "My First Skin"
Version = "1.0"

ID = e24e3780-c33d-11dc-a77d-0050c2490048
Author = "MyName"
HomePage = "http://www.example.com/myhomepage/"
Email = "info@example.com"
Copyright = "Copyright © 2009 MyName"
Distribution = "The unmodified skin may be freely redistributed and used"
Comment = "This is only an example. Comments may be long, very long."

[Graphics]

This section contains information about the visual appearance of the calculator by means of four bitmap files in Windows BMP format, an optional transparent color, an application icon image in Windows ICO format, and optional font files.

The objects (e.g. the calculator buttons) defined in other sections of the INI file reference regions on the four bitmaps. The regions are rectangular, but their contents, i.e. the imagery that visually changes based on a certain user actions, can be of any shape.

The Default bitmap is the only image that must always be provided. It is the image of the calculator as it appears when the program window opens. The other three bitmaps are optional. The bitmaps may either be all in true color, or all palette-based (which is more space-efficient, but limited to a maximum of 256 colors). If the bitmaps are palette-based, then only the palette of the Default bitmap is considered and applied to all other bitmaps.

While most computer displays support hi-color and true color modes, some systems can only display a maximum of 256 colors in certain resolutions. In such a case the software will remap true color bitmap data as appropriate. The resulting quality, however, will in most cases not be as good as if the skin had been designed from the ground up for that number of colors.

The Select bitmap contains alternate images that are displayed when an object on the calculator is "pressed". These alternate images are only used for objects that have the SELECT flag active. If the calculator supports memory or unit functions, then the Select bitmap must include appropriate alternate graphics for the Memory symbol and the UnitDropDown symbol. Otherwise, the Select bitmap is optional, although it is highly recommended to use this bitmap to provide a visual feedback for the selection of the various calculator buttons.

The Hover and Disable bitmaps work like Select, and are associated to the HOVER and DISABLE Graphics flags, respectively. Hover provides visual feedback for the mouse "hovering" over an object (also called "mouseover"). Regions in the Disable bitmap are used when the program window is not active, e.g. when the user selected a different window. It is standard system behavior that the calculator window is also disabled when a help tooltip is displayed, or when another program is used but the calculator is the frontmost window because of the "Always on Top" option. The Disable graphics and areas should be designed with consideration to these cases, where a calculator is disabled, but still pretty much in use. In these cases, changing the color of a few items would be fine, but having the display and keys completely disappear would probably cause confusion.

The optional TransparentColor key defines a color in the Default bitmap that is used to mark transparent regions of the program window. It is defined as a hexadecimal RRGGBB string (Red-Green-Blue values, for a total of six hexadecimal digits, e.g. 0x000000 is black, 0xFFFFFF is white, 0xFF0000 is red, etc.), introduced by "0x", which is a standard introducer to hex notation. Do not use the TransparentColor key if the graphics contain no transparent areas.

The simple "yes"/"no" transparency features enabled by TransparentColor are supported by all versions of Windows on which the software runs. Additional, more sophisticated features, are possible when the software runs on an operating system which supports translucency, such as Windows 2000, Windows XP or higher. Translucency bitmaps can be used to define different levels of "transparency", not just "on" and "off". Translucency information for each pixel is provided by a bitmap called "alpha channel". White pixels in the alpha channel bitmap correspond to complete opacity, while black pixels indicate full transparency. Intermediate values correspond to intermediate levels of translucency. Alpha channel bitmaps are ignored on operating systems which do not support translucency. If an alpha channel bitmap is present and the operating system supports translucency, the software checks whether a specific set of Translucent graphics exists for use with translucency, or otherwise it applies the alpha channel to the default graphics.

For full control over translucency features, the Default, Select, Hover and Disable keys also come in Translucent (e.g. DefaultTranslucent) and Alpha (e.g. DefaultAlpha) variants. Each Translucent bitmap, if used, must be paired with a corresponding Alpha bitmap. An Alpha bitmap can also be used without the corresponding Translucent entry, in which case, if the operating system supports translucency, the Alpha bitmap is applied to the "regular" bitmap. Translucent and Alpha bitmaps are ignored if the operating system does not support translucency, or on versions of the software prior to 3.0, or when the current skin is reloaded with the SHIFT+CTRL+F6 key combination (which is similar to SHIFT+CTRL+F5, only that it forces testing of the skin as if translucency was not available). It should be noted that completely translucent (i.e. invisible) areas in a skin (i.e. areas for which the alpha channel region is defined by completely black pixels) cannot be clicked on by the user, i.e. any attempts to select that region with the mouse would result in the selection of the underlying window, if present.

For example, a skin may have a Default bitmap and a DefaultAlpha bitmap. On Windows 95 only the data provided by the Default bitmap would be used. On Windows 2000, the alpha channel information found in DefaultAlpha would be applied to the Default bitmap. In some cases it is desirable to create slightly different  bitmaps for use with and without translucency (e.g. to introduce an additional shadow effect). If in our example a third bitmap, defined with the DefaultTranslucent key, existed, the software would use Default on Windows 95, and DefaultTranslucent (ignoring Default) on Windows 2000, so that the alpha channel information would be applied to DefaultTranslucent instead of Default.

The icon file defined with the Icon key determines the image to be used on the toolbar when the software is in use or minimized, as well as on window titles and in the ALT+TAB selection window. If no icon file is provided, the built-in default icon is used. The IconTrayActive and IconTrayInactive keys are used to further define different icons to appear in the system tray area, when the software is active (in use, in the background, or minimized) or inactive (not running).

The Fonts key can be used to make available (without installing on the system) one or more fonts that are provided with the calculator (e.g. to achieve an LCD-like effect). The fonts are temporarily copied to the system only if not already present. On Windows 2000 and newer versions of Windows the font is made available only to the calculator application, and is invisible to other applications and users (unless installed by the user). On previous versions of Windows the font is installed when the calculator is launched, and remains available to the entire system until the current skin is no longer used. The use of TrueType (TTF) fonts is recommended for maximum compatibility across different versions of Windows. Type 1 fonts (consisting of multiple files, usually .pfm and .pfb) are supported by the software, but may not be supported by older operating systems. On Windows 2000 and newer versions of Windows it is possible to chain multiple files belonging to the same Type 1 (or other format) font by using the vertical bar ("|") to separate their file names.

Example:

[Graphics]
Default = "default.bmp"
DefaultTranslucent = "defaultt.bmp"
DefaultAlpha = "defaulta.bmp"
Disable = "disable.bmp"
DisableTranslucent = "disablet.bmp"
DisableAlpha = "disablea.bmp"
Select = "select.bmp"
SelectTranslucent = "selectt.bmp"
SelectAlpha = "selecta.bmp"
Hover = "hover.bmp"
HoverTranslucent = "hovert.bmp"
HoverAlpha = "hovera.bmp"
Icon = "icon.ico"
IconTrayActive = "iconta.ico"
IconTrayInactive = "iconti.ico"
TransparentColor = 0x008080
Fonts = "fonts\lcd.ttf", "fonts\thermal.ttf","multiexample.pfm|multiexample.pfb"

[DisplayFont]
[Display2Font]
[UnitFont]
[Unit2Font]
[LastUpdateFont]

These sections respectively define the fonts to be used for the display digits, the unit indicator and the last update text.

The font Name should preferably refer to a font that is present on all versions of Windows, such as "Arial", "Courier New", "Times New Roman", "Symbol", "Wingdings", "Marlett", "Small Fonts", "MS Serif" and "MS Sans Serif".

The Height and optional Width keys indicate the font size and X:Y ratio. Characters may be "stretched" by changing the value of Width. A Width of 0 is the same as no Width key, and indicates that the default ratio should be used. To test the unit indicator, which should contain even the largest three-character strings without cutting them, try and define a fictitious currency named "MMM" (or "@@@"), and select it. If the unit indication is cut, use Width to adjust the character width by forcing it to be a certain size.

Weight indicates the "weight" of the font. The following table lists the effect of various weigh values on the font style.

Italic and Underline are 0/1 flags.

The Color values are expressed as hexadecimal RRGGBB values, and are used in the same cases described for the Default, Select, Hover and Disable bitmaps of the [Graphics] section. In order for the alternate colors to be used, the corresponding Graphics flags must be set in the [Display] and [Unit] sections. The default text Alignment is RIGHT, VCENTER (relative to the [Display] and [Unit] elements) and can be modified as explained for the [DisplayMenu] and [UnitMenu] sections.

The Alpha values (DefaultAlpha, SelectAlpha, HoverAlpha and DisableAlpha keys), in which 0x00 indicates complete translucency and 0xFF indicates complete opacity, are the font equivalent of the alpha channel information which can be used for the skin bitmaps. If no Alpha keys are used, then the font inherits the translucency of the bitmap on which it appears.

[Display2Font] and [Unit2Font] are used only with dual display skins.

[LastUpdateFont] only has Default and Disabled attributes (Hover and Select are not used).

For best results, skin authors may want to advise users to enable the "Smooth edges of screen fonts" setting in the Display Properties (ClearType should however be disabled when grabbing screens, e.g. for use on skin download sites).

Example:

[DisplayFont]
Name = "Arial"
Height = 18
Width = 7
Weight = 700
Italic = 0
Underline = 0
Alignment = RIGHT, VCENTER
DefaultColor = 0x000000
SelectColor = 0xFFFFFF
HoverColor = 0xFFFFFF
DisableColor = 0x090909
DefaultAlpha = 0xFF

[DisplayMenu]
[Display2Menu]
[UnitMenu]
[Unit2Menu]
[SkinMenu]

These sections define the position and alignment of the program menus. This is where and how the menus appear as a response of user action, and not where the user has to click in order for the menus to appear.

[Display2Menu] and [Unit2Menu] are used only with dual display skins.

Left and Top define two coordinates which are used based on the selected Alignment flags.

If the LEFT flag is set, the menu is positioned so that its left side is aligned with the coordinate specified by the Left parameter.

If the RIGHT flag is set, the menu is positioned so that its right side is aligned with the coordinate specified by the Left parameter.

If the BOTTOM flag is set, the menu is positioned so that its bottom side is aligned with the coordinate specified by the Top parameter. The menu opens upwards.

If the TOP flag is set, the menu is positioned so that its top side is aligned with the coordinate specified by the Top parameter.  The menu opens downwards.

If the CENTER flag is set,  the menu is centered horizontally relative to the coordinate specified by the Left parameter.

If the VCENTER flag is set, the menu is centered vertically relative to the coordinate specified by the Top parameter.

Example:

[DisplayMenu]
Left = 108
Top = 22
Alignment = LEFT, TOP

[Title]

The Title section makes it possible to define one or more active regions which have a purely graphical, but no functional, purpose. The regions respond to SELECT, HOVER and DISABLE actions, as specified by the Graphics key. To define multiple regions it is sufficient to include multiple corresponding [Title] sections.

The Left, Top, Width and Height keys define the region which is responsive to user events (mouse hover and click), as well as the corresponding areas in the alternate bitmaps.

Example:

[Title]
Left = 68
Top = 10
Width = 75
Height = 13
Graphics = DISABLE

[DisplayHighlight]
[Display2Highlight]

These sections are used on calculators with two displays, in order to highlight activity on one of the two displays.

Multiple regions can be defined by including multiple corresponding [DisplayHighlight] or [Display2Highlight] sections. For example, to create a rectangular border effect around a display, four adjacent regions would be defined.

The Left, Top, Width and Height keys define the corresponding areas in the various skin bitmaps.

Example:

[DisplayHighlight]
Left = 14
Top = 68
Width = 229
Height = 4
Graphics = SELECT, HOVER, DISABLE

[DisplayHighlight]
Left = 14
Top = 95
Width = 229
Height = 4
Graphics = SELECT, HOVER, DISABLE

[DisplayHighlight]
Left = 14
Top = 72
Width = 4
Height = 23
Graphics = SELECT, HOVER, DISABLE

[DisplayHighlight]
Left = 239
Top = 72
Width = 4
Height = 23
Graphics = SELECT, HOVER, DISABLE

[Display2Highlight]
Left = 14
Top = 37
Width = 229
Height = 4
Graphics = SELECT, HOVER, DISABLE

[Display2Highlight]
Left = 14
Top = 64
Width = 229
Height = 4
Graphics = SELECT, HOVER, DISABLE

[Display2Highlight]
Left = 14
Top = 41
Width = 4
Height = 23
Graphics = SELECT, HOVER, DISABLE

[Display2Highlight]
Left = 239
Top = 41
Width = 4
Height = 23
Graphics = SELECT, HOVER, DISABLE

[Link]

This section defines a region associated to a hyperlink function which opens the homepage of the software.

In the standard version of the software the link always points to the software homepage. In custom versions of the software, links that point to a client's website (as specified in "custom.ini") are possible.

Additional [Link] sections are possible in custom versions of the software. These links must include an additional URL key to specify the target address. The URL key is ignored in the first [Link] section, and in non-custom versions of the software.

Example:

[Link]
Left = 10
Top = 8
Width = 56
Height = 17
Graphics = DISABLE, HOVER

[Banner]

This section defines an optional region inside the calculator object which is available to contain a possible banner. This information is ignored by calculators which do not use banners. When no banner is displayed, the normal calculator skin is displayed in the banner area.

SkinCalc and Euro Calculator do not use banners, however the unregistered version of WorldCalc may access banner-supported exchange rate data feeds. In this case, the banners have a size of 234x60. Custom calculators created with Calculator Builder may also use banners.

The Left, Top, Width and Height keys define the position and size of the supported banner container region. If the software requires a banner, then the supported banner region size set in the skin must exactly match the required size set in the software. If the software requires a banner, an error message is displayed if the skin does not contain a banner region, or if the size of the region does not match the size set in the software. The skin can contain information about how to position banners of different sizes, if such a banner is ever received, however it must explicitly support the required size.

When the calculator receives a banner, it receives information about the container region size, and a banner object (e.g. a GIF, JPEG or Flash file). The Alignment key specifies how the banner container should be positioned if it is not the same size as the designated skin region. The banner container covers the skin with an area drawn in the color set by the BackgroundColor key. This area is normally completely covered by the banner itself. The area may be visible in special circumstances, e.g. if a GIF banner with transparency is used, or if a Flash banner cannot be scaled to the container region size without distorting the content, in which case it will be scaled only to the container width or height, but not to both.

Example:

[Banner]
Left = 40
Top = 220
Width = 234
Height = 60
Alignment = LEFT, TOP
BackgroundColor = 0xFFFFFF

[Memory]

This section defines the region where a symbol is to be displayed to indicate that the calculator memory is not empty (usually an "M" symbol). The alternate graphics is taken from the Select bitmap.

For calculators with two displays, the recommended placing of the memory symbol is in the first display.

Example:

[Memory]
Left = 47
Top = 35
Width = 6
Height = 6

[Display]
[Display2]
[Unit]
[Unit2]
[LastUpdate]

These sections define the position and size of the containers for the display digits, for the unit indicator, and for the last update information field, respectively. The [Unit] and the [LastUpdate] sections are optional, but the Display section must be included.

[Display2] and [Unit2] are used only with dual display skins.

On skins with dual display the Select bitmap is used to indicate the current display, while the Hover bitmap reflects user action over one of the displays. The Display, Unit and DisplayHighlight regions of a skin are grouped as one when rendering Select and Hover bitmap effects, and the same is true for the Display2, Unit2 and Display2Highlight. The SELECT and HOVER status of the Display (or Display2) region also propagates to the corresponding Unit (or Unit2) and DisplayHighlight (or Display2Highlight) regions, if present, and vice versa. For example, if the user clicks on the first display of a calculator using these different regions, then the Select bitmaps of the Display, Unit and DisplayHighlight are rendered simultaneously.

An optional Unit key can be used in the [Unit] and [Unit2] sections to set a given unit, which cannot be changed by the user. For example, on a dual display "euro calculator" intended for limited local distribution one of the two units could be hard-coded to EUR, and the other to the local euro subunit.

By default, a menu is displayed when the user clicks the units or display region. An optional NoMenu Boolean key can be used in the [Display], [Display2], [Unit] and [Unit2] sections in order to prevent the menu from being displayed. For the units menu, this is useful when the skin makes available other means to select a unit (e.g. radio buttons), while for the application menu this feature is useful when a "Menu" button is provided on the skin.

The Shortcuts field is used to provide shortcut information in the context help for these three items, but otherwise it has no functional effect. It should be set to the same Shortcuts value used in the [DisplayDropDown], [UnitDropDown] and [KeyUpdateNow] sections, respectively. Please refer to the following sections for additional information about keyboard shortcuts.

Example:

[Display]
Left = 57
Top = 36
Width = 133
Height = 22
Shortcuts = RIGHT ARROW

Introduction to Buttons (Calculator Keys)

The software equivalents of the keys or buttons of a real-world calculator are referred to as buttons. We are not calling them keys, in order to avoid confusion with the key entries of the INI file (which is divided into sections and keys).

In the skin.ini file, each button has its own INI section, with the button name in square brackets. The following INI keys are used for all button sections:

• Left
• Top
• Width
• Height
• Graphics
• Shortcuts

The Left and Top keys define the position of the top left edge of the object, counting from 0:0 being the top left edge of the calculator window. Width and Height define the size of the "bounding box", which reacts to mouse action and to which alternate graphics from other bitmaps (as indicated by the Graphics flags) may be applied.

Three mutually-exclusive Graphics flags that can be set are SELECT, DISABLE and HOVER, each activating alternate regions in the corresponding bitmap.

An optional RADIO flag can be used in the Graphics key of the KeyConvertTo section to leave the button in a visually "pushed" position (using data from the Select bitmap) until another KeyConvertTo button is pressed. If no RADIO flag is selected, then the user can repeatedly press a KeyConvertTo button to change to and from the specified unit.

An optional TOOLTIP flag can be used in the Graphics key of all buttons. This flag enables the display of help tooltips. The TOOLTIP flag may also be accompanied by a Tooltip key, followed by a language code (ISO 639-1) and text (use "\r\n" to wrap long texts into lines), to replace the internal default help text for that item.

Example:

[KeyUpdateNow]
Left = 57
Top = 36
Width = 133
Height = 22
Graphics = SELECT, HOVER, DISABLE, TOOLTIP
Tooltip = "en", "Line 1.\r\nLine 2."

The Shortcuts key is used to assign one or more keyboard shortcuts. The keyboard names used to assign shortcuts to objects follow the naming specified in:

• Input Device Action Names Used in Cloanto Software

Multiple shortcuts should preferably be set using the same Shortcuts key, using comma-separated string values as outlined in:

• Cloanto Implementation of INI File Format

It is recommended to associate keyboard shortcuts to all buttons. If no shortcut is defined for a button, then the button will not respond to keyboard action. This can become especially annoying for buttons commonly accessed through the numerical keypad.

A button does not need to be visually present on the calculator interface, i.e. it can have only a keyboard shortcut, if so desired. In this case the corresponding section should contain only the Shortcuts key. It is recommended to assign shortcuts to functions even if they have no visual equivalent. The skins released by Cloanto (e.g. Silver and Gold) should be used as an example of "standard" keyboard shortcuts. Shortcuts for hexadecimal digits A to F should only be implemented if the calculator supports the Units indication and menu.

If any of the currency unit conversion features are implemented, then it is recommended that the default/select images for the unit drop down symbol (a triangle, in many of the Cloanto skins) are drawn in such a way that the symbol flashes during an update (e.g. Update Now).

The following is a list of all available buttons. For additional help, please refer to the context help of the software.

[DisplayDropDown]
[Display2DropDown]
[UnitDropDown]
[Unit2DropDown]
[SkinDropDown]

These sections are good examples of buttons that can be designed and placed in different positions, even inside the display. In the Silver skin, for example, the DisplayDropDown and UnitDropDown buttons are rendered as arrow symbols inside the display. In the Gold skin, the DisplayDropDown button is represented by a menu button.

The UnitDropDown and SkinDropDown buttons are optional. DisplayDropDown may also be omitted, but remains available by clicking the display.

If the calculator supports Units, then the UnitDropDown symbol should be designed in such a way that the symbol "flashes" during exchange rate updates. This is done by making sure that the Default and Select bitmaps are different (see the Gold skin for a good example).

[Display2DropDown] and [Unit2DropDown] are used only with dual display skins.

[KeyHelp]
[KeyMinimize]
[KeyClose]

These are standard Windows application buttons, which we recommend to implement in a recognizable way in all calculator skins.

KeyMinimize minimizes the calculator window.

ALT+F4 always closes the calculator window even if the [KeyClose] section is omitted, or has a different type of shortcut assigned.

[KeyMemoryClear]
[KeyMemoryRecall]
[KeyMemorySet]
[KeyMemoryAdd]

These are standard memory functions, usually implemented as the full set of four buttons, or without KeyMemoryClear (which is a less-used function, that can be replaced by pressing first Clear and then MemorySet).

[Key0..Key9]

These are the number buttons, which should have shortcuts "0" to "9". Please refer to existing skins or to "real" calculators or computer numerical keypads for additional layout references. Remember that this is a calculator, not a telephone: in unusual layouts the 0 key should preferably appear before 1, and not after 9!

[KeyA..KeyF]

The KeyA to KeyF buttons are used to enter digits in hexadecimal notation ("HEX" mode). Even if no graphical buttons have been defined, it is recommended to assign the corresponding keyboard shortcuts to the letters A to F. Do not implement these shortcuts in a calculator that does not have both the unit indicator and the unit menu.

[KeyDecimal]

This is the "decimal point" button. In order for the keyboard shortcut for this function to work on all localized keyboards, the shortcut should be set to both PERIOD and COMMA.

[KeyChangeSign]
[KeyDivide]
[KeyMultiply]
[KeySubtract]
[KeyAdd]
[KeyPercent]
[KeySquareRoot]
[KeySquare]
[KeyReciprocal]
[Key00]
[Key000]
[KeyEqual]

These are standard calculator functions, which can be implemented in any combination, or not at all (e.g. in a pure currency converter, with no currency conversion functionality). For additional information, select any skin that implements these, and press F1 followed by the button.

[KeyAnd]
[KeyOr]
[KeyNot]
[KeyXor]
[KeyLsh]
[KeyRsh]

These are standard logical operators (bitwise AND, OR, etc.), recommended for use in combination with skins supporting base conversions. All operators truncate the decimal portion of a number before performing a bitwise operation. For KeyLsh and KeyRsh, the second operand indicates by how many binary positions the number is to be shifted to the left or right (e.g. F00 LSH 4 = F000).

[KeyBackspace]

This function clears the last digit which is displayed, and is usually always implemented at least as a keyboard shortcut, if not as a graphical button.

[KeyClear] and [KeyClearAll]

The KeyClear and KeyClearAll buttons respectively clear the displayed value or reset the entire calculation. KeyClear can be pressed twice to achieve the same effect as a single KeyClearAll. "C" (Clear) and "CE" (Clear Entry) are often used on calculator buttons for KeyClear, and "CA" (Clear All) is used for the functionality provided by KeyClearAll. If using a single KeyClear button, we recommend marking it with a generic "C", that can be pressed either once or twice to achieve the different effects.

[KeyConvertTo]

In the [KeyConvertTo] section, the Unit key is used to assign a specific unit (e.g. a currency unit) to the button. The value can be either a three-letter currency code, or a longer custom code, currently reserved for future use. Multiple KeyConvertTo buttons can for example be used for different currency units, one for each available currency.

An optional RADIO flag can be used in the Graphics key to leave the button in a visually "pushed" position (using data from the Select bitmap) until another KeyConvertTo button is pressed. If no RADIO flag is selected, then the user can repeatedly press a KeyConvertTo button to change to and from the specified unit.

[KeyEuro]

This section is equivalent to [KeyConvertTo] with Unit is set to EUR, and no RADIO Graphics flag.

[KeyPreviousUnit] and [KeyNextUnit]

These two buttons can be used to select a unit from the list of units as it appears in the Unit menu. If the unit indicator is supported by the skin, it is recommended to at least implement the keyboard shortcuts for these two sections, assigning them UP ARROW and DOWN ARROW, respectively.

The equivalent mouse wheel selection method is hard-coded.

[KeyConvert]

This button converts the displayed value from the selected unit to the previous one. It is a good generic button to convert between the most frequently used units, and for this reason usually has the "important" shortcut of SPACEBAR.

[KeyConstant]

This section uses a Value key to assign a constant value to the key (e.g. 3.14159265...)

[KeyDivideBy] and [KeyMultiplyBy]

The [KeyMultiplyBy] and [KeyDivideBy] sections have a Value key, used to indicate a constant value by which the number on the display should be multiplied or divided. Multiple buttons can be used, for example to add or remove different rates of VAT from a price.

[KeyOptions] and [KeySkins]

These sections make it possible to quickly access the calculator options and to directly open the Skins tab of the options. For consistency, it is recommended to include at least the default keyboard shortcuts (F4 and F5) in every skin:

[KeyOptions]
Shortcuts = F4

[KeySkins]
Shortcuts = F5

[KeyUpdateNow]

This section makes it possible to invoke a currency exchange rate data update, in calculators which support this functionality. This button is best placed next to the LastUpdate text.

Checklist

Before releasing a skin, you may want to double-check the following details.

For the naming and structure of files, directories and ZIP archives:

• The skin title which the user sees is read from the skin.ini file ([General] section, Title key). There are no restrictions on this name, other than some common sense considerations about the use of unlicensed third-party trademarks (e.g. computer and OS brands), which should be avoided.
• After you decide the skin title, choose a short name which resembles as much as possible the title, but which consists of only lower case characters (a-z) and digits (0-9). Spaces and all other characters should be stripped. For example, if the title is "My First Skin", the recommended short name would be "myfirstskin". Make sure that the name is not already present in the skin archive. The maximum length of the short name should be 21 characters (25 characters including suffix). If the short name ends in "calc", you can remove that part. If the short name includes a trademark (e.g. a computer brand), we recommend that you remove or shorten it.
• Use the short name for the ZIP archive (e.g. shortname.zip), for the directory inside the ZIP archive (e.g. shortname), and for the screenshots (shortname.png and shortname.jpg).
• For all other files (bitmaps, icons, etc.), the use of lower case characters is recommend over mixed case. Space characters should not be used.
• Inside the ZIP archive, skin files should be stored inside a directory named after the skin's short name (just one directory, not multiple levels). This helps users when they install the skin. It also makes sure that both users and skin collection compilers use the directory names that you prefer.
• The optional Copyright data should follow the format "Copyright © Year(s) YourName"
• The optional Comment data (one or more sentences) should end with a period.
• If the standard keys in the [General] section are not sufficient to cover your needs, you can add a readme.txt file, but try to avoid using it for information which normally has a place in skin.ini. If you would like to refer to a license such as GPL, you can add a file named license.txt, and/or link to it by reference in the Distribution information.

For all skins:

• Press SHIFT+CTRL+F5 to reload the skin, and see if the software issues any warning or error messages.
• Even if some keys are not visually present, standard shortcuts are always useful. The [KeyOptions] and [KeySkins] sections with keyboard shortcuts (F4 and F5 keys) should always be included.
• Do all buttons have keyboard shortcuts, and have all keyboard shortcuts been tested?
• If the calculator supports memory functions, is a Select bitmap included, and does it have the appropriate "M" symbol ([Memory] section)?
• Have all mouseover and selection states been tested? Does the calculator "look good" when it is "Always on top", but not selected, or when a help tooltip is displayed?
• Are the positions of the two menus appropriate? (They can and should be set on a skin-by-skin basis, rather than opening at the default position.)
• Have all unused sections, keys and Graphics flags and bitmaps been removed?
• Does the skin have visual KeyHelp, KeyMinimize and KeyClose objects? These are recommended, and especially KeyClose should never be left out.
• In particular, if the skin does not use transparency, has the TransparentColor key been removed? Don't set the transparent color to an unused color, but remove the entire entry instead.

If the skin (counting all different bitmaps) uses no more than 256 different colors:

• Have the bitmaps been saved as palette-based BMP files, rather than the more memory consuming true color BMP format?
• Do all bitmaps use the same color palette? (The software only considers the palette of the Default bitmap.)

If the skin includes translucency features:

• Press SHIFT+CTRL+F5 to reload the skin on an operating system which supports translucency (e.g. Windows 2000, Windows XP or Windows Server 2003), and see if the software issues any warning or error messages.
• Repeat with SHIFT+CTRL+F6 (forces non-translucency mode, which is equivalent to testing on an older operating system).

If the skins supports the Unit indication on the display:

• Be open minded about the possible uses of the Unit indicator and menu: the same field can be used both for currency units and to indicate "DEC", "HEX", "OCT" and "BIN" notation.
• Try and define a fictitious currency named "MMM", and select it. Does it fit properly in the Unit display? If not, adjust the position and size settings of the Unit container and font.
• Make sure that the KeyA to KeyF sections are used to define the keyboard shortcuts A to F, and that these keys are not used for other functions. These six keys are used for hexadecimal notation.
• Does the unit drop-down symbol flash properly while the currencies are being updated (e.g. with "Update Now")? This is done in the Select bitmap.

If the skin does not have a unit indication field in the display:

• Some sections are best completely removed. Search for the strings "Unit", "Convert" and "Euro" in the INI file, and make sure that the Unit, UnitFont, UnitMenu, UnitDropDown, KeyConvertTo, KeyEuro, KeyPreviousUnit, KeyNextUnit and KeyConvert sections are completely removed. The user would have no way of knowing what the unit is, if a unit other than the default was selected by mistake (e.g. with a keyboard shortcut).

• For the same reason, do not use sections KeyA to KeyF.

If the skin features two displays:

• The Unit indicator must be supported in both displays.
• The active display should easily be recognizable via an appropriate use of the DisplayHighlight and Display2Highlight elements.

If the skin is to be compatible with Euro Calculator, which is a currency-enabled calculator with specific support for the euro currency:

• The Unit indicator must be supported.
• The KeyEuro section must be included. If it is not included as a graphical button, it should at least reference the U and EURO keyboard shortcuts.

If the skin is to be compatible with WorldCalc, which is a currency-enabled calculator which can access banner-sponsored exchange rate data:

• The Unit indicator must be supported.
• The KeyConvertTo and KeyEuro sections should be included.

• Does the skin include a Banner section supporting a possible 234x60 banner?