Dokumentation: batskin.ini    [Stand: 25.10.2004]

Regarding "batskin.ini" - there is a possibility, that current file format
will be significantly changed, due to continued work in progress on the whole
GUI system of program. At least a possibility to select different icon sets from
available files using Options/Preferences is planned.

For now the file is following these rules:

-----------------------------------------------------------
The format is a "generic" Windows .ini file with some required sections
(the description of a generic windows .ini file could be acquired separately).
Program scans the file for these sections and parses their data accordingly.

Required sections and their contents are:

[bitmaps]
Bitmap<n>=<filename1>[,[<filename2>][,[[CropX][,[CropY][,[CropWidth][,[CropHeight]]]]]]]

the file (batskin.ini further will be called "the file") must contain at least one
such section, otherwise it could be of no sence to use it.
bitmap in the context of the file is a picture which may contain from one to many
"glyphs" (separate icons or "pictures in the picture") of the same or different
sizes, their locations could be any desired by the file creator.
<n>  code of bitmap is a number in range 0..X (X should be reasonable)
     number must be unique for this section.
filename1 - hicolor interface mode file with glyph graphics. supported formats are
     JPEG, PNG, BMP. PNG or BMP with full range alpha range (8-bit alpha) are
     preffered and fully used for image alpha-blending. JPEGs, 8bit (and lower) BMPS,
     256 color PNGs are supported in a transparency limited mode. pixel at (0,0)
     defines "KeyColor" - a color which is not drawn and is used as a picture mask
     (usually it is a magenta, for example, but could be any - if you make it as a
     used color in your glyphs, you'll have "holes"!).
filename2 - 16-color mode version of glyphs (HiColor Images checkbox is off in
Options/Preferences)
     must be of the same size with picture in the filename1.
     only BMP is supported, 16-color (4bit) files are prefered. of course, no
     alpha-blending, only simple key colouring, similar to 1.x,2.x behaviour.
     could be omitted, in that case built-in version is used, but you still define
     custom glyphs, the result could be messed up.
CropX, CropY, CropWidth, CropHeight - if picture has unused space around graphics,
     these parameters may specify a cropping rectangle similar to Photoshop "Crop
     Image". helps to save memory used by loaded bitmaps.
     omitting CropX or CropY defaults them to 0.
     omitting CropWidth or CropHeight defaults to remaining bitmap Width or Height,
     accordingly.

Example:
[bitmaps]
Bitmap0=new_icons.png,,28,33,608,384

load a bitmap from file "new_icons.png", ignore 16-bit version, crop image at 28,33
with size 608x384 (implies, picture is bigger and at least have unused space at 28
pixel wide at left and 33 pixels tall at top, this space is removed and final loaded
picture will be 608x384 pixels)


[schemes]
<SchemeName>=<GlyphSetID>
defines, which glyph set (discussed later in this document) is associated with this
program-required scheme name.
SchemeName  a name which is used by main program code to find a glyph set.
            the file must contain resolving of next glyph scheme names:
            (WorkIcons,Buttons,ListIcons,Folders,Controls,AddrBook,BigIcons)
GlyphSet    a local identifier, which defines a glyph set.

Example:
[schemes]
WorkIcons=my_workicons
...

defines "WorkIcons" as "my_workicons".
(however, all other required scheme names must be defined, too)


[glyphsets]
GlyphSet<n> = <GlyphSetID>,<Width>,<Height>
defines which glyphsets will be loaded into memory and which sizes do have glyphs
inside. the file may have more glyph sets defined, than used.
n               order number, not important.
Width, Height   size of each glyph (pixels) in the given glyph set. (all glyphs in a
glyph
                set have the same sizes!)

Example:
[glyphsets]
GlyphSet0=my_workicons,16,16

define glyph set with identifier "my_workicons" having glyph sizes of 16x16 pixels.


[<GlyphSetID>]
defines contents of a glyph set identified by <GlyphSetID>.

section opening (the [<id>] thing) may be followed by:
fixup=[<GridWidth>],[<GridHeight>],[<OffsetX>],[<OffsetY>]
defines, how will be glyphs extracted from source bitmap picture for this glyph set.
GridWidth, GridHeight
     changes virtual grid to specified size.
     source bitmap space (without the cropping part!) is virtually divided into
     cells of size GridWidth x GridHeight (pixels).
     default grid size is equal to glyph set defined sizes.
OffsetX, OffsetY
     when specified, moves the glyph position relatively to grid, respectively.
     if omitted defaults to 0 or previously specified fixup in this glyph set
     section.


<GlyphID> = <BitmapID>,<Column>,<Row>[,[<OffsetX>][,[<OffsetY>]]]
defines one glyph for this glyph set. the program scans each glyph set for a
specific program-defined name, case insensitively. custom names may be defined,
but will be not used. and vice versa - if programs tries to find a name which does
not exists, no drawing would be performed for this name.
BitmapID          the code of loaded bitmap ([bitmaps] section) which contains this
glyph.
Column, Row       grid cell position, starting with 0 (first row / first column is 0,0)
OffsetX, OffsetY  offset position of this only glyph by specified pixels.
                  defaults to 0 or fixup-specified numbers.
                  (good aligned glyphs do not require these)

Example:
[my_workicons]
Options=0,3,4
Cookies=0,12,4
...
fixup=32,32,16,16
Memo=1,14,4
Chat=1,18,8
...
Templates=1,5,4,15,10
AddrBook=1,0,4,,11

add glyphs to "my_workicons" glyph set.
assuming, "my_workicons" is a 16x16 glyph set:
"Options" is taken from bitmap with code 0, fourth column, fifth row, no additional
offset. "Cookies" is taken from the same bitmap, respective col,row to 12,4.
fixup follows, which makes virtual grid 32x32, and icons are taken from 16,16 in
each cell. "Memo" is placed in a bitmap with code 1 at column/row - 14,4.
"Templates" is taken from bitmap 1, row/column 5/4, but moved to 15,10 inside grid
cell. "AddrBook" is only moved to 11 in the cell.


the file may contain any amount of comments - any text after semicolon (";") is
ignored until the end of line.


the "batskin.ini" story still evolves, since GUI customization is a work in progress
and these two things are closely related. that's why I feel reluctantly to post
"batskin.ini" documentation officially, to avoid "versioning hell".
it is possible, that .ini will be mutated into a more TheBat! general format soon.
and glyph ids (names) could became not program-dependent, but GUI definition file
dependent.
however, the principle it is built upon, will not be changed and very easy porting will
be
possible, with few lines changed in the file.
so, "batskin.ini" creation is welcomed, anyway!


Related Notes:
 when program loads bitmaps, it makes necessary image crops, if specified, to save
 memory usage, which could be huge. small png files having large unused space could
 be small due to good compression, but after they load they may consume many
 megabytes of RAM.
 glyphs are drawn directly from source bitmaps, no duplications are made, the file
 mostly defines where to draw from each specified glyph.


Regarding "Missing NFS Icons" problem:
For those, who may want to add those few missing icons, a file batskin.ini could be
supplied along with a missing icons only additional file (3 files altogether)

[bitmaps]
Bitmap0=glyphs.bmp
Bitmap1=GlyphBMP-patch.png

filter-related part of glyphs should look like:

; filters in a separate file
fixup=24,24,0,0
bLeft=1,0,0
bDown=1,1,0
bUp=1,2,0
bRight=1,3,0
bNewFilter=1,4,0

  if icons follow in the same order in the GlyphBMP-patch.png

of course, GlyphBMP-patch.png may be named gbpatch.png, be of type .bmp (file
extension must be changed accordingly!) or .jpg, as you want.

-----------------------------------------------------------