The K-Meleon Skinning and Theming Tutorial

K-Meleon skins (or themes) change the browser's appearance. Unlike in other browsers, K-Meleon skins can set a default layout, modify appearance preferences, and even define which buttons will be available in the browser. Skins are backwards compatible and skins from older versions will still work on current releases. However, very old skins may not include support for newer features without some modifications.

Skins are stored as subfolders within the K-Meleon/skins folder or the Profiles/your.profile/skins folder. You can examine and edit any part of the skins on your computer. They are distributed as .zip, .7z, or .exe archives which must be extracted first.

Change K-Meleon's skin

To change the browser's skin:

1. Go to Edit > Preferences (F2) to open the preferences dialog.
2. On the GUI Appearance page click the drop-down box in the Skin section.
3. Select a skin and check the boxes to show that skin's background image, menu icons, and throbber if desired.
4. Restart K-Meleon.

Install a new skin

To install a new skin in K-Meleon:

1. Download a skin. It will be in an archive format (.7z, .zip, .exe, etc.) chosen by the author.
2. Extract your new skin to the K-Meleon/skins folder. You will need an archiver like 7-zip, PeaZip, or WinZip. If extracted correctly the top level of the directory should contain the toolbars.cfg file and graphical assets.
3. When you restart K-Meleon your theme will be available in the preferences dialog.

Store skins in a profile

Instead of storing skins in the existing main skins folder, you can also store skins within your profile. This will make keeping skins easier if you update your browser or use another computer. Simply create a Profiles/your.profile/skins/ folder. You can use this folder the same way as the main K-Meleon skins folder. If a theme in your profile's folder has the same name as a skin in the main folder, K-Meleon will use the theme from your profile.

Download skins

There are several places to look for new K-Meleon skins:

• The Forum is the place to look for newer skins or to ask questions about customizing K-Meleon's appearance.
• K-Meleon Themes for Version 1.5 will work on versions of K-Meleon up to the current version.
• The older K-Meleon Themes Wiki page list skins that worked on version 1.1 and will work on newer versions of K-Meleon, although they may need some modifications.
• The Skins and Throbbers page lists some even older skins from version 0.7. The graphical assets will work on newer versions of K-Meleon, but these skins will require more serious modifications and may lack buttons for some more recent features.

Modify a skin

It's easy to modify skins in K-Meleon. Before you begin, you should back up the original skin to another area on your computer. K-Meleon also allows you to keep custom versions of skins within your profile folder so that you don't have to modify the original skin's files. To create a custom version of a skin without changing the original files:

1. Open your profile folder from K-Meleon by selecting Edit > Configuration > Profile Directory in the menu.
2. If you do not have a skins folder in your profile, create a new folder and name it skins.
3. Open the Profiles/your.profile/skins/ folder and create a new folder with the exact name of the skin you're going to customize. So if you're modifying Klassic, your folder must be named Klassic and not "klassic" or "_Klassic_" or something similar.
4. Now, K-Meleon will check your profile's skin folder any time you select that skin. For any file that is missing, K-Meleon will use the one from the original skin. So if you leave the profile skin folder empty, there will be no change in the skin. If you place one custom asset, K-Meleon will only change the theme for that one asset. For example, if you only add an image titled back.bmp then K-Meleon will generate a skin almost the same, except the background image will be different.
5. Copy and paste any images, icons, or configuration files you want to edit to your /Profiles/your.profile/skins/<skin-name>/ folder.
6. After you modify any of these files, save them and then restart K-Meleon for changes to take effect.
   Note: Many skins include their own toolbars.cfg. If your skin uses the browser's default toolbars.cfg, it's a good idea to save a copy to your skin's folder or to your profile folder itself. Both of those locations will override the default configuration file. Then, if you have any errors you can delete, move, or rename your modified toolbars.cfg and K-Meleon will return to its working default configuration.

If you ever want to restore the default version of your skin simply change the name of your custom skin. For example, if you wanted to restore your Klassic skin to its original state, you could rename the custom version to _Klassic or anything that makes sense for you.

Remove buttons

Entire toolbars can be switched on and off in View > Toolbars. Individual buttons can be commented out. To comment out a button:

1. Open K-Meleon and select Edit > Configuration > Toolbars to open your current skin's toolbars.cfg in a text editor.
2. This document may look complex but commenting a button out is fairly simple. Toolbars.cfg sets the images, left-click function, and right-click function for the buttons in K-Meleon. Any line beginning with a # is a comment and will be ignored by the browser.
3. Scroll down to the button you wish to hide and place a # at the beginning of each line in the button's description. There are some buttons in the config that will already be commented out so that they are turned off by default. You can use these as a reference.
4. Save toolbars.cfg and restart K-Meleon.

