Source/ESContactAlertsController.h

   1 /*
   2  * Adium is the legal property of its developers, whose names are listed in the copyright file included
   3  * with this source distribution.
   4  *
   5  * This program is free software; you can redistribute it and/or modify it under the terms of the GNU
   6  * General Public License as published by the Free Software Foundation; either version 2 of the License,
   7  * or (at your option) any later version.
   8  *
   9  * This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
  10  * the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
  11  * Public License for more details.
  12  *
  13  * You should have received a copy of the GNU General Public License along with this program; if not,
  14  * write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
  15  */
  16
  17 @class AIModularPane, AIListObject;
  18
  19 /*!
  20  * @protocol AIEventHandler <NSObject>
  21  * @brief Protocol for a class which posts and supplies information about an Event
  22  *
  23  * Example Events are Account Connected, Contact Signed On, New Message Received
  24  */
  25 @protocol AIEventHandler <NSObject>
  26 - (NSString *)shortDescriptionForEventID:(NSString *)eventID;
  27 - (NSString *)globalShortDescriptionForEventID:(NSString *)eventID;
  28 - (NSString *)englishGlobalShortDescriptionForEventID:(NSString *)eventID;
  29 - (NSString *)longDescriptionForEventID:(NSString *)eventID forListObject:(AIListObject *)listObject;
  30 - (NSImage *)imageForEventID:(NSString *)eventID;
  31 - (NSString *)naturalLanguageDescriptionForEventID:(NSString *)eventID
  32                                                                                 listObject:(AIListObject *)listObject
  33                                                                                   userInfo:(id)userInfo
  34                                                                         includeSubject:(BOOL)includeSubject;
  35 @end
  36
  37 /*!
  38  * @protocol AIActionHandler <NSObject>
  39  * @brief Protocol for an Action which can be taken in response to an Event
  40  *
  41  * An action may optionally supply a details pane.  If it does, it can store information in a details dictionary
  42  * which will be passed back to the action when it is triggered as well as when it is queried for a  long description.
  43  *
  44  * Example Actions are Play Sound, Speak Event, Display Growl Notification
  45  */
  46 @protocol AIActionHandler <NSObject>
  47 /*!
  48  * @brief Short description
  49  * @result A short localized description of the action
  50  */
  51 - (NSString *)shortDescriptionForActionID:(NSString *)actionID;
  52
  53 /*!
  54  * @brief Long description
  55  * @result A longer localized description of the action which should take into account the details dictionary as appropraite.
  56  */
  57 - (NSString *)longDescriptionForActionID:(NSString *)actionID withDetails:(NSDictionary *)details;
  58
  59 /*!
  60  * @brief Image
  61  */
  62 - (NSImage *)imageForActionID:(NSString *)actionID;
  63
  64 /*!
  65  * @brief Details pane
  66  * @result An <tt>AIModularPane</tt> to use for configuring this action, or nil if no configuration is possible.
  67  */
  68 - (AIModularPane *)detailsPaneForActionID:(NSString *)actionID;
  69
  70 /*!
  71  * @brief Perform an action
  72  *
  73  * @param actionID The ID of the action to perform
  74  * @param listObject The listObject associated with the event triggering the action. It may be nil
  75  * @param details If set by the details pane when the action was created, the details dictionary for this particular action
  76  * @param eventID The eventID which triggered this action
  77  * @param userInfo Additional information associated with the event; userInfo's type will vary with the actionID.
  78  */
  79 - (void)performActionID:(NSString *)actionID forListObject:(AIListObject *)listObject withDetails:(NSDictionary *)details triggeringEventID:(NSString *)eventID userInfo:(id)userInfo;
  80
  81 /*!
  82  * @brief Allow multiple actions?
  83  *
  84  * If this method returns YES, every one of this action associated with the triggering event will be executed.
  85  * If this method returns NO, only the first will be.
  86  *
  87  * Example of relevance: An action which plays a sound may return NO so that if the user has sound actions associated
  88  * with the "Message Received (Initial)" and "Message Received" events will hear the "Message Received (Initial)"
  89  * sound [which is triggered first] and not the "Message Received" sound when an initial message is received. If this
  90  * method returned YES, both sounds would be played.
  91  */
  92 - (BOOL)allowMultipleActionsWithID:(NSString *)actionID;
  93 @end
  94
  95 //Event preferences
  96 #define PREF_GROUP_CONTACT_ALERTS       @"Contact Alerts"
  97 #define KEY_CONTACT_ALERTS                      @"Contact Alerts"
  98 #define KEY_DEFAULT_EVENT_ID            @"Default Event ID"
  99 #define KEY_DEFAULT_ACTION_ID           @"Default Action ID"
 100
 101 //Event Dictionary keys
 102 #define KEY_EVENT_ID                            @"EventID"
 103 #define KEY_ACTION_ID                           @"ActionID"
 104 #define KEY_ACTION_DETAILS                      @"ActionDetails"
 105 #define KEY_ONE_TIME_ALERT                      @"OneTime"
 106
 107 #define EVENTS_TITLE                            AILocalizedString(@"Events", "Name of preferences and tab for specifying what Adium should do when events occur - for example, when display a Growl alert when John signs on.")
 108
 109 typedef enum {
 110         AIContactsEventHandlerGroup = 0,
 111         AIMessageEventHandlerGroup,
 112         AIAccountsEventHandlerGroup,
 113         AIFileTransferEventHandlerGroup,
 114         AIOtherEventHandlerGroup
 115 } AIEventHandlerGroupType;
 116 #define EVENT_HANDLER_GROUP_COUNT 5
 117
 118 @interface ESContactAlertsController : NSObject {
 119     IBOutlet    AIAdium                 *adium;
 120
 121         NSMutableDictionary                     *globalOnlyEventHandlers;
 122         NSMutableDictionary                     *eventHandlers;
 123         NSMutableDictionary                     *actionHandlers;
 124 }
 125
 126 //
 127 - (void)initController;
 128 - (void)closeController;
 129
 130 //Events
 131 - (void)registerEventID:(NSString *)eventID withHandler:(id <AIEventHandler>)handler inGroup:(AIEventHandlerGroupType)inGroup globalOnly:(BOOL)global;
 132 - (NSArray *)allEventIDs;
 133 - (NSMenu *)menuOfEventsWithTarget:(id)target forGlobalMenu:(BOOL)global;
 134 - (NSArray *)arrayOfMenuItemsForEventsWithTarget:(id)target forGlobalMenu:(BOOL)global;
 135 - (NSArray *)sortedArrayOfEventIDsFromArray:(NSArray *)inArray;
 136 - (NSSet *)generateEvent:(NSString *)eventID forListObject:(AIListObject *)listObject userInfo:(id)userInfo previouslyPerformedActionIDs:(NSSet *)previouslyPerformedActionIDs;
 137 - (NSString *)defaultEventID;
 138 - (NSString *)eventIDForEnglishDisplayName:(NSString *)displayName;
 139 - (NSString *)globalShortDescriptionForEventID:(NSString *)eventID;
 140 - (NSString *)longDescriptionForEventID:(NSString *)eventID forListObject:(AIListObject *)listObject;
 141 - (NSString *)naturalLanguageDescriptionForEventID:(NSString *)eventID
 142                                                                                 listObject:(AIListObject *)listObject
 143                                                                                   userInfo:(id)userInfo
 144                                                                         includeSubject:(BOOL)includeSubject;
 145 - (NSImage *)imageForEventID:(NSString *)eventID;
 146 - (BOOL)isMessageEvent:(NSString *)eventID;
 147
 148 //Actions
 149 - (void)registerActionID:(NSString *)actionID withHandler:(id <AIActionHandler>)handler;
 150 - (NSDictionary *)actionHandlers;
 151 - (NSMenu *)menuOfActionsWithTarget:(id)target;
 152 - (NSString *)defaultActionID;
 153
 154 //Alerts
 155 - (NSArray *)alertsForListObject:(AIListObject *)listObject;
 156 - (NSArray *)alertsForListObject:(AIListObject *)listObject withEventID:(NSString *)eventID actionID:(NSString *)actionID;
 157 - (void)addAlert:(NSDictionary *)alert toListObject:(AIListObject *)listObject setAsNewDefaults:(BOOL)setAsNewDefaults;
 158 - (void)addGlobalAlert:(NSDictionary *)newAlert;
 159 - (void)removeAlert:(NSDictionary *)victimAlert fromListObject:(AIListObject *)listObject;
 160 - (void)setAllGlobalAlerts:(NSArray *)allGlobalAlerts;
 161 - (void)removeAllGlobalAlertsWithActionID:(NSString *)actionID;
 162 - (void)mergeAndMoveContactAlertsFromListObject:(AIListObject *)oldObject intoListObject:(AIListObject *)newObject;
 163
 164 @end