There is only one header file (IEAddOn.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. 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.
IE_INIT ('Init')
This message is received when the add-on image is loaded in memory. It can be used e.g. to read preferences or open the add-on resource file and read some resources from it. The return value must be a pointer to a BMessage.
Data:B_REF_TYPE "addon ref"
B_REF_TYPE "addon directory ref"
IE_OK ('OK!!')
or IE_ERROR ('Err!')
depending
on the success of the initialization.
Data of the answer message:
B_LONG_TYPE "Type"
B_STRING_TYPE "Author" (OPTIONAL)
B_STRING_TYPE "Copyright" (OPTIONAL)
B_STRING_TYPE "Message" (OPTIONAL)
B_LONG_TYPE "Maximum Occurrences" (OPTIONAL)
IE_EXIT ('Exit')
This message is received before unloading the add-on image from memory. It happens usually when the user quits Interface Elements. It can be used e.g. to store preferences in the database. The return value is ignored (should be NULL).
IE_NEW ('New!')
The user wants to create a new resource of this type. Typically you will open a window with default resource parameters. 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 an add-on window by pressing "Apply", the add-on should send an IE_WINDOW_CLOSED message to the main application using the BMessenger received in this message. If the user does not press "Apply" but closes the window, the window can be closed without sending a message to Interface Elements.
Data:B_MESSENGER_TYPE "messenger"
B_RECT_TYPE "frame"
B_STRING_TYPE "name"
B_LONG_TYPE "type"
B_LONG_TYPE "id"
IE_EDIT ('Edit')
The user wants to edit a resource with this editor. Caution! The type of the resource is not necessarily the same as the add-on resource type! The add-on has to check whether it can accept the resource data for editing or not. If it does not accept the data it should indicate with an alert. If it accepts but data will be lost during conversion, this also must be indicated to the user. Typically you will open a window with the resource parameters received in this message. 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 an add-on window by pressing "Apply", the add-on should send an IE_WINDOW_CLOSED message to the main application using the BMessenger received in this message. If the user does not press "Apply" but closes the window, the window can be closed without sending a message to Interface Elements.
Data:B_MESSENGER_TYPE "messenger"
B_RECT_TYPE "frame"
B_STRING_TYPE "name"
B_LONG_TYPE "type"
B_LONG_TYPE "id"
B_RAW_TYPE "data"
IE_GENERATE ('Gen!')
The user wants to generate C++ source from the resource data. This message may not apply to every add-on. Typically you will create files in the directory given. The return value is a pointer to a BList of filenames the add-on created, or NULL.
Data:B_REF_TYPE "directory"
B_STRING_TYPE "name"
B_RAW_TYPE "data"
B_MESSENGER_TYPE "messenger"
IE_STRIP ('Strp')
The user wants to strip the resource data i.e. remove the data which is needed only for its generation. This message applies to the add-ons which can generate themselves. Typically you will remove the unnecessary parts from the resource data, which the end-user does not need, to spare space. The return value is ignored (should be NULL).
Data:B_STRING_TYPE "name"
B_RAW_TYPE "data"
B_MESSENGER_TYPE "messenger"
IE_GENERATE_MESSAGE_HANDLER ('GenM')
This is a very special message to those add-ons which want to place some C++ code in the MessageReceived of the main application. This message is used only by the 'Main Menu' add-on. The return value is a string pointer, or NULL.
Data:B_STRING_TYPE "name"
B_RAW_TYPE "data"
All messages are sent with the BMessenger that the add-on receives in 'New!' or 'Edit' messages.
IE_WINDOW_CLOSED
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. In this case send this message with only the "window" and "frame" data.
Data:B_OBJECT_TYPE "window"
B_RAW_TYPE "data"
B_RECT_TYPE "frame" (OPTIONAL)
B_STRING_TYPE "name" (OPTIONAL)
B_LONG_TYPE "type" (OPTIONAL)
B_LONG_TYPE "id" (OPTIONAL)
IE_UPDATE_LIST
This message is sent to update the resource list so that changes in the resource will immediately shown in the resource list. This message type is not yet implemented!
The message data are the same as by IE_WINDOW_CLOSED.
IE_EDIT_AS_HEX, IE_EDIT_AS_TEXT
The add-on wants to edit its data in a text or hex editor (set by the user in the preferences). It will receive the edited data back in the IE_DATA_EDITED message.
Data:B_MESSENGER_TYPE "messenger"
B_RAW_TYPE "data"
B_STRING_TYPE "name"
IE_GET_RESOURCES
The add-on wants to receive information about all the resources in the resource file. This is rarely needed. The reply arrives in IE_RESOURCES as a bunch of ResourceInfo structures ("resourceinfo" of type B_RAW_TYPE). For details of how to send and receive this information, see IE_RESOURCES.
This message does not contain data.These messages are replies to one of the requests IE_EDIT_AS_HEX, IE_EDIT_AS_TEXT or IE_GET_RESOURCES.
IE_DATA_EDITED
Reply to IE_EDIT_AS_HEX or IE_EDIT_AS_TEXT. If the message does not contain "data", that means the user closed the editor without making modifications.
Data:B_RAW_TYPE "data"
IE_RESOURCES
Reply to IE_GET_RESOURCES. This message contains a number of ResourceInfo
structures (see IEAddOn.h for details).
B_RAW_TYPE "resourceinfo"
Usually you will request the resources this way:
ie_messenger.SendMessage(new BMessage(IE_GET_RESOURCES), &answer); index=0; if(answer->what==IE_RESOURCES){ while( resourceinfo = (ResourceInfo*) answer->FindData ("resourceinfo", B_RAW_TYPE, index++, &size)){ // do something with resourceinfo } }