K-Meleon

KMeleonWiki > Documentation > EndUserDocs > MacroLanguage > MacroLanguage2

K-Meleon Macro Language


Contents


See also:


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

Variable type Value Version ReadOnly
$ARG STRING Argument given from caller plugin (not from caller macro). 0.9 YES
$CHARSET STRING Character encoding used for the current page. 1.0 NO
$CommandLine STRING The command line which started K-Meleon. 1.5.2 YES
$FrameURL STRING URL for the current frame. 0.8.2 YES
$ImageURL STRING URL for the current image. 0.8 YES
$LinkURL STRING URL for the current link. 0.8 YES
$macroModules STRING Semicolon separated list of all active kmm modules. ? NO
$SelectedText STRING Selected text in the current page. 1.0 YES
$TabNumber INT The number of tabs in the current window. 1.5 YES
$TextZoom INT Text zoom factor for the current page. 1.0. NO
$TITLE STRING Title for the current page. 0.9 NO
$URL STRING URL for the current page. 0.7 YES
$URLBAR STRING Contents of the URL bar. 1.0 NO

Special Global Variables are case sensitive.

$ARG

K-Meleon's keyboard accelerators, its menu system and its plugins (but not the macros plugin itself) can call a macro with an argument:

setmenu($__m,macro,"&Toolbars","cfg_Skin(toolbars)");

A macro called this way, can get the argument reading the $ARG variable:

   cfg_Skin{
   macroinfo=_("Edit a skin configuration file");
   $ext="cfg"; &getExtensionHandler; $cfg_File=$ARG.".".$ext;
   .
   .
   }

