Creating a K-Meleon plugin

A K-Meleon plugin is a dll that is used in tight coupling with the browser. The plugin can subclass the browser window and overhear all messages, it can send messages to affect the browser, it can talk with other plugins, and through a set of K-Meleon callback functions it can communicate with Gecko.

All plugins in the K-Meleon plugin directory are loaded at startup, unless there exists a "kmeleon.plugins.[plugin-name].load" preference set to False.

When a plugin is loaded, K-Meleon calls GetKmeleonPlugin. This should be the only function you have to export. It should return a pointer to a kmeleonPlugin structure. This structure is the connection between the plugin and K-Meleon. It holds pointers to a slew of functions, as well as some information about your plugin.

The kmeleonPlugin structure (defined in kmeleon_plugin.h) has two main sections, stuff filled in by you, and stuff filled in by K-Meleon.

The things you should fill in are:

  • version --- This is the first thing in the structure. It should be set to KMEL_PLUGIN_VER
  • description --- This is what the user sees when he/she clicks plugins in the preferences box
  • DoMessage --- This is a pointer to the function K-Meleon will call when sending messages to your dll.

The things K-Meleon will fill in are:

  • hParentInstance -- This is the HINSTANCE of K-Meleon.
  • hDllInstance -- This is the HINSTANCE for your plugin. You should make note of this if you want to access any resources defined in the dll.
  • A pointer to a kmeleonFunctions structure -- This structure (kFuncs) holds pointers to all the functions you can call in K-Meleon. See kmeleon_plugin.h for the available functions and their description.

Right after loading up your dll, and getting the kmeleonPlugin structure, K-Meleon will call DoMessage() with an 'Init' message. This is only done once, ever. You can use this time to load graphics and stuff.

Right before unloading your dll, K-Meleon calls DoMessage() with a 'Quit' message. This is also only done once. You can use this time to unload those graphics and stuff you loaded earlier. Note that by the time the 'Quit' message is sent, there are no more K-Meleon windows on the screen.

Every time a new window is created, K-Meleon will send a 'Create' message. A reference to the parent window comes as a parameter. In the same way, every time a window is closed, K-Meleon will send a 'Destroy' message.

K-Meleon will send a 'Config' message when the user clicks "Config" in the preferences box. A reference to the preferences box comes as a parameter.

K-Meleon will send a 'DoMenu' message when it encounters your plugin in menus.cfg. A reference to the HMENU, that you should play with, comes as the first parameter. The second parameter is a pointer to a character array holding whatever was put in parenthesis inside menus.cfg. Use that text to create different menu entry commands for your plugin and/or to set the text shown in menus.

K-Meleon will send a 'DoRebar' message soon after 'Create'. It will pass the HWND of the rebar control for the new window that was just created. You can use this time to create a rebar band or 2 or 3... You don't have to worry about size and position, K-Meleon should handle that for you. Also note that the rebar id will be ignored and overwritten.

K-Meleon will send 'DoAccel' when it encounters a line for your plugin in accel.cfg. It will pass a pointer to a character array holding whatever was put in parenthesis inside accel.cfg. Use that text to create different accel commands for your plugin. You should return a command id for your command. Use GetCommandIDs() to reserve command ids.

To allow macros to control your plugin, you can accept extra subjects in DoMessage() calls. A pluginmsg() command passes up to two parameters from the macro call. A pluginmsgex() command uses one parameter to send information and a second to point at a text buffer receiving the reply. The simple plugin() command only use the available accel commands.

You can also export a DrawBitmap() function, which is called by the bmp_menu plugin whenever it's time for you to draw your menu icons. If you don't define it, you won't get menu icons.

In order to receive messages, such as WM_COMMAND from your menu items, you should subclass any newly created window, so that messages are routed through your plugin.


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