
README-themes
-------------

There are two completely different mechanisms that control the
visual appearence of this application:

 o The ttk (themed tk) package that draws all widgets, such as buttons etc.
   Ttk works with themes but in this context we usually denote
   these themes as skins or as ttk themes.

 o The application defined theme engine that controls which
   icons to use, and some resources that are used by the widgets.
   Do not confuse the application themes with tile themes.

We only focus on the application themes, the second item, here.
A theme consists of a sub tree in the file system and typically looks like:

MyCoolTheme/avatars/32x32/
                    48x48/
                    64x64/
            backgrounds/
            elements/
            icons/16x16/
                  32x32/
                  48x48/
                  64x64/
                  128x128/
                  others/
                  scalable/
            iconsets/emoticons/
                     roster/
                     service/
            mime/16x16/
            sounds/
            splash/


Most folders contain images of various sorts, but not all. Sub folders
denoted 32x32, for instance, contain images of this size only. The image
formats always supported are GIF and PNG, but in some cases also JPEG
images can be used.

avatars/        default avatars when user doesn't have any
backgrounds/    typical larger size images used as roster background or 
                as splash image
chatstyles/     todo
elements/       images used as user interface elements in various places
icons/          the main directory where most images used for buttons etc.
                come from. The others/ folder is for multi resolution images
                like .ico and .icns.
iconsets/       archives of typically small images used as emticons etc.
                They are jisp formats, packed or unpacked.
mime/           images illustrating a given MIME type. The file name is
                obtained from the type by replacing "/" with "-".
sounds/         sound sets, see README-sounds
splash/         the splash image(s)



A theme, apart from the application default, can be placed either
internally in the application tree, or as a user defined theme
in the preference folder. A theme is distinguished by its name, which
is also the name of the folder containing the complete directory tree.
Examples:

    coccinella/themes/Cool/
    prefsFolder/themes/Green/

The file names in icons/ follow to some degree the freedesktop.org
specification, where the basename contains of "-" separated smaller words
which describe the context of the image in a hierarchical way. When the
theme engine looks up an image or icon, it first looks in the present theme,
and then in the built in default theme (Crystal). It is using the following
fallback hierarchy:

  list-add-user-Dis -> list-add-user
    PNG -> GIF

where it strips off the last "-" part for each image format.

Many images have a resource name associated with it. If you keep the filename 
the same as in the original distro, the image will be automatically used. 
You may also pick a different name, but then you must specify a new value for 
the resource that is also the file name. As an example:

*JMain.connectImage:       imageMyConnect

where the 'imageMyConnect.png' file is in the themes directory.

The 'iconsets' and 'sounds' have extended search paths. As an example,
the sound sets are collected from:

    coccinella/sounds/
    coccinella/themes/MyCoolTheme/sounds/
    prefsFolder/sounds/
    prefsFolder/themes/MyCoolTheme/sounds/

This way it is possible to add a sound set independent of any theme.






BU:
................................................................................


Images
------

Images are the most important thing determined by a theme.
They are normally found in the applications images folder:

    coccinella/images/

but may be placed in specific places used by standalone components:

    coccinella/components/Phone/images/

A theme, apart from the application default, can be placed either
internally in the application tree, or as a user defined theme
in the preference folder. A theme is distinguished by its name, which
is also the name of the folder containing the complete directory tree.
Examples:

    coccinella/themes/Cool/
    prefsFolder/themes/Green/

A theme directory tree replicates the application tree structure with the
images or resources that are going to be replaced. For instance, if a
"Cool" theme shall replace one or several images it can define the
content in the following folders:

    Cool/images/
    Cool/components/Phone/images/

When the application asks for an image it may define a sub path (subPath)
where the image shall be searched for. This sub path defaults to "images".
The search order for an image in the "Cool" theme is:

    coccinella/themes/Cool/subPath/     <-- if folder exists
    prefsPath/themes/Cool/subPath/      <-- if folder exists

If not found in any of these the

    coccinella/subPath/

is used as a final fallback. As an example consider the search order for an
image 'login' (we assume png format) in the 'Cool' theme:

    coccinella/themes/Cool/images/login.png     <-- if folder exists
    prefsFolder/themes/Cool/images/login.png    <-- if folder exists
    coccinella/images/login.png

For the moment the image formats must be either GIF or PNG.


Resources
---------

The second part that influences the applications appearence that belong
to the application theme specification is the resources. Some features
of widgets and several application specific layout stuff is encoded
as resources using the built in option database for resources.

The default resources are found in
  
    coccinella/resources/

The default.rdb file always sets some reasonable values. After that the 
platform specific rdb file is read.

A theme may override any resource settings by adding its own resource files in

    themes/themeName/resources/

using the predefined resource file names, like:

themes/themeName/resources/default.rdb

Most visual appearence are now set via the tile theme engine but some are
still used, see specific docs for these. For the application specific
resources you need to search the sources for something like:

option add *Chat*mePreForeground      red

In the resource files they show up as:

*MailBox*Tablelist.labelBackground:        #dd1111

Many images have a resource name associated with it. If you keep the filename 
the same as in the original distro, the image will be automatically used. 
You may also pick a different name, but then you must specify a new value for 
the resource that is also the file name. Examplevise:

*JMain.connectImage:       imageMyConnect

where the 'imageMyConnect.png' file is inside the themes image directory.


That's it!