K-Meleon - MacroLanguage

K-Meleon

MacroLanguage

KMeleonWiki > Documentation > EndUserDocs > MacroLanguage

K-Meleon Macro Language (old version)

(New version for K-Meleon 1.5 or newer is at -> MacroLanguage2)

Comments
Variables and Macros
Expressions
Special Strings
Special Global Variables
Events
Statements

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;
    }

    macroinfo = "string";

Since version 1.5 presents the string in the status bar whenever the mouse hovers over the item in a menu which calls the macro.

    example {
        macroinfo = "Macro description";
        $x = 0;
    }

In Macro language the NULL value can be:

"" => A empty string.
0 => A zero value.

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.

    $x = 1 + "2";                       $x = 3
    $y = "The value of x is " . x;      $y = "The value of x is 3"

Special Strings

Strings should be enclosed in double quotes although not required unless the string contains operators. A backslash is used to escape special characters:

\\	backslash (\)
\n	newline character
\t	tabulator
\"	quotation mark (")

The string values "true" and "false" are recognized as boolean values and can be used in place of a conditional expression.

    $z = "false";
    $z ? $x = 1 : $x = 0;               $x = 0
    $z = "true";
    $z ? $x = 1 : $x = 0;               $x = 1

Special Global Variables

There is a number of predefined global variables to let K-Meleon macros access some global state information.

$ARG	Argument given from caller plugin (not from caller macro).
$CHARSET	Character encoding used for the current page. Since 1.0.
$FrameURL	URL for the current frame.
$ImageURL	URL for the current image.
$LinkURL	URL for the current link.
$SelectedText	Selected text in the current page. Since 1.0.
$TextZoom	Text zoom factor for the current page. Since 1.0.
$TITLE	Title for the current page.
$URL	URL for the current page.
$URLBAR	Contents of the URL bar. Since 1.0.

Events

    OnActivateWindow
    OnCloseGroup
    OnCloseWindow
    OnInit
    OnLoad
    OnOpenWindow
    OnQuit
    OnSetup
    OnStartup
    OnWMAppExit

Statements

Statements should be finished by a semicolon. Statements may not span several lines!

    # THIS 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";

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:

    CONDITION ? &ConditionTrue : &ConditionFalse;

    ConditionTrue {
        ...
    }
    ConditionFalse {
        ...
    }

Special statements

    open( URL );

Opens URL in the current browser window.

    opennew( URL );

Opens URL in a new browser window.

    openbg( URL );

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

    $VALUE = getpref( TYPE, "user.preference.variable" );

Gets a user preference.
TYPE = BOOL | INT | STRING

    setpref( TYPE, "user.preference.variable", VALUE );

Sets a user preference.
TYPE = BOOL | INT | STRING

    togglepref( TYPE, "user.preference.variable", VALUE1, VALUE2, ... );

Toggles a user preference between a series of values (booleans always toggle between true and false).
TYPE = BOOL | INT | STRING

    delpref( prefName );

Deletes any user set value of the specified preference. This restores the preference's default value if one is set, otherwise the preference is expunged.

    exec( COMMAND_LINE );

Executes an external program.

    id( COMMAND_ID );

Sends a message ID to the current window. See the complete list of command IDs.

    forcecharset([charset] );

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

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

    plugin( PLUGIN, COMMAND );
    pluginmsg( PLUGIN, COMMAND, ARGS );
    $REPLY = pluginmsgex( PLUGIN, COMMAND, ARGS, TYPE );

Runs a plugin command. The possible values of COMMAND, ARGS and TYPE depend on the specific plugin. See the complete list of plugin commands.

    alert( MESSAGE [, TITLE [, ICON]] );

Shows a messagebox.
ICON = EXCLAIM | INFO | STOP | QUESTION

    $RESULT = confirm( MESSAGE [, TITLE [, BUTTONS [, ICON]]] );

    $VALUE = prompt( MESSAGE [, TITLE [, DEFAULT_STRING]] );

Shows a modal 'prompt' dialog and returns a string value.

    statusbar( TEXT );

Shows the message text on the status bar.

    $TEXT = getclipboard();

Gets data from the clipboard.

    setclipboard( TEXT );

Sets data to the clipboard.

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

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 );

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 );

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

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

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

    $I = index( s, t );

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

    $LEN = length( s );

Returns the length of the string s.

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

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

    $DIR = dirname( URL );

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

    $HOST = hostname( URL );

Returns the hostname of the given URL.

    macros( MACRO1 [,MACRO2 [,MACRO3 [...]]] );

Executes another macro. Multiple macro execution since 1.1.

    &MACRO;

Equivalent to macros( MACRO ).

Special statements available since K-Meleon 1.0

    $CONTENT = readfile( PATH );

Returns the contents of the specified file (32 kB maximum). Only for little text files.

    $VALUE = readreg( ROOT, PATH );

Returns the value of the specified registry key.
ROOT = HKLM | HKCU | HKCC | HKCR | HKU

    $PATH = promptforfile( INITIAL_FOLDER, FILE_TYPE_DESCRIPTION, FILE_EXTENSION_PATTERN );

Prompts the user for a file, displaying only the files matching the pattern.

    $PATH = promptforfolder( CAPTION [, INITIAL_FOLDER] );

Prompts the user for a folder.

    injectJS( JS_CODE );
    injectCSS( CSS_CODE );

Injects a JavaScript or a Cascading Style Sheet into the current page.

    $VALID_URL = urlencode( TEXT );

Encodes TEXT for use in an URL.

    $TRANSLATION = _( TEXT );

Replaces TEXT by the specified translation, if any.

    while( CONDITION ) STATEMENT

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

    while( CONDITION ) &Loop;

    Loop {
        ...
    }

Special statements available since K-Meleon 1.1

    $PATH = getfolder( FOLDER_TYPE );

    setaccel( KEY, COMMAND);

Sets a keyboard accelerator for the specified command.
KEY: Key (combination) to use e.g. "CTRL ALT X".
COMMAND: Command ID or plugin command. If NULL, the accel is deleted.

    setmenu( MENU_NAME, ITEM_TYPE [, LABEL [, COMMAND]] [, WHERE]);

Parameter	Type	Meaning
MENU_NAME	string	Specifies the name of the addressed menu (required).
ITEM_TYPE	predefined	Specifies the nature of the addressed item (required). Can be one of the strings: inline, popup, command, macro, separator.
LABEL ⁽¹⁾	string	Specifies the name of the addressed item inside the addressed menu.
COMMAND ⁽²⁾	string	Specifies the command associated with the addressed item.
WHERE ⁽³⁾	string or integer string -1 n=0,1,2,...	Specifies where to insert the addressed item. Insert before an item specified either by label or by command Insert at the end of the addressed menu Insert at position n of the addressed menu (1st position: 0)

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

  menuchecked = boolean expression ;

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 ;

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);

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.

Parameters:
Parameter        Required        Type           Value                    Meaning
menuName        YES             STRING        A menu name         The name of the menu to be rebuilt.

EditThisPage BackLinks PageInfo last changed on Wed Jul 8 23:00:32 2015

English

MacroLanguage