KMeleonWiki > Resources > MacroLibrary > MacroGuidelines

K-Meleon Macro Coding Guidelines

Here you'll find important information on how to write macro modules for K-Meleon 1.1. Please make sure that your macro modules are following our guidelines before submitting them to the Macro Library. To get a better understanding of the macro language, check out the Macro Language page or kko's Macro Reference.

Naming Convention

Module Names

The module name must be unique!

The module name is the name of the *.kmm file that is hosting your macro code. Since file names have to be unique, the module name has to be unique too. At first, you should think about an appropriate name for your module. The name should be short, but nevertheless it should be telling something about the purpose of the module.

Macro Names

The names of all macros and global variables defined in module <modulename> must have <modulename>_ as a prefix!

In your module, a macro name like "Open", for instance, isn't very specific. Another macro coder could use the same macro name in another module. Users who now install both modules would end up getting a macro redefinition error. When you call your macro <aName>_Open and the other macro coder calls his macro <anotherName>_Open, such collisions will never occur. Since the module name must be unique anyway, the module name is the appropriate prefix. (And when you see a macro <name1>_<name2> somewhere in a toolbars.cfg for instance, you know that it's defined in <name1>.kmm)

Extended Naming Convention

Your macro and variable names should follow this convention:

<modulename>_...

That's a public macro of module <modulename> that is intended for usage in accels/menus/toolbars (or by other modules).

_<modulename>_...

That's a private helper macro of module <modulename> that is not intended for usage in accels/menus/toolbars (or by other macros).

$<modulename>_...

That's a public global variable of module <modulename> (that may be used by other modules).

$_<modulename>_...

That's a private global variable of module <modulename>.

Note that you don't need to follow this convention. This is just a recommendation to increase the readability of your code (not at last to your own benefit).

Module Dependencies

Inside your module, you can insert such a line of code:

$macroModules=$macroModules."<modulename>;";

All default modules have such a line. So, the value of the variable $macroModules is a semicolon-separated list of all the installed (default) modules' names. This list can be used to determine the presence of a particular module:

index($macroModules,";<modulename>;")>-1?<...installed...>:<...not installed...>;

This way, module dependencies can be resolved, if necessary. But try to avoid such dependencies completely. Keep in mind that all modules except main.kmm are optional. Users should have the choice which ones they want to use.

Module Resources

When your <modulename>.kmm is accompanied by other files (e.g. scripts, images, Style Sheets), place these in a subfolder <modulename> of the macro folder. Keep in mind that users can place your module either in their user macro folder or in their default macro folder for use with all profiles. Your module should find its resources in any case.

Event Handling

• Build your menus OnInit, not OnSetup. In the latter case, the user would have no chance to modify your menu configuration - that's not polite. Same for accels.
• Perform only those operations OnInit and OnSetup that have to be finished before the first window becomes visible. Time consuming operations (such as file operations) should be done OnStartup (that is when the first window is already visible and before or while the first document is loading).
• Use menuchecked in favor of setcheck() for macros.

[