Add buttons

Adding buttons is more complicated but still fairly straightforward. First, you'll need to open toolbars.cfg for your skin just like above. Your skin will likely have some buttons commented out by default; you can add these buttons simply by removing the # marks at the beginning of each line in the button's description.

If you want to create your own button you can use the buttons from your skin as an example or use this basic template:

        Open{
        ID_FILE_OPEN
        }

The text above will create an "Open" button. The first line is the name of the button. The second line is what it triggers. That second line can be nearly anything in K-Meleon. Your button can trigger commands, macros, pop-up menus, and functions from Kplugins.

In version 75 and up, this will create a button using the menu icon for the command. Menu icons will be defined in your theme's skin.cfg or menuicons.cfg file. If you want the name displayed as text beside the icon, add a ! to the beginning of the name, so the above example would be named !Open.

In version 74 and below this will create a text-only button. In those older versions, the browser will display the name as text if no icon is chosen. For older versions, a button will contain only text or only an image.

It's possible to add right-click menus, custom icons, and tooltips to your button. Check out the other buttons in your skin's toolbars.cfg to use as a reference. You can add image files to your skin's folder for icons and all skins can use the image files in the skins/Default/ or Skins/Shared/ folders. Visit the K-Meleon graphics forum if you need assistance.

Create toolbars

You can add your custom buttons to an existing toolbar or you can create custom toolbars. To add a new toolbar to your current theme:

1. Open K-Meleon and select Edit > Configuration > Toolbars to open your current skin's toolbars.cfg in a text editor.
2. Scroll down to the end of the document.
3. Copy and paste the template below. Add your buttons between the curly braces.
4. Save toolbars.cfg and restart K-Meleon.

YourToolbar {

# Add buttons here.

}

This example will default to a 16-pixel-high toolbar with 16-pixel-wide buttons. You can manually set the size by placing the height and button width in parentheses like so: YourToolbar(32,32)

On K-Meleon versions 75 and up you can use the same icon size from the tab bar by setting both values to zero like: YourToolbar(0,0)

Create a new skin

If you would like to create a new skin, it will help to use an existing skin for reference. If you're creating a classic-style skin, Phoenity is a perfect template. Lim Chee Aun's Phoenity was once the default skin. He is an excellent graphic designer, the skin still works with modern versions of K-Meleon, it was released under a Creative Commons License, there is an update packed with helpful comments, and its text files are cleanly laid out.

➥Download the Phoenity theme for K-Meleon.

K-Meleon 75 introduced a new skin system that is used in the Default skin. Versions 75 and up support both this new system and the older classic system. If you would like to create a skin using this format refer to the High Resolution skin. This skin adds improved high-resolution icons to the Default skin. The higher-resolution icons are based on the vector versions of Lim Chee Aun's Aura icons. High Resolution was created to demonstrate how 75-style skins function. It's available under an open-source license and you're welcome to use it as a template.

➥Download the High Resolution theme for K-Meleon.

Additional resources are available if you are modifying or building a skin:

• The SkinComponents page explains the purpose of most assets in a skin.
• Siria's Classiria skin is a classic-style skin that includes a considerable amount of explanatory comments in the text files.
• The ToolbarsConfig page includes an explanation of how the config file worked for older skins.
• For recommendations of tools to create graphical assets check out the ThemeTools page.
• If you have any questions or issues or just want to share your theme drop by the graphics forum.

Version 75 skins

From an end user's point of view, the 75-style skins are very similar, but they offer better support for modern displays and easier customization. The new skins introduced the ability to change icon size from the preferences dialog. To change the icon size on a KM75-style skin go to Edit > Preferences (F2) >> GUI Appearance and change the Toolbar size value. Setting the toolbar size to 0 will use the default size which will depend on your computer's resolution and zoom settings.

K-Meleon 75 and up allow you to store a custom toolbars.cfg in your profile without editing the skin itself. If you use multiple 75-style skins you can use the same config file in your profile for each of them. K-Meleon will check for toolbars.cfg first in the user's profile folder, then the skin's own folder, and then in the "default/settings" folder. However, note that K-Meleon will use that config for all themes which will likely cause issues for older one like Klassic.

The key differences between classic skins and 75-style skins are:

