Comments

A line starting with # is a comment and is ignored.

# this is a comment

Variables and Macros

Variables are not declared explicitly, but must have a name starting with a dollar sign. A variable can either be global, accessible from any macro, or local to a specific macro. Before a variable can be used in an expression, it must be assigned a value. Integer and string values are available.

$x = 0; $y = "A text string";

Macro declarations consist of a macro name followed by a compound of statements enclosed in curly braces to execute for that macro. An optional assignment of a string value to 'menu' can be used to set the text shown when the macro is used in menus.

example { menu = "Menu text"; $x = 0;
}

Expressions

The following operators are available:

Operator

Meaning

Sample Statement

Integer Result

=

assignement

$x = 7;

$x = 7

.

string concatenation

$x = 7 . 3;

$x = 73

+

integer addition

$x = 7 + 3;

$x = 10

-

integer subtraction

$x = 7 - 3;

$x = 4

*

integer multiplication

$x = 7 * 3;

$x = 21

/

integer division

$x = 7 / 3;

$x = 2

%

integer remainder

$x = 7 % 3;

$x = 1

==

equality

$x = 7 == 3;

$x = 0

!=

unequality

$x = 7 != 3;

$x = 1

<, <=, >, >=

string comparison

$x = 10 < 2

$x = 1

<, <=, >, >=

integer comparison

$x = +10 > +2

$x = 1

? :

conditional expression

$x = $y==1 ? 2:3;

$x = 2 if y equals 1, $x = 3 otherwise

Parentheses can be used to alter the evaluation order. By default, addition and subtraction have higher precedence than multiplication, division and remainder operations.

When needed, a variable is automatically converted from a string to an integer, or vice versa.

Since K-Meleon 1.1, the On<event> macros are located in the Main K-Meleon Macro Module (main.kmm). This module also provides global $On<event> variables which you should use in your own modules to get code executed whenever <event> is triggered:

