EModule Howto: class EModule - Abstract Base class for XEMPIM modules 3rd party classes must inherit directly from this class. A module should consist of both a gui and (usually) a collection of records (such as in an addressbook or calendar module). The internal representation of records is up to the module author, but accessors and mutators should conform to the virtual methods declared for EModule, in order to communicate properly with the XEMPIM Core. Functions overview: Stuff the Core will need ------------------------ Signals to which an EModule should respond - (id) initWithInterface:(EModuleInterface *)ptr; Initializes the EModule with a pointer to an EModuleInterface object. It is imperative that the EModuleInterface pointer be stored by the EModule. Without it, the module can not query the XEMPIM core or other modules. - (NSView *) getMainView; Returns the EModule's main view to be displayed in the XEMPIM window. If this is unimplemented there is no way for XEMPIM to display an EModule. - (NSView *) getViewForRecord:(NSString *)identifier; Returns the view associated with a specific record. This function allows other EModule's to show views for an identifier. This function may return nil (or be left undefined). - (NSView *) getPreferenceView; Returns the preference view for the module. - (void) moduleAlert:(EModuleAlert)alert; This function is used by the core to send secure signals to modules (the NSNotification system would allow all modules to send signals to other modules, and to listen to signals intended for other modules). the EModuleAlert type is an enumeration of: EModuleDisplayedAlert, EModuleUndisplayedAlert Attributes which must be set: The Following Attributes allow the core to get information about a module. They can be set in Apple's Project Builder under the "Targets" tab or by editing the generated Info.plist file. CFBundleName: **this used to use CFBundleIdentifier. It has changed. The name by which XEMPIM will identify the EModule. Refered to as Bundle Identifier in "Simple" mode. CFBundleGetInfoString: The module description loaded by XEMPIM. Refered to as Get-Info String in "Simple" mode. EModuleType: The type of module to be loaded. XEMPIM uses this to identify a module's type. If it is unset XEMPIM will identify a module as "EUnknownModule". This can not be edited in "Simple" mode. To create this field: Click the "Expert" button at the top of the target display Click the "New Sybling" button Fill in the "Property List" field with the value "EModuleType" Ensure that the "Class" field is set to "String" (this is the default) Enter one of the following for a predefined type (case insensitive): CONTACTS: a contact manager CALENDAR: a calendar/appointment manager MAIL: an electronic mail client NEWS: a news client TASKS: a tasks manager TEST: a test module (this is more or less useless) Dealing with module records --------------------------- These methods aren't quite neccessary, but they're strongly recommended if you want your module to play nicely with others. - (NSString *) getIdentifierByField:(NSString *)field_name withValue:(NSString *)value; Returns the identifier for a record where the value of the field_name parameter is the value paramater. This may be modified to return an (NSArray *) instead. - (NSString *) getIthIdentifier:(int)i; Returns the identifier of the receivers I'th record. What it means to be the I'th record of is left to the developer to the determine (the simplest approach of course being to store the records in an NSMutableArray. - (NSString *) getValue:(NSString *)identifier ofField:(NSString *)field_name; Return a value from the module based on the record identifier, and the desired field. - (void) setValue:(NSString *)identifier ofField:(NSString *)field_name to:(NSString *)value; Set a value, similarly to the correspond accessor. - (NSString *)addRecord:(NSString *)identifier; add a record and return that records identifier possible handling of this function would be to ignore the identifier parameter, and automatically set and return the new record id. after the record is created, the return id can be used to populate the record - (NSString *) deleteRecord:(NSString *)identifier; delete a record with given id - (NSMenu *)getMenu; return the NSMenu to be used for the submenu in the EModules menu. the menu can not already be attached to another Menu/MenuItem The "Unload [module]", "Load [module] at Startup", and separator items are added and managed by the core. If nil is returned the core will generate a menu for the module with only the default items. Available Functions ------------------- The EModuleInterface class will respond to and relay the following signals to allow for module communication: - (NSString *) getConfigDir; Returns XEMPIM's configuration directory (currently statically set to ~/Library/XEMPIM) - (NSString *) findModuleNameByType:(EModuleType)type; Returns the first module with EModuleType type. EModuleType is an enumerated type with values: EUnknownModule = -1 EContactsModule ECalendarModule EMailModule ENewsModule ETasksModule ETestModule - (NSString *) getIdentifierFromModule:(NSString *)mod_name byField:(NSString *)field_name withValue:(NSString *)value; Gets the identifier of a record with field field_name matching value from module mod_name. Again, this may be changed to return an NSArray. - (NSString *) getIthIdentifier:(int)i fromModule:(NSString *)mod_name; Gets the I'th identifier from the module mod_name. - (NSString *) getValueFromModule:(NSString *)mod_name fromRecord:(NSString *)identifier ofField:(NSString *)field_name; Gets the value of field field_name from the record associated with identifier from the module mod_name. - (void) setValueFromModule:(NSString *)mod_name fromRecord:(NSString *)identifier ofField:(NSString *)field_name to:(NSString *)value; Sets the value of field field_name in the record associated with identifier of module mod_name to value. - (NSString *) addRecord:(NSString *)identifier toModule:(NSString *)mod_name; Adds a record given identifier to mod_name. Returns the identifier of the created record. The returned identifier may differ from the paramater passed. Be sure to use the returned identifier in subsequent access to the record. - (void) displayModule:(NSString *)mod_name inView:(NSView *)view; Displays the module named by mod_name in the NSView view. If view is nil the module is displayed in XEMPIM's main window. - (void) displayView:(NSView *)view; Displays the NSView view in XEMPIM's main window. Used for displaying records from the local module. Notes ----- This section provides some useful hints for creating EModule's using Apple's developer tools (Project Builder and Interface Builder). Project Builder: Use apple's "Cocoa Bundle" template to set up the correct build process. Be sure to provide the path to EModule.h and EModuleInterface.h (provided in the distribution) and to link EModule.framework Interface Builder: Do not instantialize an object of your GUI controller class in your .nib file. Instead, set the FileOwner object's type to be your GUI controller class. Then in the init function for your gui controller include the command: [NSBundle loadNibNamed:@"NIB_FILE" owner:self]; where NIB_FILE is the name of the nib file to be loaded without the .nib extension. This will cause the nib file to be loaded and the connections established.