K-Meleon

Comments

A line that starts 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 values and string values are available.

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

When needed, a variable is automatically be converted from a string to an integer, or the other way around.

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

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

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

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


Expressions

The following operators are available:

  +     addition         $x = 7 + 3;         10
  -     subtraction      $x = 7 - 3;         4
  *     multiplication   $x = 7 * 3;         21
  /     division         $x = 7 / 3;         2
  %     remainder        $x = 7 % 3;         1
      equal            $x = 7  3;        0
  !=    not equal        $x = 7 != 3;        1
  .     concatenation    $x = 7 . 3;         73
  ? :   conditionals     $x = $y1 ? 2:3;   2 if y  1; 3 otherwise
  < <=  comparison       $x = 10 < 2         1 (string comparison)
  > >=                   $x = +10 > +2       1 (number comparison)

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


Strings

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

  \\   backslash
  \n   newline
  \r   carrige return
  \t   tab
  \"   quotation mark


Global Variables

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

$URL

URL for current page.

$LinkURL

URL for current link.

$ImageURL

URL for current image.

$FrameURL

URL for current frame.

$TITLE

Title for current page.

$ARG

Argument given from caller plugin (not from caller macro).

Available since K-Meleon 1.0:

$URLBAR

Content of the urlbar

$SelectedText

Selected text in the current page.

$CHARSET

Text encoding used for current page.

$TextZoom

Text zoom factor for the current page.


Events

OnStartup?
OnOpenWindow?
OnCloseWindow?
OnLoad?
OnQuit?


Statements

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

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

!!! Statements may not span several lines! !!!

    $error = 1 +
        1;

Special statements:

  open( URL );
        Open url in the current browser window.

  opennew( URL );
        Open url in a new browser window.

  openbg( URL );
        Open url in a new background window.

  $VALUE = getpref( TYPE, "user.preference.variable" );
        Gets a user preference.
        TYPE = BOOL | INT | STRING

  setpref( TYPE, "user.preference.variable", VALUE );
        Sets user preferences.
        TYPE = BOOL | INT | STRING

  togglepref( TYPE, "user.preference.variable", VALUE1, VALUE2, ... );
        Toggles a user preference between a series of values.
        TYPE = BOOL | INT | STRING
        (booleans always toggle between true and false)

  exec( PROGRAM );
        Execute an external program.

  id( COMMAND_ID );
        Send a message id to the current window.
        See the complete list of command IDs.

  plugin( PLUGIN, COMMAND );
  pluginmsg( PLUGIN, COMMAND, ARGS );
  $REPLY = pluginmsgex( PLUGIN, COMMAND, ARGS, TYPE );
        Run a plugin command.
        See the complete list of plugin commands.
        COMMAND = ???
        ARGS = ???
        TYPE = ???

  alert( MESSAGE, TITLE, ICON );
        Show a messagebox.
        ICON = EXCLAIM | INFO | STOP | QUESTION

  $RESULT = confirm( MESSAGE, TITLE, BUTTONS, ICON );
        Show a messagebox and ask for confirmation.
        BUTTONS = RETRYCANCEL | YESNO | YESNOCANCEL | ABORTRETRYIGNORE;
        ICON = EXCLAIM | INFO | STOP | QUESTION
        RESULT = OK | YES | NO |ABORT | RETRY | IGNORE | 0

  $VALUE = prompt( PROMPT, TITLE, DEFAULT_STRING );
        Show a modal 'prompt' dialog that returns a string value.

  statusbar( TEXT );
        Show the message text on the status bar.

  $TEXT = getclipboard();
        Get and return data from the clipboard.

  setclipboard( TEXT );
        Set data to the clipboard.

  $SUB = gensub( r, s, h, t );
        search the target string t for matches of the string r.  If h
        is a string beginning with g or G, then replace all matches
        of r with s.  Otherwise, h is a number indicating which match
        of r to replace.  The modified string is returned as the
        result of the function.

  $SUB = gsub( r, s, t );
        for each substring matching the string r in the string t,
        substitute the string s, and return 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);

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

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

  $BASE = basename( NAME , SUFFIX? );
        Returns NAME with any leading directory components removed.
        If specified, also remove a trailing SUFFIX.

  $DIR = dirname( NAME );
        Returns NAME with its trailing /component removed; if NAME
        contains no /'s, output '.' (meaning the current directory).

  $HOST = hostname( URL );
        Returns hostname of given URL.

  macros( MACRO );
        Execute another macro.

  &MACRO
        Alias for 'macros(MACRO)'

Available since K-Meleon 1.0:


  $CONTENT = readfile( filepath );
        Return the content of the file given in parameter. Only for small text file ( < 32Kb ).

  $VALUE = readkey( root, path );
        Return the value of a registry key, root can be one of the following: HKLM,HKCU,HKCC,HKCR,HKU.

  $FILEPATH = promptforfile( InitialFolder?, FileTypeDescription?, FileMask? )
        Prompt the user for a file, displaying only the files which match the FileMask? pattern.

  $FOLDERPATH = promptforfolder( Caption, InitialFolder? )
        Prompt the user for a folder.

  injectJS( JS )
  injectCSS( CSS )
        Inject in the current page a java script or a cascading style sheet.

  $VALID_URL = urlencode( text )
<!-- write description here

  $TRANSLATION = _( text )
<!-- write description here

  while (CONDITION) STATEMENT
<!-- write description here

Available since K-Meleon 1.1:


  $PATH = getfolder("foldertype");
      Return the designed path with foldertype one of:
        RootFolder?
        SettingsFolder?
        ProfileFolder?
        ResFolder?
        SkinFolder?
        MacroFolder?
        UserMacroFolder?

--

  setaccel(key, command)
       key: key to use (Ex: "CTRL ALT X")
       command: id or plugin command. If NULL, delete the accel if it exists.



  setmenu(<menuname>,<itemtype>[,<label>,<command>?],<where>?);

    parameter     type           meaning

    <menuname>    string         Specifies the name of the addressed menu (required).
    <itemtype>    predefined     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|integer Specifies where to insert the addressed item.
                  string         Insert before an item specified either by label or by command
                  -1             Insert at the end of the addressed menu <where>
                  n=0|1|2|...    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).


Not all parameters are required for alert, confirm and prompt commands.


Plugin commands for macros

See the list of commands supported by plugins.


K-Meleon

(c) 2000-2010 kmeleonbrowser.org. All rights reserved.
design by splif.