Never read $ARG after opening one of the Modal Windows (there's a bug). Assign the value of $ARG to a local variable as shown in the example.


Events

The Macro Extension Plugin provides a variety of events.

Event Is triggered
OnActivateWindow When a window gets the focus.
OnCloseGroup When a multi-layered window is closed.
OnCloseTab When a tab is closed.
OnCloseWindow When a window/layer is closed.
OnInit When the Default Configuration Files have been parsed.
OnLoad When a document finished loading.
OnOpenTab When a tab is opened.
OnOpenWindow When a window/layer is opened.
OnQuit When the macro plugin (the browser) is being closed.
OnSetup When the User Configuration Files have been parsed.
OnStartup When the first window is opened.
OnWMAppExit When ID_APP_EXIT is called to terminate the application.

Not all of these events are supported by all versions of K-Meleon.

Event Handling

Whenever <event> is triggered, the Macro Extension Plugin will look for a macro named On<event> and execute it if found. The appropriate On<event> macros are provided by default.

To get your own code executed whenever <event> is triggered, simply add your code to the On<event> macro in your Macro Definition File (macros.cfg).

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:

    CONDITION ? &ConditionTrue : &ConditionFalse;

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


Alternative conditional statements since version 1.5

   if (condition) { statement1; [statement2; [...]] } else { statementA; [statementB; [...]] }                                                          

If the boolean expression in parentheses is true, the statements in the if block are executed. Otherwise the statements in the else block are executed. The else block is optional. Surrounding curly braces can be omitted for a block that contains only one statement.

Examples:

        if (condition) statement;

        if (condition) {
                statement1;
                statement2;
        } else {
                statement3;
                statement4;
        }

        if (condition) statement1; else statement2; statement3;

In the last example, statement3 is executed whatever the value of condition may be since the if-else statement is finished after statement2. If statement3 is meant to belong to the else block, statement2 and statement3 have to be enclosed in curly braces.


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.


    $TEXT = urldecode( VALID_URL );                                          Since version 1.5

Decodes an encoded 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:

    while( CONDITION ) &Loop;
Loop { ... }
    while( CONDITION ) { STATEMENT1 ; [STATEMENT2 ; [ ... ]] }    Since version 1.5

The syntax was extended to support execution of multiple statements.

    while ( CONDITION ) { 
    STATEMENT1 ;
    STATEMENT2 ;
    }    


Interfaces to


The User


Simple Dialogs / Modal Windows

    alert( MESSAGE [, TITLE [, ICON]] );                                        Since version 0.8

Shows a messagebox.

ICON = EXCLAIM | INFO | STOP | QUESTION

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

Shows a messagebox and asks for confirmation.

BUTTONS = RETRYCANCEL | YESNO | YESNOCANCEL | ABORTRETRYIGNORE
ICON = EXCLAIM | INFO | STOP | QUESTION
RESULT = OK | YES | NO |ABORT | RETRY | IGNORE | 0

    $VALUE = prompt( MESSAGE [, TITLE [, DEFAULT]] );     Since version 0.7

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

Parameter Required Type Value Meaning
message YES STRING A message(1) The text to be displayed in the dialog's body.
title NO STRING A title(2) The text to be displayed in the dialog's title bar.
default NO(3) STRING A preset The text to be displayed in the dialog's input field.

(1) The message cannot span several lines here!

(2) The title cannot span several lines.

(3) When <default> is specified, <title> must be specified too.


Setting Accelerator Key Definitions

   setaccel( keys [,command]);                                                      Since version 1.1

This method can be used to set keyboard accelerators instead of editing accel.cfg.

Parameter Required Type Value Meaning
keys YES STRING A key combination(1) The addressed key combination.
command YES STRING A command(2) The command to be associated with the key combination.

(1) A space-separated list of predefined key names.

(2) Command can be "ID_..." or "pluginName(pluginCommand)". If command is an empty string, this is a deletion.


Menus

    setcheck( COMMAND, STATE );                                              Since version 0.9 
Parameter Required Type Value Meaning
COMMAND YES STRING A command The command associated with the addressed menu item.
STATE YES BOOL A boolean expression The checkmark's state (true=visible, false=hidden).

This method is used to set a checkmark for command's menu representations. Use the menuchecked statement to handle checkmarks of menu items representing macros.

    setmenu( MENU_NAME, ITEM_TYPE [, LABEL [, COMMAND]] [, WHERE]);    Since version 1.1
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 (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 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)

(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. Use this statement in the first lines of the macro function.

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. Use this statement in the first lines of the macro function.

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.

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


  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. Use this statement in the first lines of the macro function.



The Operating System

   exec( COMMAND_LINE );                                                           Since version 0.6

Executes an external program.

   $VALUE = iniread( SECTION, KEY, VALUE, PATH );                      Since version 1.5.3                                                           Since version 0.6

Returns the value of the specified key in the specified section from the ini file in the path.

   iniwrite( SECTION, KEY, VALUE, PATH );                                  Since version 1.5.3

Writes the key and value in the section to the ini file specified in path. If the file, section, or key does not exist, it is created. If the key exists the value is overwritten. An ini file has the following format.

        [SECTION]
        KEY=VALUE


                                
   $PATH = promptforfile( INITIAL_FOLDER, FILE_TYPE_DESCRIPTION, FILE_EXTENSION_PATTERN ); 
                                                                                                                  Since version 1.0

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


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

Prompts the user for a folder.


    $CONTENT = readfile( PATH );                                                  Since version 1.0

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


    $VALUE = readreg( ROOT, PATH );                                         Since version 1.0

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


The Browser

 
   $PATH = getfolder( FOLDER_TYPE );                                       Since version 1.1

Returns the path of the specified folder.
FOLDER_TYPE = RootFolder | SettingsFolder | ProfileFolder | ResFolder | SkinFolder | MacroFolder | UserMacroFolder


 
   id( COMMAND_ID );                                                                     Since version 0.7

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


   macros( MACRO1 );                                                                     Since version 0.7

Executes another macro.

    &MACRO;

Equivalent to macros( MACRO ).

   macros( MACRO1 [,MACRO2 [,MACRO3 [...]]] );                    Since version 1.1 

Expanded to handle Multiple macro execution in version 1.1


The Browser Preference System

   delpref( prefName );                                                                      Since version 0.9

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.

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

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

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

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

 
   togglepref( TYPE, "user.preference.variable"[, VALUE1, VALUE2, ... ]);     Since version 0.6        

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

The K-Meleon Plugins

 
   plugin( PLUGIN, COMMAND );                                                     Since version 0.7


   pluginmsg( PLUGIN, COMMAND, ARGS );                               Since version 0.7


 
   $REPLY = pluginmsgex( PLUGIN, COMMAND, ARGS, TYPE );         Since version 0.7

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

The Clipboard

    $TEXT = getclipboard();                                                              Since version 0.7

Gets data from the clipboard.


    setclipboard( TEXT );                                                                  Since version 0.7

Sets data to the clipboard.

The Statusbar

    statusbar( TEXT );                                                                        Since version 0.7

Shows the message text on the status bar.

Alphabetical Index

  
 * $ARG                         
 * $CHARSET                        
 * $FrameURL                                
 * $ImageURL                        
 * $LinkURL                        
 * $SelectedText        
 * $TextZoom        
 * $TITLE                        
 * $URL                        
 * $URLBAR
 * _()                        
 * alert()
 * basename()                
 * confirm()
 * delpref()                        
 * dirname()                
 * exec()
 * forcecharset()        
 * gensub()
 * getclipboard()        
 * getfolder()                
 * getpref()        
 * gsub()
 * hostname()
 * id()
 * if() 
 * index()
 * iniread()
 * iniwrite()        
 * injectCSS()        
 * injectJS()        
 * length()
 * macroinfo
 * macros()        
 * menuchecked        
 * menugrayed
 * OnActivateWindow
 * OnCloseGroup
 * OnCloseTab
 * OnCloseWindow
 * OnInit
 * OnLoad
 * OnOpenTab
 * OnOpenWindow
 * OnQuit
 * OnSetup
 * OnStartup
 * OnWMAppExit
 * open()        
 * openbg() 
 * openbgtab() 
 * opennew() 
 * opentab() 
 * plugin()
 * pluginmsg()
 * pluginmsgex()
 * prompt()                
 * promptforfile()        
 * promptforfolder()        
 * readfile()
 * readreg()        
 * rebuildmenu()
 * setaccel()
 * setcheck()          
 * setclipboard()        
 * setmenu()        
 * setpref()        
 * statusbar()        
 * sub()        
 * substr()
 * togglepref()
 * urldecode()
 * urlencode()
 * while()        
K-Meleon

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