Developing PowerBar Modules


Introduction

A sample project with documented source code is provided. All modules should be built as shared libraries and have 'pbar' as a creator and 'pblb' as a type.


Module Functions

When PowerBar is launched and finds a module to load, it creates a special view and passes the module to it. This view knows how to call certain functions defined by the module...

Your module should provide some combination of the functions below. At a minimum it must at least implement module_get_width() and to do anything useful it needs to implement module_create() as well. The functions below should, in general, be all that you need to make a useful module. However, feel free to add additional views if your module is sufficiently complex.

module_get_width()

Implemented by your module to indicate how much space it wants in the PowerBar window. This is the only function you absolutely have to implement. This function is called when PowerBar is first launched.

module_create(BView *owner)

Implemented by your module to do any necessary initializions. It is useful to store the owning BView in a global variable so that you can draw into it later. This function is called when PowerBar is first launched.

module_quit()

Implemented by your module to do any necessary cleaning up before shutting down. This function is called when PowerBar quits.

module_draw()

Implemented by your module to do whatever drawing is necessary. It is called by PowerBar every time the owning view needs redrawn.

module_mouse_down(BPoint cursor, long buttons)

Implemented by your module to react to mouse clicks. The location is in the BView's coordinates. The button state is stored in "buttons".

module_mouse_moved(BPoint cursor, ulong transit, BMessage *msg)

Implemented by your module to react to MouseMoved messages. Exactly the same as a normal BView's MouseMoved method.

message_received(BMessage *msg)

Implemented by your module to react to dropped messages.

module_pulse()

Implemented by your module to react to pulse events. module_pulse() is called by PowerBar approximately every 1/3 seconds.


Constants and Messages

In module.h the following items are defined:

kHEIGHT

The unchanging height of the PowerBar window. This has a value of 30.

mRESIZE

A BMessage indicating that a module wants to be resized. Once a module has determined that it needs to change in size, it sends the mRESIZE message to the owning view and everything is taken care of. The code might look something like this:
	BMessage *msg = new BMessage(mRESIZE);
	msg->AddLong("width", new_width);
	owner_view->Window()->PostMessage(msg, owner_view);
Please note that "new_width" above is an actual size and NOT a delta.

kBGCOLOR

The standard background color which should be used by all modules.

kSHADOW

The standard shadow color for adding a 3D edge.

kHILITE

The standard highlight color for adding a 3D edge.