root/Trunk/Adium.framework/Versions/A/Headers/AIInterfaceControllerProtocol.h @ 2

Revision 2, 20.0 KB (checked in by jon, 16 years ago)

Initial commit of skeletal project.

Line 
1/*
2 *  AIInterfaceControllerProtocol.h
3 *  Adium
4 *
5 *  Created by Evan Schoenberg on 7/31/06.
6 *
7 */
8
9#import <Adium/AIControllerProtocol.h>
10#import <Adium/AIPlugin.h>
11
12#define Interface_ContactSelectionChanged                               @"Interface_ContactSelectionChanged"
13
14/*!
15 * @brief AIContactInfoInspectorDidChangeInspectedObject notification name
16 *
17 * userinfo is an NSDictionary with keys KEY_PREVIOUS_INSPECTED_OBJECT and KEY_NEW_INSPECTED_OBJECT and objects of class AIListObject
18 */
19#define AIContactInfoInspectorDidChangeInspectedObject  @"AIContactInfoInspectorWillChangeInspectedObject"
20#define KEY_PREVIOUS_INSPECTED_OBJECT   @"PreviousInspectedObject"
21#define KEY_NEW_INSPECTED_OBJECT                @"NewInspectedObject"
22
23#define Interface_SendEnteredMessage                            @"Interface_SendEnteredMessage"
24#define Interface_WillSendEnteredMessage                        @"Interface_WillSendEnteredMessage"
25#define Interface_DidSendEnteredMessage                         @"Interface_DidSendEnteredMessage"
26#define Interface_ShouldDisplayErrorMessage                     @"Interface_ShouldDisplayErrorMessage"
27#define Interface_ShouldDisplayQuestion                         @"Interface_ShouldDisplayQuestion"
28#define Interface_ContactListDidBecomeMain                      @"Interface_ContactListDidBecomeMain"
29#define Interface_ContactListDidResignMain                      @"Interface_contactListDidResignMain"
30#define Interface_ContactListDidClose                           @"Interface_contactListDidClose"
31#define Interface_TabArrangingPreferenceChanged         @"Interface_TabArrangingPreferenceChanged"
32#define AIViewDesiredSizeDidChangeNotification          @"AIViewDesiredSizeDidChangeNotification"
33
34#define PREF_GROUP_INTERFACE                    @"Interface"
35#define KEY_TABBED_CHATTING                             @"Tabbed Chatting"
36#define KEY_GROUP_CHATS_BY_GROUP                @"Group Chats By Group"
37#define KEY_SAVE_CONTAINERS                             @"Save Containers On Quit"
38#define KEY_CONTAINERS                                  @"Containers"
39
40#define PREF_GROUP_CONTACT_LIST                         @"Contact List"
41#define KEY_CL_WINDOW_LEVEL                                     @"Window Level"
42#define KEY_CL_HIDE                                                     @"Hide While in Background"
43#define KEY_CL_EDGE_SLIDE                                       @"Hide On Screen Edges"
44#define KEY_CL_FLASH_UNVIEWED_CONTENT           @"Flash Unviewed Content"
45#define KEY_CL_ANIMATE_CHANGES                          @"Animate Changes"
46#define KEY_CL_SHOW_TOOLTIPS                            @"Show Tooltips"
47#define KEY_CL_SHOW_TOOLTIPS_IN_BACKGROUND      @"Show Tooltips in Background"
48#define KEY_CL_WINDOW_HAS_SHADOW                        @"Window Has Shadow"
49
50typedef enum {
51        AINormalWindowLevel = 0,
52        AIFloatingWindowLevel = 1,
53        AIDesktopWindowLevel = 2
54} AIWindowLevel;
55
56//Identifiers for the various message views
57typedef enum {
58        DCStandardMessageView = 1,      //webkit is not available
59        DCWebkitMessageView                     //Preferred message view
60} DCMessageViewType;
61
62@protocol AIInterfaceComponent, AIContactListComponent, AIMessageDisplayController, AIMessageDisplayPlugin;
63@protocol AIContactListTooltipEntry, AIFlashObserver;
64
65@class AIListWindowController, AIMessageWindowController;
66
67@class AIChat, AIListObject, AIListGroup;
68
69@protocol AIInterfaceController <AIController>
70- (void)registerInterfaceController:(id <AIInterfaceComponent>)inController;
71- (void)registerContactListController:(id <AIContactListComponent>)inController;
72
73/*!     @brief  Implement handling of the reopen Apple Event.
74 *
75 *      @par    The reopen handler should respond by making sure that at least one of Adium's windows is visible.
76 *
77 *      @par    Adium.app's implementation handles this event this way:
78 *
79 *      @li     If there are no chat windows, shows the Contact List.
80 *      @li     Else, if the foremost chat window and chat tab has unviewed content, make sure it stays foremost (bringing it forward of the Contact List, if necessary).
81 *      @li     Else, if any chat window has unviewed content, bring foremost the chat window and chat tab with the most recent unviewed content.
82 *      @li     Else, if all chat windows are minimized, unminimize one of them.
83 *      @li     If the application is hidden, unhide it.
84 *
85 *      @return A value suitable for returning from the \c NSApplication delegate method <code>applicationShouldHandleReopen:hasVisibleWindows:
86</code>. Specifically: \c YES if AppKit should perform its usual response to the event; \c NO if AppKit should do nothing.
87 */
88- (BOOL)handleReopenWithVisibleWindows:(BOOL)visibleWindows;
89
90//Contact List
91/*! @name Contact List */
92/* @{ */
93/*!
94 * @brief Brings contact list to the front
95 */
96- (IBAction)showContactList:(id)sender;
97/*!
98 * @brief Close the contact list window
99 */
100- (IBAction)closeContactList:(id)sender;
101/*!
102 * @returns YES if contact list is visible and selected, otherwise NO
103 */
104- (BOOL)contactListIsVisibleAndMain;
105/*!
106 * @returns YES if contact list is visible, otherwise NO
107 */
108- (BOOL)contactListIsVisible;
109/*! @} */
110
111#pragma mark Detachable Contact List
112/*!
113 * @brief Create a new AIListWindowController to display a given contact list group in a detached window
114 *
115 * @result Created contact list controller for detached contact list
116 */
117- (AIListWindowController *)detachContactList:(AIListGroup *)aContactList;
118
119#pragma mark Messaging
120/*!
121 * @brief Opens tab or window for a chat (following user's preferences)
122 *
123 * @param inChat The chat. If already open, the chat will be brought to the front.
124 */
125- (void)openChat:(AIChat *)inChat;
126
127/*!
128 * @brief Opens a chat in a given container at a specific index
129 *
130 * NOTE: If the chat is already open, this won't move it and instead does nothing. Perhaps it should, though :)
131 *
132 * @param inChat The chat.
133 * @param containerID The name of the container window.
134 * @param index The index within that containter window.
135 */
136- (id)openChat:(AIChat *)inChat inContainerWithID:(NSString *)containerID atIndex:(int)index;
137
138/*!
139 * @brief Move a chat to a new window container
140 *
141 * NOTE: The chat must already be open. That's a bug.
142 */
143- (void)moveChatToNewContainer:(AIChat *)inChat;
144
145/*!
146 * @brief Close the interface for a chat
147 *
148 * @param inChat The chat
149 */
150- (void)closeChat:(AIChat *)inChat;
151
152/*!
153 * @brief Consolidate all open chats into a single container
154 */
155- (void)consolidateChats;
156
157/*!
158 * @brief Brings the tab/window for a chat to the front and sets it as active
159 * @param inChat The chat
160 */
161- (void)setActiveChat:(AIChat *)inChat;
162
163/*!
164 * @brief Get the active chat.
165 *
166 * @result The active chat. If no chat is active (a non-chat window is focued, or Adium is not focused), returns nil.
167 */
168- (AIChat *)activeChat;
169
170/*!
171 * @brief Get the chat which was most recently active
172 *
173 * If -[self activeChat] is non-nil, this will be the same as activeChat. However, if no chat is active, so long
174 * as any chat is open, this will return the chat most recently active.  If no chats are open, this will return nil.
175 */
176- (AIChat *)mostRecentActiveChat;
177
178/*!
179 * @brief Get all open chats
180 *
181 * @result The open chats. Returns an empty array if no chats are open.
182 */
183- (NSArray *)openChats;
184
185/*!
186 * @brief Get all open chats in a given container.
187 *
188 * @result The array of open chats. Returns nil if no container with containerID exists.
189 */
190- (NSArray *)openChatsInContainerWithID:(NSString *)containerID;
191
192/*!
193 * @brief Get an array of the containerIDs of all open containers
194 */
195- (NSArray *)openContainerIDs;
196
197/*!
198 * @brief Open a new container with a given ID and name
199 *
200 * @param containerID The container's ID. Pass nil to let Adium generate one
201 * @param containerName THe name of the container. Pass nil to not specify one.
202 *
203 * @result The newly created AIMessageWindowController
204 */
205- (AIMessageWindowController *)openContainerWithID:(NSString *)containerID name:(NSString *)containerName;
206
207/*!
208 * @brief Cycles to the next open chat, making it active
209 *
210 * This crosses container boundaries.
211 */
212- (void)nextChat:(id)sender;
213
214/*!
215 * @brief Cycles to the previous open chat, making it active
216 *
217 * This crosses container boundaries.
218 */
219- (void)previousChat:(id)sender;
220
221#pragma mark Interface plugin callbacks
222/*!
223 * @brief A chat window did open: rebuild our window menu to show the new chat
224 *
225 * This should be called by the interface plugin (e.g. AIDualWindowInterfacePlugin) after a chat opens
226 *
227 * @param inChat Newly created chat
228 */
229- (void)chatDidOpen:(AIChat *)inChat;
230
231/*!
232 * @brief A chat has become active: update our chat closing keys and flag this chat as selected in the window menu
233 *
234 * This should be called by the interface plugin (e.g. AIDualWindowInterfacePlugin)
235 *
236 * @param inChat Chat which has become active
237 */
238- (void)chatDidBecomeActive:(AIChat *)inChat;
239
240/*!
241 * @brief A chat has become visible: send out a notification for components and plugins to take action
242 *
243 * This should be called by the interface plugin (e.g. AIDualWindowInterfacePlugin)
244 *
245 * @param inChat Chat that has become active
246 * @param inWindow Containing chat window
247 */
248- (void)chatDidBecomeVisible:(AIChat *)inChat inWindow:(NSWindow *)inWindow;
249
250/*!
251 * @brief A chat window did close: rebuild our window menu to remove the chat
252 *
253 * This should be called by the interface plugin (e.g. AIDualWindowInterfacePlugin)
254 *
255 * @param inChat Chat that closed
256 */
257- (void)chatDidClose:(AIChat *)inChat;
258
259/*!
260 * @brief The order of chats has changed: rebuild our window menu to reflect the new order
261 *
262 * This should be called by the interface plugin (e.g. AIDualWindowInterfacePlugin)
263 */
264- (void)chatOrderDidChange;
265
266#pragma mark Chat window access
267/*!
268 * @brief Find the window currently displaying a chat
269 *
270 * @returns Window for chat otherwise if the chat is not in any window, or is not visible in any window, returns nil
271 */
272- (NSWindow *)windowForChat:(AIChat *)inChat;
273
274
275/*!
276 * @brief Find the chat active in a window
277 *
278 * If the window does not have an active chat, nil is returned
279 */
280- (AIChat *)activeChatInWindow:(NSWindow *)window;
281
282#pragma mark Interface selection
283/*!
284 * @brief Get the list object currently focused in the interface
285 *
286 * We find the first responder that knows about list objects and get its selected object.
287 * This may be, for example, the contact list or a chat window.
288 */
289- (AIListObject *)selectedListObject;
290
291/*!
292 * @brief Get the list object currently selected in the contact list
293 *
294 * If multiple objects are selected, this returns the first one. If possible, use arrayOfSelectedListObjectsInContactList and
295 * handle multiple selections.
296 */
297- (AIListObject *)selectedListObjectInContactList;
298
299/*!
300 * @brief Get the list objects currently selected in the contact list
301 *
302 * @result An NSArray of selected objects
303 */
304- (NSArray *)arrayOfSelectedListObjectsInContactList;
305
306#pragma mark Message View
307/*!
308 * @brief Register an object which can handle displaying messages
309 *
310 * See @protocol AIMessageDisplayPlugin for details. An example of such an object is the WebKit Message View plugin.
311 *
312 * @param inPlugin The object, which must conform to @protocol(AIMessageDisplayPlugin)
313 */
314- (void)registerMessageDisplayPlugin:(id <AIMessageDisplayPlugin>)inPlugin;
315
316/*!
317 * @brief Unregister an object previously registered with registerMessageDisplayPlugin.
318 */
319- (void)unregisterMessageDisplayPlugin:(id <AIMessageDisplayPlugin>)inPlugin;
320
321/*!
322 * @brief Get the AIMessageDisplayController-conforming object for a chat
323 *
324 * Every chat has exactly one. You can get it!
325 */
326- (id <AIMessageDisplayController>)messageDisplayControllerForChat:(AIChat *)inChat;
327
328#pragma mark Error Display
329- (void)handleErrorMessage:(NSString *)inTitle withDescription:(NSString *)inDesc;
330- (void)handleMessage:(NSString *)inTitle withDescription:(NSString *)inDesc withWindowTitle:(NSString *)inWindowTitle;
331
332#pragma mark Question Display
333- (void)displayQuestion:(NSString *)inTitle withAttributedDescription:(NSAttributedString *)inDesc withWindowTitle:(NSString *)inWindowTitle
334                  defaultButton:(NSString *)inDefaultButton alternateButton:(NSString *)inAlternateButton otherButton:(NSString *)inOtherButton
335                                 target:(id)inTarget selector:(SEL)inSelector userInfo:(id)inUserInfo;
336- (void)displayQuestion:(NSString *)inTitle withDescription:(NSString *)inDesc withWindowTitle:(NSString *)inWindowTitle
337                  defaultButton:(NSString *)inDefaultButton alternateButton:(NSString *)inAlternateButton otherButton:(NSString *)inOtherButton
338                                 target:(id)inTarget selector:(SEL)inSelector userInfo:(id)inUserInfo;
339
340#pragma mark Synchronized Flashing
341- (void)registerFlashObserver:(id <AIFlashObserver>)inObserver;
342- (void)unregisterFlashObserver:(id <AIFlashObserver>)inObserver;
343- (int)flashState;
344
345#pragma mark Tooltips
346/*!
347 * @brief Register a tooltip-supplying object
348 *
349 * @param inEntry The object which will be queried for information when building a tooltip. Must conform to the AIContactListTooltipEntry protocol.
350 * @param isSecondary Most tooltips are secondary; this means they are displayed in the bottom half of the tooltip which can expand as needed.
351 */
352- (void)registerContactListTooltipEntry:(id <AIContactListTooltipEntry>)inEntry secondaryEntry:(BOOL)isSecondary;
353
354/*!
355 * @brief Unregister a previously reigstered tooltip-supplying object
356 *
357 * @param inEntry The object to unregister
358 * @param isSecondary This should match the value passed to registerContactListTooltipEntry:secondaryEntry:
359 */
360- (void)unregisterContactListTooltipEntry:(id <AIContactListTooltipEntry>)inEntry secondaryEntry:(BOOL)isSecondary;
361
362/*!
363 * @brief Get an array of all primary contact list tooltip entries
364 *
365 * @result An NSArray of objects conforming to AIContactListTooltipEntry
366 */
367- (NSArray *)contactListTooltipPrimaryEntries;
368
369/*!
370 * @brief Get an array of all secondary contact list tooltip entries
371 *
372 * @result An NSArray of objects conforming to AIContactListTooltipEntry
373 */
374- (NSArray *)contactListTooltipSecondaryEntries;
375
376/*!
377 * @brief Show an object's tooltip at a given point
378 *
379 * If object is not nil, the tooltip box will be shown for that object at the given point. It is created if needed;
380 * if there is an existing object tooltip, that window is moved to the given point and reconfigured for object.
381 * This is a rich-text, information-rich tooltip, not a simple text tooltip as seen elsewhere in Mac OS X.
382 *
383 * @param object The object for which the tooltip should be shown. Pass nil to hide any existing tooltip.
384 * @param point The point in screen coordinates for the tooltip's origin. If object is nil, this value is ignored.
385 * @param inWindow The window from which the tooltip is originating. If object is nil, this value is ignored.
386 */
387- (void)showTooltipForListObject:(AIListObject *)object atScreenPoint:(NSPoint)point onWindow:(NSWindow *)inWindow;
388
389#pragma mark Window level menu
390/*!
391 * @brief Build a menu of possible window levels
392 *
393 * Window levels may be, for example, 'Above other windows' or 'Normally'.
394 *
395 * @param target The target on which @selector(selectedWindowLevel:) will be called when a menu item is selected
396 */
397- (NSMenu *)menuForWindowLevelsNotifyingTarget:(id)target;
398
399@end
400
401//Controls a contact list view
402@protocol AIContactListViewController <NSObject>       
403- (NSView *)contactListView;
404@end
405
406//Manages contact list view controllers
407@protocol AIContactListController <NSObject>   
408- (id <AIContactListViewController>)contactListViewController;
409@end
410
411/*!
412 * @protocol AIMessageDisplayController
413 * @brief    The message display controller is responsible for, unsurprisingly, the actual display of messages.
414 *
415 * The display controller manages a view ("messageView") which will be inserted along with other UI elements such
416 * as a text entry area into a window.  The Interface Plugin knows nothing about how the AIMessageDisplayController
417 * keeps its messageView up to date, nor should it, but knows that the view will show messages.
418 *
419 * The AIMessageDisplayController is informed when the message view which is using it is closing.
420 *
421 * This is, for example, the AIWebKitMessageViewController.
422 */
423@protocol AIMessageDisplayController <NSObject>
424- (void)setChatContentSource:(NSString *)source;
425- (NSString *)chatContentSource;
426- (NSString *)contentSourceName; // Unique name for this particular style of "content source".
427
428- (NSView *)messageView;
429- (NSView *)messageScrollView;
430- (void)messageViewIsClosing;
431- (void)clearView;
432@end
433
434/*
435 * @protocol AIMessageDisplayPlugin
436 * @brief    A AIMessageDisplayPlugin provides AIMessageDisplayController objects on demand.
437 *
438 * The WebKit display plugin is one example.
439 */
440@protocol AIMessageDisplayPlugin <NSObject, AIPlugin>   
441- (id <AIMessageDisplayController>)messageDisplayControllerForChat:(AIChat *)inChat;
442@end
443
444@protocol AIContactListTooltipEntry <NSObject>
445- (NSString *)labelForObject:(AIListObject *)inObject;
446- (NSAttributedString *)entryForObject:(AIListObject *)inObject;
447- (BOOL)shouldDisplayInContactInspector;
448@end
449
450@protocol AIFlashObserver <NSObject>
451- (void)flash:(int)value;
452@end
453
454//Handles any attributed text entry
455@protocol AITextEntryView
456- (void)setAttributedString:(NSAttributedString *)inAttributedString;
457- (void)setTypingAttributes:(NSDictionary *)attrs;
458- (BOOL)availableForSending;
459- (AIChat *)chat;
460@end
461
462@protocol AIInterfaceComponent <NSObject>
463- (void)openInterface;
464- (void)closeInterface;
465- (id)openChat:(AIChat *)chat inContainerWithID:(NSString *)containerID withName:(NSString *)containerName atIndex:(int)index;
466- (void)setActiveChat:(AIChat *)inChat;
467- (void)moveChat:(AIChat *)chat toContainerWithID:(NSString *)containerID index:(int)index;
468- (void)moveChatToNewContainer:(AIChat *)inChat;
469- (void)closeChat:(AIChat *)chat;
470- (AIMessageWindowController *)openContainerWithID:(NSString *)containerID name:(NSString *)containerName;
471/*!
472 * @brief Return an array of NSDictionary objects for all open containers with associated information
473 *
474 * The returned array has zero or more NSDictionary objects with the following information for each container
475 *      Key                     Value
476 *      @"ID"           NSString of the containerID
477 *      @"Frame"        NSString of the window's [NSWindow frame]
478 *      @"Content"      NSArray of the AIChat objects within that container
479 *      @"ActiveChat"   AIChat that is currently active
480 *      @"Name"         NSString of the container's name
481 */
482- (NSArray *)openContainersAndChats;
483- (NSArray *)openContainerIDs;
484- (NSArray *)openChats;
485- (NSArray *)openChatsInContainerWithID:(NSString *)containerID;
486- (NSString *)containerIDForChat:(AIChat *)chat;
487- (NSWindow *)windowForChat:(AIChat *)chat;
488- (AIChat *)activeChatInWindow:(NSWindow *)window;
489@end
490
491/*!
492 * @protocol AIInterfaceContainer
493 * @brief This protocol is for a general interface element such as the contact list or the container of a chat
494 */
495@protocol AIInterfaceContainer <NSObject>
496- (void)makeActive:(id)sender;  //Make the container active/front
497- (void)close:(id)sender;       //Close the container
498@end
499
500/*!
501 * @brief AIChatWindow defines the protocol for an object which contains one or more AIChatContainers
502 */
503@protocol AIChatWindowController <NSObject>
504/*
505 * @brief Get an array of all the chats within this window controller's window.
506 */
507- (NSArray *)containedChats;
508
509/*
510 * @brief The window
511 */
512- (NSWindow *)window;
513@end
514
515/*!
516 * @protocol AIChatViewController
517 * @brief A AIChatViewController manages everything pertaining to a chat's view area
518 *
519 * It will manage this view, text input, and any associated controls.
520 */
521@protocol AIChatViewController <NSObject>
522- (NSView *)view;
523- (NSScrollView *)messagesScrollView;
524- (AIChat *)chat;
525
526/*!
527 * @brief Show/hide the user list for a group chat.
528 * Does nothing if not in a group chat.
529 */
530- (void)toggleUserList;
531
532/*!
533 * @brief Is the user list visible for a group chat?
534 */
535- (BOOL)userListVisible;
536@end
537
538/*!
539 * @protocol AIChatContainer
540 * @brief This protocol is for an object which displays a single chat (e.g. a tab in a chat window)
541 */
542@protocol AIChatContainer <AIInterfaceContainer>
543/*
544 * @brief Get the window controller which holds this AIChatContainer
545 */
546- (id <AIChatWindowController>)windowController;
547
548/*
549 * @brief Get the view controller for this AIChatContainer
550 */
551- (id <AIChatViewController>)chatViewController;
552@end
553
554@protocol AIContactListComponent <NSObject>
555/*!
556 * @brief Show the contact list window and bring Adium to the front
557 */
558- (void)showContactListAndBringToFront:(BOOL)bringToFront;
559- (BOOL)contactListIsVisibleAndMain;
560- (BOOL)contactListIsVisible;
561- (void)closeContactList;
562@end
563
564@protocol AIMultiContactListComponent <AIContactListComponent>
565- (id)detachContactList:(AIListGroup *)contactList;
566- (void)nextDetachedContactList;
567- (void)previousDetachedContactList;
568- (unsigned)detachedContactListCount;
569@end
570
571//Custom printing informal protocol
572@interface NSObject (AdiumPrinting)
573- (void)adiumPrint:(id)sender;
574- (BOOL)validatePrintMenuItem:(NSMenuItem *)menuItem;
575@end
576
577@interface NSWindowController (AdiumBorderlessWindowClosing)
578- (BOOL)windowPermitsClose;
579@end
Note: See TracBrowser for help on using the browser.