1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
|
/*
* Jitsi, the OpenSource Java VoIP and Instant Messaging client.
*
* Distributable under LGPL license.
* See terms of license at gnu.org.
*/
package net.java.sip.communicator.service.gui;
import java.awt.*;
import java.awt.event.*;
import java.util.*;
import java.util.List;
import net.java.sip.communicator.service.contactlist.*;
import net.java.sip.communicator.service.gui.event.*;
import net.java.sip.communicator.service.protocol.*;
/**
* The <tt>UIService</tt> offers generic access to the graphical user interface
* for all modules that would like to interact with the user.
* <p>
* Through the <tt>UIService</tt> all modules can add their own components in
* different menus, toolbars, etc. within the ui. Each <tt>UIService</tt>
* implementation should export its supported "plugable" containers - a set of
* <tt>Container</tt>s corresponding to different "places" in the application,
* where a module can add a component.
* <p>
* The <tt>UIService</tt> provides also methods that would allow to other
* modules to control the visibility, size and position of the main application
* window. Some of these methods are: setVisible, minimize, maximize, resize,
* move, etc.
* <p>
* A way to show different types of simple windows is provided to allow other
* modules to show different simple messages, like warning or error messages. In
* order to show a simple warning message, a module should invoke the
* getPopupDialog method and then one of the showXXX methods, which corresponds
* best to the required dialog.
* <p>
* Certain components within the GUI, like "AddContact" window for example,
* could be also shown from outside the UI bundle. To make one of these
* component exportable, the <tt>UIService</tt> implementation should attach to
* it an <tt>WindowID</tt>. A window then could be shown, by invoking
* <code>getExportedWindow(WindowID)</code> and then <code>show</code>. The
* <tt>WindowID</tt> above should be obtained from
* <code>getSupportedExportedWindows</code>.
*
* @author Yana Stamcheva
* @author Dmitri Melnikov
* @author Adam Netocny
* @author Lyubomir Marinov
*/
public interface UIService
{
/**
* Returns TRUE if the application is visible and FALSE otherwise. This
* method is meant to be used by the systray service in order to detect the
* visibility of the application.
*
* @return <code>true</code> if the application is visible and
* <code>false</code> otherwise.
*
* @see #setVisible(boolean)
*/
public boolean isVisible();
/**
* Shows or hides the main application window depending on the value of
* parameter <code>visible</code>. Meant to be used by the systray when it
* needs to show or hide the application.
*
* @param visible if <code>true</code>, shows the main application window;
* otherwise, hides the main application window.
*
* @see #isVisible()
*/
public void setVisible(boolean visible);
/**
* Returns the current location of the main application window. The returned
* point is the top left corner of the window.
*
* @return The top left corner coordinates of the main application window.
*/
public Point getLocation();
/**
* Locates the main application window to the new x and y coordinates.
*
* @param x The new x coordinate.
* @param y The new y coordinate.
*/
public void setLocation(int x, int y);
/**
* Returns the size of the main application window.
*
* @return the size of the main application window.
*/
public Dimension getSize();
/**
* Sets the size of the main application window.
*
* @param width The width of the window.
* @param height The height of the window.
*/
public void setSize(int width, int height);
/**
* Minimizes the main application window.
*/
public void minimize();
/**
* Maximizes the main application window.
*/
public void maximize();
/**
* Restores the main application window.
*/
public void restore();
/**
* Resizes the main application window with the given width and height.
*
* @param width The new width.
* @param height The new height.
*/
public void resize(int width, int height);
/**
* Moves the main application window to the given coordinates.
*
* @param x The x coordinate.
* @param y The y coordinate.
*/
public void move(int x, int y);
/**
* Brings the focus to the main application window.
*/
public void bringToFront();
/**
* Sets the exitOnClose property. When TRUE, the user could exit the
* application by simply closing the main application window (by clicking
* the X button or pressing Alt-F4). When set to FALSE the main application
* window will be only hidden.
*
* @param exitOnClose When TRUE, the user could exit the application by
* simply closing the main application window (by clicking the X
* button or pressing Alt-F4). When set to FALSE the main
* application window will be only hidden.
*/
public void setExitOnMainWindowClose(boolean exitOnClose);
/**
* Returns TRUE if the application could be exited by closing the main
* application window, otherwise returns FALSE.
*
* @return Returns TRUE if the application could be exited by closing the
* main application window, otherwise returns FALSE
*/
public boolean getExitOnMainWindowClose();
/**
* Returns an exported window given by the <tt>WindowID</tt>. This could be
* for example the "Add contact" window or any other window within the
* application. The <tt>windowID</tt> should be one of the WINDOW_XXX
* obtained by the <tt>getSupportedExportedWindows</tt> method.
*
* @param windowID One of the WINDOW_XXX WindowID-s.
* @throws IllegalArgumentException if the specified <tt>windowID</tt> is
* not recognized by the implementation (note that
* implementations MUST properly handle all WINDOW_XXX ID-s.
* @return the window to be shown.
*/
public ExportedWindow getExportedWindow(WindowID windowID)
throws IllegalArgumentException;
/**
* Returns an exported window given by the <tt>WindowID</tt>. This could be
* for example the "Add contact" window or any other window within the
* application. The <tt>windowID</tt> should be one of the WINDOW_XXX
* obtained by the <tt>getSupportedExportedWindows</tt> method.
*
* @param windowID One of the WINDOW_XXX WindowID-s.
* @param params The parameters to be passed to the returned exported
* window.
* @throws IllegalArgumentException if the specified <tt>windowID</tt> is
* not recognized by the implementation (note that
* implementations MUST properly handle all WINDOW_XXX ID-s.
* @return the window to be shown.
*/
public ExportedWindow getExportedWindow(WindowID windowID, Object[] params)
throws IllegalArgumentException;
/**
* Returns a configurable popup dialog, that could be used to show either a
* warning message, error message, information message, etc. or to prompt
* user for simple one field input or to question the user.
*
* @return a <code>PopupDialog</code>.
* @see PopupDialog
*/
public PopupDialog getPopupDialog();
/**
* Returns the <tt>Chat</tt> corresponding to the given <tt>Contact</tt>.
*
* @param contact the <tt>Contact</tt> for which the searched chat is about.
* @return the <tt>Chat</tt> corresponding to the given <tt>Contact</tt>.
*/
public Chat getChat(Contact contact);
/**
* Returns the <tt>Chat</tt> corresponding to the given <tt>ChatRoom</tt>.
*
* @param chatRoom the <tt>ChatRoom</tt> for which the searched chat is
* about.
* @return the <tt>Chat</tt> corresponding to the given <tt>ChatRoom</tt>.
*/
public Chat getChat(ChatRoom chatRoom);
/**
* Returns a list of all open Chats
*
* @return A list of all open Chats
*/
public List<Chat> getChats();
/**
* Get the MetaContact corresponding to the chat.
* The chat must correspond to a one on one conversation. If it is a
* group chat an exception will be thrown.
*
* @param chat The chat to get the MetaContact from
* @return The MetaContact corresponding to the chat.
*/
public MetaContact getChatContact(Chat chat);
/**
* Returns the selected <tt>Chat</tt>.
*
* @return the selected <tt>Chat</tt>.
*/
public Chat getCurrentChat();
/**
* Returns the phone number currently entered in the phone number field.
* This method is meant to be used by plugins that are interested in
* operations with the currently entered phone number.
*
* @return the phone number currently entered in the phone number field.
*/
public String getCurrentPhoneNumber();
/**
* Sets the phone number in the phone number field. This method is meant to
* be used by plugins that are interested in operations with the currently
* entered phone number.
*
* @param phoneNumber the phone number to enter.
*/
public void setCurrentPhoneNumber(String phoneNumber);
/**
* Returns a default implementation of the <tt>SecurityAuthority</tt>
* interface that can be used by non-UI components that would like to launch
* the registration process for a protocol provider. Initially this method
* was meant for use by the systray bundle and the protocol URI handlers.
*
* @param protocolProvider the <tt>ProtocolProviderService</tt> for which
* the authentication window is about.
*
* @return a default implementation of the <tt>SecurityAuthority</tt>
* interface that can be used by non-UI components that would like
* to launch the registration process for a protocol provider.
*/
public SecurityAuthority getDefaultSecurityAuthority(
ProtocolProviderService protocolProvider);
/**
* Returns an iterator over a set of windowID-s. Each <tt>WindowID</tt>
* points to a window in the current UI implementation. Each
* <tt>WindowID</tt> in the set is one of the constants in the
* <tt>ExportedWindow</tt> interface. The method is meant to be used by
* bundles that would like to have access to some windows in the gui - for
* example the "Add contact" window, the "Settings" window, the
* "Chat window", etc.
*
* @return Iterator An iterator to a set containing WindowID-s representing
* all exported windows supported by the current UI implementation.
*/
public Iterator<WindowID> getSupportedExportedWindows();
/**
* Checks if a window with the given <tt>WindowID</tt> is contained in the
* current UI implementation.
*
* @param windowID one of the <tt>WindowID</tt>-s, defined in the
* <tt>ExportedWindow</tt> interface.
* @return <code>true</code> if the component with the given
* <tt>WindowID</tt> is contained in the current UI implementation,
* <code>false</code> otherwise.
*/
public boolean isExportedWindowSupported(WindowID windowID);
/**
* Returns the <tt>WizardContainer</tt> for the current UIService
* implementation. The <tt>WizardContainer</tt> is meant to be implemented
* by the UI service implementation in order to allow other modules to add
* to the GUI <tt>AccountRegistrationWizard</tt> s. Each of these wizards is
* made for a given protocol and should provide a sequence of user interface
* forms through which the user could register a new account.
*
* @return Returns the <tt>AccountRegistrationWizardContainer</tt> for the
* current UIService implementation.
*/
public WizardContainer getAccountRegWizardContainer();
/**
* Returns an iterator over a set containing containerID-s pointing to
* containers supported by the current UI implementation. Each containerID
* in the set is one of the CONTAINER_XXX constants. The method is meant to
* be used by plugins or bundles that would like to add components to the
* user interface. Before adding any component they should use this method
* to obtain all possible places, which could contain external components,
* like different menus, toolbars, etc.
*
* @return Iterator An iterator to a set containing containerID-s
* representing all containers supported by the current UI
* implementation.
*/
public Iterator<Container> getSupportedContainers();
/**
* Checks if the container with the given <tt>Container</tt> is supported
* from the current UI implementation.
*
* @param containderID One of the CONTAINER_XXX Container-s.
* @return <code>true</code> if the container with the given
* <tt>Container</tt> is supported from the current UI
* implementation, <code>false</code> otherwise.
*/
public boolean isContainerSupported(Container containderID);
/**
* Determines whether the Mac OS X screen menu bar is being used by the UI
* for its main menu instead of the Windows-like menu bars at the top of the
* windows.
* <p>
* A common use of the returned indicator is for the purposes of
* platform-sensitive UI since Mac OS X employs a single screen menu bar,
* Windows and Linux/GTK+ use per-window menu bars and it is inconsistent on
* Mac OS X to have the Window-like menu bars.
* </p>
*
* @return <tt>true</tt> if the Mac OS X screen menu bar is being used by
* the UI for its main menu instead of the Windows-like menu bars at
* the top of the windows; otherwise, <tt>false</tt>
*/
public boolean useMacOSXScreenMenuBar();
/**
* Shows or hides the "Tools > Settings" configuration window.
* <p>
* The method hides the implementation-specific details of the configuration
* window from its clients and allows the UI to completely control, for
* example, how many instances of it are visible at one and the same time.
* <p>
*
* @param visible <tt>true</tt> to show the "Tools > Settings"
* configuration window; <tt>false</tt> to hide it
*
* @deprecated instead use getConfigurationContainer().setVisible(visible)
*/
@Deprecated
public void setConfigurationWindowVisible(boolean visible);
/**
* Returns the <tt>ConfigurationContainer</tt> associated with this
* <tt>UIService</tt>.
*
* @return the <tt>ConfigurationContainer</tt> associated with this
* <tt>UIService</tt>
*/
public ConfigurationContainer getConfigurationContainer();
/**
* Returns the create account window.
*
* @return the create account window
*/
public CreateAccountWindow getCreateAccountWindow();
/**
* Adds the given <tt>WindowListener</tt> listening for events triggered
* by the main UIService component. This is normally the main application
* window component, the one containing the contact list. This listener
* would also receive events when this window is shown or hidden.
* @param l the <tt>WindowListener</tt> to add
*/
public void addWindowListener(WindowListener l);
/**
* Removes the given <tt>WindowListener</tt> from the list of registered
* listener. The <tt>WindowListener</tt> is listening for events
* triggered by the main UIService component. This is normally the main
* application window component, the one containing the contact list. This
* listener would also receive events when this window is shown or hidden.
* @param l the <tt>WindowListener</tt> to remove
*/
public void removeWindowListener(WindowListener l);
/**
* Provides all currently instantiated <tt>Chats</tt>.
*
* @return all active <tt>Chats</tt>.
*/
public Collection <Chat> getAllChats();
/**
* Registers a <tt>NewChatListener</tt> to be informed when new
* <tt>Chats</tt> are created.
* @param listener listener to be registered
*/
public void addChatListener(ChatListener listener);
/**
* Removes the registration of a <tt>NewChatListener</tt>.
* @param listener listener to be unregistered
*/
public void removeChatListener(ChatListener listener);
/**
* Repaints and revalidates the whole UI. This method is meant to be used
* to runtime apply a skin and refresh automatically the user interface.
*/
public void repaintUI();
/**
* Creates a new <tt>Call</tt> with a specific set of participants.
*
* @param participants an array of <tt>String</tt> values specifying the
* participants to be included into the newly created <tt>Call</tt>
*/
public void createCall(String[] participants);
/**
* Starts a new <tt>Chat</tt> with a specific set of participants.
*
* @param participants an array of <tt>String</tt> values specifying the
* participants to be included into the newly created <tt>Chat</tt>
*/
public void startChat(String[] participants);
/**
* Creates a contact list component.
*
* @return the created <tt>ContactList</tt>
*/
public ContactList createContactListComponent();
/**
* Returns a collection of all currently in progress calls.
*
* @return a collection of all currently in progress calls.
*/
public Collection<Call> getInProgressCalls();
}
|