There is only one header file (IEElement.h) which you have to include in your project and which you can find in the Develop directory.
There is only one function an add-on should export as extern "C"
:
void *message_port(BMessage *message);
This function is the interface between the add-on and Interface Elements (or the ResourceHandler). The meaning of the return value depends on the message the add-on receives; sometimes there is no return value (can be NULL), or it is a BWindow* or a BMessage*. The main application will know what to expect.
message_port()
All messages arrive through the exported message_port
function as an argument.
IE_INIT ('Init')
This message is received when the add-on image is loaded in memory. This is usually not needed, but can be used e.g. to read preferences. The return value must be a pointer to a BMessage.
This message does not contain data.The answer message can be IE_GUI_ELEMENT ('Lmnt')
if the add-on does not contain an inspector, or IE_GUI_ELEMENT_INSPECTOR ('Insp')
if it does. If the add-on is not an inspector, no answer message is necessary since that data is not useful for the ResourceHandler at run time.
B_STRING_TYPE "Name" (OPTIONAL)
B_STRING_TYPE "Author" (OPTIONAL)
B_STRING_TYPE "Copyright" (OPTIONAL)
B_STRING_TYPE "Message" (OPTIONAL)
B_BOOL_TYPE "HasProblemsWhenDragging" (OPTIONAL)
IE_EXIT ('Exit')
This message is received before unloading the add-on image from memory. It happens when the user quits the application. The return value is ignored (should be NULL).
IE_INSTANTIATE_PALETTE_BVIEW ('InsP')
You have to instantiate a default instance of your view and return a pointer to it.
This message does not contain data.The return value is a pointer to BView.
IE_INSTANTIATE_BVIEW ('Inst')
You have to instantiate a new instance of your view based on the archived options and return a pointer to it.
The message contains the options of your view instance in the form of message data (e.g. B_STRING_TYPE "fontname").The return value is a pointer to BView.
IE_GET_OPTIONS ('Get?')
Create a BMessage of view configuration and return a pointer to that BMessage. Deleting the BMessage is the responsibity of the requester. The return value is a pointer to a BMessage.
Data:B_OBJECT_TYPE "bview"
IE_EDIT ('Edit')
The user wants to edit the view options. Typically you will open a window with the view parameters and update the view as the user modifies its parameters (by sending IE_UPDATE_VIEW). The return value is a pointer to a BWindow which the add-on opened. If more than one windows are opened the pointer to the "main" window (which knows how to close their child windows) should be returned. When the user closes the window, the add-on should send an IE_WINDOW_CLOSED message to the main application using the BMessenger received in this message.
Data:B_MESSENGER_TYPE "messenger"
B_RECT_TYPE "frame"
B_OBJECT_TYPE "bview"
IE_STRIP ('Strp')
The data which is needed only for editing or source generation should be removed as a result of this message. Typically you will remove the unnecessary parts from the view options, which the end-user does not need, to reduce the size of the resource file. The return value is ignored (should be NULL).
The message contains the options of your view instance.
IE_GENERATE ('Gen!')
The add-on has to return a BMessage which contains fragments of the C++ source which will be put in certain parts of the window source. The return value is a BMessage pointer, or NULL.
The message which the add-on receives contains the options of the view, in addition some strings which makes source generation easier. There is only one requirement for the BMessage representation of the view: it should contain aB_STRING_TYPE "name"
data which is the view name.
Interface Elements will attach a unique persistant ID to each view (B_LONG_TYPE "ID"
),
which is also useful when generating source.
B_STRING_TYPE "windowname"
B_STRING_TYPE "windowclass"
B_STRING_TYPE "viewnameid"
B_STRING_TYPE "iewindowview"
B_STRING_TYPE "DataTypes"
B_STRING_TYPE "Header"
B_STRING_TYPE "MessageReceived"
B_STRING_TYPE "DispatchMessage"
B_STRING_TYPE "IEConstructor"
B_STRING_TYPE "Constructor"
B_STRING_TYPE "IEClassDefinition"
B_STRING_TYPE "ClassDefinition"
message_port
).
It is possible that in the future there will be more places to insert source to.
MessageReceived()
of the view
These messages arrive in the MessageReceived()
method of the add-on's BView derived class. So if you need to implement
controlling a variable or an action when all the views are attached to the window, you should override MessageReceived()
.
IE_SET_VARIABLE ('Set!')
Set the variable which the view controls.
B_OBJECT_TYPE "variable"
IE_VARIABLE_TO_VIEW ('v2vu')
The view has to initialize itself from its variable. This happens after constructig the window, before showing it, but can be called anytime.
IE_VIEW_TO_VARIABLE ('vu2v')
The view has to write its state to its variable. This happens usually when closing the window, but can be called anytime.
IE_ALL_VIEWS_ATTACHED ('IEaa')
All the views have been attached to the window. An add-on needs this message only when it operates with other views.
All messages are sent with the BMessenger that the add-on receives in the 'Edit' message.
IE_WINDOW_CLOSED ('IEwc')
This message is sent when the user finished editing a resource and decided to keep that data. It can also be sent when the user does not want to keep the data but you want to store the window frame rectangle in the database.
Data:B_OBJECT_TYPE "window"
B_RECT_TYPE "frame" (OPTIONAL)
IE_UPDATE_VIEW ('IEuv')
This message is sent to update the view after the user edited its parameters. Its purpose is to set the position and size of frame rectangle of the view's encapsulation parent view correctly. You might not need to send this message if your view does not change in size.
Data:
B_OBJECT_TYPE "bview"