myMacro{# your On<event> code}$On<event>=$On<event>."myMacro;";

Since K-Meleon 1.1, the On<event> macros are executed in the context of the window that triggered the event. In previous versions, these macros were executed in the context of the currently active window (which is not necessarily the window that triggered the event).

Event Cascade

Startup is always followed by Load or OpenWindow
OpenWindow is always followed by Load
Init, Setup and Quit are only fired once a session.(1)
ActivateWindow is usually fired multiple times when a browser window is focused
Startup Order of Precedence
Init
Setup
Startup(1)

(1) When the browser is opening a group or folder at startup, the Load event is fired before Startup and Startup is fired multiple times (once for each opened layer).

Shutdown Order of Precedence
CloseGroup or WMAppExit(1)
CloseWindow(2)
Quit

(1) WMAppExit seems currently not to be fired at all.

(2) CloseWindow is fired for each closed layer.

Statements

Statements should be finished by a semicolon. With version prior to 1.5, statements may not span several lines! Strings can't never span several lines.

# THIS CODE IS INVALID$error = 1 +1;

Several statements can be lined up on the same line with a semicolon in between.

$x = 0; $y = "A text string";

Version 1.5 has a new macro parser. This one is more strict and will notify about errors that weren't discovered in previous versions (especially in regard to missing semicolons and malformed strings). Macros have to be encoded in UTF-8 now.

Conditional statements

The conditional expression operator (? :) can be used to execute a single statement depending on a certain condition.

A complete "If ... Then ... Else ..." statement would look like this:

CONDITION ? STATEMENT_CONDITION_TRUE : STATEMENT_CONDITION_FALSE;

A simple "If ... Then ..." statement would look like this:

CONDITION ? STATEMENT_CONDITION_TRUE : 0;

In the example above, nothing (0 = zero) is executed when the condition is false.

To execute multiple statements depending on a certain condition, these have to be encapsulated in helper macros:

Alternative conditional statements since version 1.5

K-Meleon 1.5 support if ... else statement using the following syntax:

if (condition) {
# action to do when condition is true
...
} else {
# action to do when condition is false
...
}

Documents

Document Manipulation

forcecharset([charset] ); Since version 0.9

Sets the character set (detection) for the current window. See encoding.kmm for a usage demonstration.

Parameter

Required

Type

Value

Meaning

charset

NO(1)

STRING

A charset

The name of the desired character set.

(1) When omitted, the character set auto detection is enabled. The used method is determined by the value of the intl.charset.detector preference.

injectCSS( CSS ); Since version 1.0

Injects a Cascading Style Sheet into the current page.
This method is most beneficially used in conjunction with the readfile() method. Note that this method is intended for an on demand application of CSS code only, do not use it in an event based manner. Make use of the userContent.css file to permanently apply your own styles to the documents you view.

Parameter

Required

Type

Value

Meaning

CSS

YES

STRING

CSS code

The Cascading Style Sheet code to be injected.

injectJS( JS ); Since version 1.0

Injects a JavaScript into the current page.

injectJS( JS [, location ]); Since version 1.5

Injects JavaScript code into the current document, into the current frame or into all tabs of the current window.

This method is most beneficially used in conjunction with the readfile() method. Note that this method is intended for an on demand application of JavaScript code, avoid its usage in an event based manner to keep K-Meleon stable and responsive.

Parameter

Required

Type

Value

Meaning

JS

YES

STRING

JS code

The JavaScript code to be injected.

location

NO(1)

PREDEFINED

alltabs(2)

Address all tabs in the current window.

frame

Address the current frame only.

(1) When omitted, the specified code is injected into the current document which may be a frame set. So, subframes have to be handled by the injected code itself. Same when injecting into all tabs.(2) For version 1.5

Opening Documents

open( URL ); Since version 0.4

Opens URL in the current browser window.

opennew( URL ); Since version 0.4

Opens URL in a new browser window.

openbg( URL ); Since version 0.4

Opens URL in a new background window.

opentab( URL ); Since version 1.5

Opens the specified URL in a new tab. This new tab gets the focus.

openbgtab( URL ); Since version 1.5

Opens the specified URL in a new tab. This new tab is opened in the background (the current tab keeps the focus).

String Handling

General

$I = index( s, t ); Since version 0.7

Returns the index of the string t in the string s, or -1 if t is not present.

$LEN = length( s ); Since version 0.7

Returns the length of the string s.

$SUB = substr( s, i [, n] ); Since version 0.7

Returns the at most n-character substring of s starting at i. If n is omitted, the rest of s is used.

Substitution

$TRANSLATION = _( TEXT ); Since version 1.0

Replaces TEXT by the specified translation, if any.

$SUB = gensub( r, s, h, t ); Since version 0.7

Searches the target string t for matches of the string r. If h is a string beginning with g or G, then all matches of r are replace with s. Otherwise, h is a number indicating which match of r to replace. The modified string is returned.

$SUB = gsub( r, s, t ); Since version 0.7

Substitutes the string s for each substring matching the string r in the string t, and returns the modified string. This is equivalent to gensub( r, s, "G", t).

$SUB = sub( r, s, t ); Since version 0.7

Just like gsub(), but only the first matching substring is replaced. This is equivalent to gensub( r, s, 1, t).

URLs

$BASE = basename( URL [, SUFFIX] ); Since version 0.7

Returns URL with any leading directory components removed. If specified, also remove a trailing SUFFIX.

$DIR = dirname( URL ); Since version 0.7

Returns URL with its trailing /component removed. If URL contains no '/', output '.' (meaning the current directory).

$HOST = hostname( URL ); Since version 0.7

Returns the hostname of the given URL.

$VALID_URL = urlencode( TEXT ); Since version 1.0

Encodes TEXT for use in an URL.

Iteration

while( CONDITION ) STATEMENT ; Since version 1.0

Executes a single STATEMENT while the CONDITION is true. To execute multiple statements, these have to be encapsulated in a helper macro:

Menus

Specifies the nature of the addressed item (required).Can be one of the strings: inline, popup, command, macro, separator.

LABEL (1)

string

Specifies the name of the addressed item inside the addressed menu.

COMMAND (2)

string

Specifies the command associated with the addressed item.

WHERE (3)

string or integerstring-1n=0,1,2,...

Specifies where to insert the addressed item.Insert before an item specified either by label or by commandInsert at the end of the addressed menu Insert at position n of the addressed menu (1st position: 0)

(1) LABEL must be specified for all item types except "separator". If LABEL is an empty string, this is a deletion.(2) COMMAND must be specified for item types "command" and "macro". If COMMAND is an empty string and LABEL is not, this is a deletion.(3) WHERE can be omitted for all item types except "separator" (-1 is the default).

menuchecked = boolean expression ; Since version 1.1

This statement is used inside a macro to set a checkmark for this macro's menu representations. The checkmark's state is dynamically updated according to the value of the boolean expression. The latter is evaluated whenever a menu item representing this macro becomes visible.

Note that local variables are out of scope here, only globally defined variables can be used.

menugrayed = boolean expression ; Since version 1.1

This statement is used inside a macro to enable and disable (gray out) this macro's menu representations. The enabled/disabled state is dynamically updated according to the value of the boolean expression. The latter is evaluated whenever a menu item representing this macro becomes visible.

Note that local variables are out of scope here, only globally defined variables can be used.

rebuildmenu (menuName); Since version 1.1

This method is used to rebuild a menu that was created by a setmenu() statement. Note that a menu must be rebuilt by rebuildmenu() inside the same macro where it was built by setmenu(). The rebuildmenu() statement takes effect only when the hosting macro is (directly or indirectly) called from the menus. See proxy.kmm for a usage demonstration.