Customizing many aspects of K-Meleon is as simple as editing the configuration file, or config. Configs are human-readable documents that can be edited in any text editor including Notepad or Notepad2. Config files contain settings for the browser including drop-down menus, keyboard accelerators/shortcuts, and toolbars plus their toolbar buttons.

Menus (menus.cfg)

Menus are defined by 2 menus.cfg files. The menus.cfg file in K-Meleon/browser/defaults/settings/ sets up many of K-Meleon's default menus including the top-level menus. Many more menus are defined via macros. Each profile will also contain an additional menus.cfg for end-user customization. You can open the custom accel.cfg in the active profile by selecting Edit > Configuration > Menus in the browser. By default, the profile config will only contain commented-out guidance for users.

Menus.cfg is parsed from top to bottom. It is only read once. That means you have to define things above where they are used. The custom menus from the profile will be parsed last, and therefore can override default menu settings.

• A line that starts with # is a comment and is ignored.
• A line with a { on it starts a menu. Everything before the { is the menu name.
• A line that has a } on it ends a menu. Everything else on the line is ignored.
• A line with a - on it adds a separator to the menu.
• A command that starts with a : adds a submenu to the menu.
• The & character will underline the following letter for use of keyboard shortcuts.
• A line that has an = on it is a menu item. Everything on the left of the = is displayed on the menu.
• You can use \t to insert a tab such as to separate labels from the key.
• On the right side of the = is the command id that the menu item corresponds to.

Example for default config

# This will create the main menu bar with the File menu,
# that when opened has the command to open a new window.

&File {
&New Window\tCtrl+N = ID_NEW_BROWSER
}

Main {
:&File
}

Example for custom config in profile

# This will add a single entry to the existing &File menu

!&File {
Restart K-Meleon = ID_APP_RESTART
}

Accelerators (accel.cfg)

Accelerators, or keyboard shortcuts, are defined by 2 accel.cfg files. The accel.cfg file in K-Meleon/browser/defaults/settings/ lists all of K-Meleon's default shortcuts. Each profile will also contain an additional accel.cfg for end-user customization. You can open the custom accel.cfg in the active profile by selecting Edit > Configuration > Accelerators in the browser.

As usual, all lines starting with # are comments (ignored). Each accelerator definition consists of 2 parts separated by an = sign:

<key1> [<key2> [<key3> [<key4>]]] = <command>

<keyX>	The declaration of the combination of the keyboard keys (See next list of predefined key names).
<command>	The command can be a command ID, plugin command or macro called via the macros() plugin. Note that plugin commands are ignored if the addressed plugin or macro is not loaded or does not exist.

The keys

You can use a combination of any number of control keys (Alt/Ctrl/Shift) and one normal key. Control keys are:

CTRL
SHIFT
ALT

Normals keys are standard alphanumeric symbols (A-Z, 0-9, rest of symbols) and the following constants for special keys:

  VK_ESCAPE
  VK_F1
  VK_F2
  VK_F3
  VK_F4
  VK_F5
  VK_F6
  VK_F7
  VK_F8
  VK_F9
  VK_F10
  VK_F11
  VK_F12

  VK_TAB
  VK_CAPITAL   (Shift Lock)
  VK_BACK
  VK_RETURN
  VK_SPACE
  VK_MENU   (Alt Gr)

  VK_PLUS   (normal +, not numpad)
    **Note**: VK_PLUS is the code of the key, not the code of the symbol!
          If, for example, the + is accessed by pressing Shift and the key, then
          VK_PLUS corresponds to pressing the key only (without the Shift key).
  VK_MINUS   (normal -, not numpad) (same remark as for VK_PLUS)

  VK_LWIN   (left Windows key)
  VK_RWIN   (right Windows key)
  VK_APPS   (menu key)

  VK_PRINT  or  VK_SNAPSHOT   (this key doesn't work for K-Meleon accelerators)
  VK_SCROLL
  VK_PAUSE

  VK_INSERT
  VK_DELETE
  VK_HOME
  VK_END
  VK_PRIOR  or  !VK_PAGE_UP
  VK_NEXT  or  !VK_PAGE_DOWN

  VK_LEFT
  VK_UP
  VK_DOWN
  VK_RIGHT

  VK_NUMLOCK
  VK_DIVIDE   (/ on numpad)
  VK_MULTIPLY   (* on numpad)
  VK_SUBTRACT   (- on numpad)
  VK_NUMPAD0
  VK_NUMPAD1
  VK_NUMPAD2
  VK_NUMPAD3
  VK_NUMPAD4
  VK_NUMPAD5
  VK_NUMPAD6
  VK_NUMPAD7
  VK_NUMPAD8
  VK_NUMPAD9
  VK_ADD   (+ on numpad)
  VK_DECIMAL   (. on numpad)

And for the mouse buttons:

  LButton
  MButton
  RButton

Conditional accelerator definition

You can define accelerators dependent on the absence/presence of a plugin:

%ifplugin <pluginName>
        ...
%else
        ...
%endif

The %else part can be omitted (it's optional).

Examples

CTRL O = ID_FILE_OPEN
CTRL ALT VK_F4   = ID_APP_EXIT
VK_ESCAPE = ID_NAV_STOP
SHIFT VK_LEFT = ID_NAV_BACK
CTRL ALT SHIFT P = ID_LINK_ABOUT_PLUGINS

# plugin function
%ifplugin bookmarks
CTRL D = bookmarks(add)
%endif

# macro function
CTRL VK_RETURN = macros(ctrl_enter)

You can find more examples in accel.cfg file in your \K-Meleon\defaults\settings subfolder.

Toolbars (toolbars.cfg)

Toolbars are stored in a file named toolbars.cfg. The default config is located in the K-Meleon/browser/defaults/settings folder. Most skins will contain their own config. If toolbars.cfg is present in a theme's folder, this will override the default. You can store the config in a profile in 2 ways. First, if toolbars.cfg is present directly in the profile folder this will override the other configs. This can cause issues switching themes though because the graphical assets are not defined the same way across different skins. You can also create a /profile/skins/<skin_name>/ folder and place a toolbars.cfg file there. This will only override the toolbar configuration when using that specific skin.

The file is constituted of a set of toolbars, which in turn are made of buttons. In K-Meleon, the available toolbars are directly dependent on the active skin. That means, switching to another skin (Edit > Preferences (F2) > GUI Appearance) will also change which buttons are shown and what they do. It will not merely change appearance like other programs. Toolbars.cfg defines available toolbars, buttons present on toolbars, image assets, actions to execute, and menus to open.

To open the configuration of the current skin, select Edit > Configuration > Toolbars. It's strongly recommended to create a backup copy before modifying it, or even better copy the whole skin folder either under a new name or into your profile, to keep the default skin original. It is possible to copy over buttons and whole toolbars from one skin to another, but note that toolbars and images can have different names, formats, or sizes. If you only want to change the action of a given button or add a menu when right-clicking it, that's as easy as changing 1 line of text in the toolbars.cfg.

The format of toolbars.cfg is as follows: (not as complicated as it looks here, just open an existing toolbars.cfg to have a look)

 Tool Bar(16,16){        # NAME OF TOOLBAR* (WIDTH, HEIGHT), DEFAULT=(16,16) 

 Print(16,16) {        # NAME OF BUTTON (WIDTH, HEIGHT), DEFAULT=TOOLBAR
 ID_FILE_PRINT|Print         # LEFT-CLICK | RIGHT-CLICK OR LONG-CLICK **
 Print this page         # TOOL TIP ***                
 toolhot.bmp[0]         # HOT IMAGE [INDEX WITHIN IMAGE FILE]
 toolcold.bmp[0]         # COLD IMAGE [INDEX WITHIN IMAGE FILE]
 tooldead.bmp[0]         # DISABLED IMAGE [INDEX WITHIN IMAGE FILE] *****
 }                         # END OF BUTTON

 -                         # SEPARATOR

 }                         # END OF TOOL BAR



# *If you place a "!" at the beginning of your button name, K-Meleon will
# display the name as text on versions 75 and up. On versions 74 and
# below, K-Meleon will display the text only if there is no image.
#
# ** Left-click is usually a command. Right-click is usually a menu. 
# For a list of commands go to "Edit > Configuration > Commands List."
# K-Meleon can call these and any plugin commands including all macros
# from buttons. Default plugin commands are listed here:
# http://kmeleonbrowser.org/wiki/PluginCommandsToolbars
# Check "K-Meleon/browser/defaults/setting/menus.cfg" for a list of menus.
# K-Meleon can also use menus created by macros
#
# *** Tooltips are optional. If this matches the default skin, K-Meleon 
# will translate it to the user's language. If this is a custom tooltip, 
# K-Meleon will not translate it. 
#
# ***** All images are optional. Older versions of K-Meleon will display
# text if there is no image. Versions 75 and up will display the menu
# icon for the theme scaled to the current toolbar height. Images used
# in a toolbar should all be the same height. Cold is the normal state.
# Hot is clicked or hovering. If only one image is defined, K-Meleon will
# use that for all 3 states.
#
# ------------------------------------------------------------------------
#
# Any changes will take effect after K-Meleon is restarted.
#
# ------------------------------------------------------------------------

The print command "ID_FILE_PRINT" is simply an example command. The command can be a command ID, a plugin command, or a macro. Refer to the End User Documentation online or the in-browser reference by clicking Edit > Configuration > Commands List.

Where to find toolbar and button configurations:

• View > Toolbars
  
• Edit > Preferences (F2) > GUI Appearance > Toolbars
  
• Edit > Preferences (F2) > GUI Appearance > Skin
  
• Edit > Preferences (F2) > K-Meleon Plugins > Full Screen / Bookmarks / Favorites / Hotlist
  
• Edit > Configuration > Toolbars
  
• Edit > Configuration > Commands List
  
• Toolbars and buttons can also be created by macros (kmm files)

Toolbar tips

• You can very easily change the toolbar background to an image of your liking, by simply replacing the image back.bmp in the current skin folder.
  
• You can hide the thin borders between toolbars: Open about:config (Edit > Configuration > Browser Configuration) and set the pref "kmeleon.display.toolbars_line" to "false".
  
• Every button can have an additional menu on it, appearing when right-clicking or long-clicking on it. This means a left-click executes the normal function, and a right-click shows a menu. Example: Add to the cache button in the privacy bar a menu with the various "clear" options. Edit toolbars.cfg and replace "privacy(ClearCache)" with "privacy(ClearCache)|&Clear Data". Or add the whole privacy menu to the javascript button: "macros(pref_ToggleJavaScript)|&Privacy". The & sign must be placed before underlined characters. You can add every menu you like to every button, simply by using the menu name as shown in the English language menu or the default menus.cfg
• Want to use a new macro command on a button? Get a bmp image somewhere and place it in the skin, shared, or default folder. Add the button definition to toolbars.cfg. To find the function name, open the macro kmm file and look in the setmenu lines for the name it shows in the browser menu. Directly after it is the name of the macro command you need.
  
• K-Meleon will look for missing assets in the skins/default/ folder. In K-Meleon 75 and up, any skin can access assets from the default skin or the shared/ folder as if they were in their own folder. In KM 74, if you create a folder named "default" it will have the same effect.
• If you want to create a whole new toolbar, just think up a name for it and write it into toolbars.cfg. Use the same syntax as the other toolbars have.

For more information refer to the Skinning and Theming Tutorial.

Other config files

- skin.cfg

This JSON file is contained in K-Meleon's default theme as of K-Meleon 75. It is also used in other themes that use the newer 75-style skinning system. It defines the menu icons and the default toolbar icons for a theme. For more information refer to the Skinning and Theming Tutorial section about modifying themes.

- menuicons.cfg

This file is contained in K-Meleon's Klassic theme. Klassic uses the older theme system with less complex transparency and scaling which is still supported in the newest versions of the browser. Menuicons.cfg was used by all themes before K-Meleon 75. Most custom themes will contain this file. It defines the menu icons for a skin. In K-Meleon 75 and up it will also define default toolbar icons for when you add new buttons to a theme. For more information refer to the Skinning and Theming Tutorial section about modifying themes and the kplugin reference page.

- mozilla.cfg

This optional file will contain preferences to be applied to K-Meleon, or another Mozilla-derived browser. It does not exist in K-Meleon by default and must be added to the browser. It is useful primarily in organizations to apply the same settings to multiple computers. It can lock preferences, which will prevent those settings from being changed by an end user. Refer to the Custom Preferences Tutorial for more information.

- macros.cfg

Macros are small extensions that add functions to K-Meleon. They are small human-readable extensions. You can download them, you could write them yourself, and many out-of-the-box features are handled via native macros in the K-Meleon installation. In very early versions of K-Meleon, all macros were stored in the macros.cfg file. Native macro code grew from 44 lines in KM 0.4 to 1400 lines in KM 0.9 alongside the growth of user-submitted optional macros. K-Meleon 1.0 introduced an improved system and macros.cfg is now obsolete.

As of K-Meleon 1.0, macros are stored within K-Meleon macro module (.kmm) files. Macros can be modified by editing the module file in any text editor. Entire modules can be disabled via renaming them, deleting them, or via the preferences dialog. For more information on macros refer to the:

• Macro Language Reference
• Macro Tutorial
• Training Macro by James D