Classic Skins	75-Style Skins
Icons are bitmap images or .ICO files.	Icons can be in many formats including .PNG, .JPG, .GIF, .TIFF, .ICO, and bitmap images.
The skin defines icon sizes.	The user defines a preferred icon size; the skin defines images for various size ranges. It's possible for a theme's author to define all icon sizes or to set all icons to the user's preference.
Each skin has a separate toolbars.cfg file.	The toolbars.cfg file can be in the profile folder, the skin's folder, or the browser/defaults/settings folder. K-Meleon will check in that order and use the first config file it finds.
Icons for commands are defined in toolbars.cfg and menuicons.cfg.	Icons can be defined in toolbars .cfg and menuicons.cfg still. Icons are now mainly assigned to commands in skin.cfg. The commands are then automatically paired with menu items and can be assigned toolbar locations in toolbars.cfg. If a theme contains menuicons.cfg but not skin.cfg, K-Meleon will use the 16-pixel menu icons as the default toolbar icons.
No chrome URL support.	There is limited chrome URL support for "cold" images only; don't use this.
Button names are displayed as text if there is no image.	Button names are displayed as text if they are preceded by a !. A button can have only an icon, only text, or both.

Troubleshooting

- No history icon

If the theme works fine except for the history button, there is an easy fix. Open toolbars.cfg in a text editor and search for the following lines:

        %ifplugin history
        History{
        history(View)|Histor&y

Replace those 3 lines with the 3 lines below:

        %ifplugin macros
        History{
        macros(Places_History)|Histor&y 

Now save the file and restart K-Meleon.

This change is required because older versions of K-Meleon used a separate Kplugin for the history button, but after improvements to the macro language, it was later handled by a macro. Refer to this update announcement in the forum for more information.

- Icons are missing

If you are using a very old skin some icons or features may not be defined. The skin itself defines what icons and toolbars are available to K-Meleon. If you want to use very old (pre 1.5) skins you'll have to define new features in toolbars.cfg to update the skin for your version of K-Meleon or add the graphic assets from the desired skin into a more recent skin.

If you use a skin(variant), like Phoenity(Large) or Classiria(16px_max), the issue is different and very easy to fix. K-Meleon 75 and up no longer support variants. K-Meleon 74 and below will pull the missing icons for variants from their original skins. K-Meleon 1.5.x used the technique by default if you would like to examine an example. Version 1.5.x included both the Phoenity and Phoenity(Large) themes. If you examine their contents you'll notice that many icons are not present in Phoenity(Large).

To make a skin(variant) work correctly on modern versions of K-Meleon, you can patch them manually:

1. If you don't have the original skin, download the original. So for Phoenity(Large), you would need the Phoenity skin.
2. Copy all of the files from the original skin and paste them into the skin(variant).
3. Your computer should ask if you want to overwrite files that already exist in the skin(variant). DO NOT overwrite any files; tell your file manager to skip these. This will add only the missing files from the original skin.
4. Restart K-Meleon and all of your icons will be visible.

- Icons are invisible

If you select a theme and all of the icons are invisible then K-Meleon can't find the config files. Go to your skins folder and open the folder for the theme that's invisible. There should be images and .cfg files there. If you instead see one or more folders, copy and paste those folders to your /skins folder.

- Icons are too small

If you are using the Default skin or another 75-style skin, you can increase the toolbar and icon size by going to Edit > Preferences (F2) >> GUI Appearance > Toolbar Size, entering a size, and re-starting K-Meleon.

Old-style themes define their own icon size. If a classic skin's icons are too small, you can try a different skin or modify the icons.

- Rectangles around icons

Some systems including WINE on Linux, ReactOS, and older versions of Windows do not fully support "alpha" transparency in icon files. If you're seeing black (or some solid color) rectangles around all icons, your system's library doesn't support the transparencies used in your theme. These systems either display a pixel in the bitmap or do not display the pixel; there is no partial or in-between state.

You can still use any theme that doesn't contain alpha transparencies. The "Klassic" theme that comes with K-Meleon is an old-style theme that uses traditional all-or-nothing transparency. The Phoenity theme was once the default theme for K-Meleon and will support nearly every version of K-Meleon including up to the current release. It should also work.

If you edit a .bmp file and it loses transparency, check the following things:

• Is the top-left pixel the color you want to be transparent? This is where K-Meleon will look.
• Did the editing software change the color depth of the bitmap? The old system has errors with bitmap transparency at 32-bit color depth. Try manually setting the file to a lower color depth. If you are seeing pink or black static in your images try setting the color to 24-bit.