The K-Meleon Skinning and Theming Tutorial

K-Meleon skins (or themes) change the browser's appearance. Unlike 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. 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.

If you create a skin variant in your profile (like /Profiles/your.profile/skins/Default(variant)/), K-Meleon will first check your profile for the original skin (Default in this example). If the original is not present in your profile, K-Meleon will then check the main skins folder and apply the changes to that skin.

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

Skin (variants)

The easiest way to customize skins in K-Meleon is to create variations of existing skins. If you create a folder with the exact name of an existing skin and add a title in parentheses, K-Meleon will apply the changes in the variant folder to the original skin. For example, you can create a Default(custom) subfolder in the K-Meleon/skins folder. After you do this an option will appear in the preferences dialog for a "Default(custom)" skin. When you use this skin K-Meleon will use the Default skin but if any files with the same name appear in your variation, K-Meleon will use those instead. This allows you to create custom icons or backgrounds, store them in a custom folder, and never have to modify the original skin. You can even store your customized skins in your profile.

K-Meleon 1.5.x used the technique by default if you would like to examine an example. Version 1.5.x included the Phoenity and Phoenity(Large) themes. If you examine their contents you'll notice that many icons are not present in Phoenity(Large). K-Meleon will pull those missing icons from the Phoenity folder.

Custom 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.

Adding buttons is more complicated but still fairly straightforward. First, you'll need to open toolbars.cfg for your skin. 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. The second line can be nearly anything in K-Meleon. Your button can trigger commands, macros, 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. Check out the K-Meleon graphics forum if you need assistance.

Creating 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 button. 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. Lim Chee Aun's Phoenity for K-Meleon was once the default skin. Lim Chee Aun is an excellent graphic designer, the skin still works with modern versions of K-Meleon, it was released under a Creative Commons License, it includes helpful comments, and its text files are clear.

For explanations of the various parts of a skin:

• The SkinComponents page explains the purpose of most assets in a skin.
• Siria's Classiria skin includes a considerable amount of explanatory comments in the text files.
• The ToolbarsConfig page also includes an explanation of the config file, but specifics may be outdated.

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

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. 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.

75-style themes 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. For these newer themes, 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.

It's possible to create new 75-style skins but most skins use the older style. If you would like to create a skin using this format refer to the High Resolution skin. This skin is a variant of the Default skin with higher resolution graphics and was created to demonstrate how 75-style skins function.

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 browser/defaults/settings folder, or the skin's 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.

- 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.