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.

List of standard message for DoMessage()

• Load : sent just after loading up your dll. Return -1 to not load the plugin.

• Init : sent after all plugins and default settings were loaded. You can use this time to load graphics and stuff, and update menus, accels or toolbars.

• Setup: sent after loading profile settings.

• Create: sent whenever a new windows is created. The first parameter contains a reference to the parent window.

• CreateTab?: sent whenever a new tab is created. When tabs are enable 'Create' is always followed by CreateTab?, except for popup. The first parameter contains a reference to the parent window and the second parameter a reference to the tab.

• DoMenu: sent when k-meleon 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. Use SetMenu() instead on relying on this message when possible.

• DoAccel: sent when k-meleon 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. Use SetAccel() instead on relying on this message when possible.

• DoRebar: sent 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.

• DestroyTab?: sent whenever a new tab is closed. When tabs are enable 'Destroy' is always preceded by DestroyTab?, except for popup. Same parameter than CreateTab?.

• Destroy: sent whenever a windows is closed. Same parameter as Create

• Quit: sent before unloading the plugin dll. 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.

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.