net.java.sip.communicator.service.gui
Interface UIService

All Known Implementing Classes:

UIServiceImpl

public interface UIService

The UIService offers generic access to the graphical user interface for all modules that would like to interact with the user.

Through the UIService all modules can add their own components in different menus, toolbars, etc. within the ui. Each UIService implementation should export its supported "plugable" containers - a set of Containers corresponding to different "places" in the application, where a module can add a component.

The UIService 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.

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.

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 UIService implementation should attach to it an WindowID. A window then could be shown, by invoking getExportedWindow(WindowID) and then show. The WindowID above should be obtained from getSupportedExportedWindows.

Author:

Yana Stamcheva, Dmitri Melnikov, Adam Netocny, Lyubomir Marinov

Method Summary

void	addChatListener(ChatListener listener) Registers a NewChatListener to be informed when new Chats are created.
void	addWindowListener(WindowListener l) Adds the given WindowListener listening for events triggered by the main UIService component.
void	bringToFront() Brings the focus to the main application window.
void	createCall(String[] participants) Creates a new Call with a specific set of participants.
ContactList	createContactListComponent() Creates a contact list component.
WizardContainer	getAccountRegWizardContainer() Returns the WizardContainer for the current UIService implementation.
Collection<Chat>	getAllChats() Provides all currently instantiated Chats.
Chat	getChat(ChatRoom chatRoom) Returns the Chat corresponding to the given ChatRoom.
Chat	getChat(Contact contact) Returns the Chat corresponding to the given Contact.
MetaContact	getChatContact(Chat chat) Get the MetaContact corresponding to the chat.
List<Chat>	getChats() Returns a list of all open Chats
ConfigurationContainer	getConfigurationContainer() Returns the ConfigurationContainer associated with this UIService.
CreateAccountWindow	getCreateAccountWindow() Returns the create account window.
Chat	getCurrentChat() Returns the selected Chat.
String	getCurrentPhoneNumber() Returns the phone number currently entered in the phone number field.
SecurityAuthority	getDefaultSecurityAuthority(ProtocolProviderService protocolProvider) Returns a default implementation of the SecurityAuthority interface that can be used by non-UI components that would like to launch the registration process for a protocol provider.
boolean	getExitOnMainWindowClose() Returns TRUE if the application could be exited by closing the main application window, otherwise returns FALSE.
ExportedWindow	getExportedWindow(WindowID windowID) Returns an exported window given by the WindowID.
ExportedWindow	getExportedWindow(WindowID windowID, Object[] params) Returns an exported window given by the WindowID.
Point	getLocation() Returns the current location of the main application window.
PopupDialog	getPopupDialog() Returns a configurable popup dialog, that could be used to show either a warning message, error message, information message, etc.
Dimension	getSize() Returns the size of the main application window.
Iterator<Container>	getSupportedContainers() Returns an iterator over a set containing containerID-s pointing to containers supported by the current UI implementation.
Iterator<WindowID>	getSupportedExportedWindows() Returns an iterator over a set of windowID-s.
boolean	isContainerSupported(Container containderID) Checks if the container with the given Container is supported from the current UI implementation.
boolean	isExportedWindowSupported(WindowID windowID) Checks if a window with the given WindowID is contained in the current UI implementation.
boolean	isVisible() Returns TRUE if the application is visible and FALSE otherwise.
void	maximize() Maximizes the main application window.
void	minimize() Minimizes the main application window.
void	move(int x, int y) Moves the main application window to the given coordinates.
void	removeChatListener(ChatListener listener) Removes the registration of a NewChatListener.
void	removeWindowListener(WindowListener l) Removes the given WindowListener from the list of registered listener.
void	repaintUI() Repaints and revalidates the whole UI.
void	resize(int width, int height) Resizes the main application window with the given width and height.
void	restore() Restores the main application window.
void	setConfigurationWindowVisible(boolean visible) Deprecated. instead use getConfigurationContainer().setVisible(visible)
void	setCurrentPhoneNumber(String phoneNumber) Sets the phone number in the phone number field.
void	setExitOnMainWindowClose(boolean exitOnClose) Sets the exitOnClose property.
void	setLocation(int x, int y) Locates the main application window to the new x and y coordinates.
void	setSize(int width, int height) Sets the size of the main application window.
void	setVisible(boolean visible) Shows or hides the main application window depending on the value of parameter visible.
void	startChat(String[] participants) Starts a new Chat with a specific set of participants.
boolean	useMacOSXScreenMenuBar() 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.

Method Detail

isVisible

boolean isVisible()

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.

Returns:

true if the application is visible and false otherwise.

See Also:

setVisible(boolean)

setVisible

void setVisible(boolean visible)

Shows or hides the main application window depending on the value of parameter visible. Meant to be used by the systray when it needs to show or hide the application.

Parameters:

visible - if true, shows the main application window; otherwise, hides the main application window.

See Also:

isVisible()

getLocation

Point getLocation()

Returns the current location of the main application window. The returned point is the top left corner of the window.

Returns:

The top left corner coordinates of the main application window.

setLocation

void setLocation(int x,
                 int y)

Locates the main application window to the new x and y coordinates.

Parameters:

x - The new x coordinate.

y - The new y coordinate.

getSize

Dimension getSize()

Returns the size of the main application window.

Returns:

the size of the main application window.

setSize

void setSize(int width,
             int height)

Sets the size of the main application window.

Parameters:

width - The width of the window.

height - The height of the window.

minimize

void minimize()

Minimizes the main application window.

maximize

void maximize()

Maximizes the main application window.

restore

void restore()

Restores the main application window.

resize

void resize(int width,
            int height)

Resizes the main application window with the given width and height.

Parameters:

width - The new width.

height - The new height.

move

void move(int x,
          int y)

Moves the main application window to the given coordinates.

Parameters:

x - The x coordinate.

y - The y coordinate.

bringToFront

void bringToFront()

Brings the focus to the main application window.

setExitOnMainWindowClose

void setExitOnMainWindowClose(boolean exitOnClose)

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.

Parameters:

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.

getExitOnMainWindowClose

boolean getExitOnMainWindowClose()

Returns TRUE if the application could be exited by closing the main application window, otherwise returns FALSE.

Returns:

Returns TRUE if the application could be exited by closing the main application window, otherwise returns FALSE

getExportedWindow

ExportedWindow getExportedWindow(WindowID windowID)
                                 throws IllegalArgumentException

Returns an exported window given by the WindowID. This could be for example the "Add contact" window or any other window within the application. The windowID should be one of the WINDOW_XXX obtained by the getSupportedExportedWindows method.

Parameters:

windowID - One of the WINDOW_XXX WindowID-s.

Returns:

the window to be shown.

Throws:

IllegalArgumentException - if the specified windowID is not recognized by the implementation (note that implementations MUST properly handle all WINDOW_XXX ID-s.

getExportedWindow

ExportedWindow getExportedWindow(WindowID windowID,
                                 Object[] params)
                                 throws IllegalArgumentException

Returns an exported window given by the WindowID. This could be for example the "Add contact" window or any other window within the application. The windowID should be one of the WINDOW_XXX obtained by the getSupportedExportedWindows method.

Parameters:

windowID - One of the WINDOW_XXX WindowID-s.

params - The parameters to be passed to the returned exported window.

Returns:

the window to be shown.

Throws:

IllegalArgumentException - if the specified windowID is not recognized by the implementation (note that implementations MUST properly handle all WINDOW_XXX ID-s.

getPopupDialog

PopupDialog getPopupDialog()

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.

Returns:

a PopupDialog.

See Also:

PopupDialog

getChat

Chat getChat(Contact contact)

Returns the Chat corresponding to the given Contact.

Parameters:

contact - the Contact for which the searched chat is about.

Returns:

the Chat corresponding to the given Contact.

getChat

Chat getChat(ChatRoom chatRoom)

Returns the Chat corresponding to the given ChatRoom.

Parameters:

chatRoom - the ChatRoom for which the searched chat is about.

Returns:

the Chat corresponding to the given ChatRoom.

getChats

List<Chat> getChats()

Returns a list of all open Chats

Returns:

A list of all open Chats

getChatContact

MetaContact getChatContact(Chat chat)

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.

Parameters:

chat - The chat to get the MetaContact from

Returns:

The MetaContact corresponding to the chat.

getCurrentChat

Chat getCurrentChat()

Returns the selected Chat.

Returns:

the selected Chat.

getCurrentPhoneNumber

String getCurrentPhoneNumber()

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.

Returns:

the phone number currently entered in the phone number field.

setCurrentPhoneNumber

void setCurrentPhoneNumber(String phoneNumber)

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.

Parameters:

phoneNumber - the phone number to enter.

getDefaultSecurityAuthority

SecurityAuthority getDefaultSecurityAuthority(ProtocolProviderService protocolProvider)

Returns a default implementation of the SecurityAuthority 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.

Parameters:

protocolProvider - the ProtocolProviderService for which the authentication window is about.

Returns:

a default implementation of the SecurityAuthority interface that can be used by non-UI components that would like to launch the registration process for a protocol provider.

getSupportedExportedWindows

Iterator<WindowID> getSupportedExportedWindows()

Returns an iterator over a set of windowID-s. Each WindowID points to a window in the current UI implementation. Each WindowID in the set is one of the constants in the ExportedWindow 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.

Returns:

Iterator An iterator to a set containing WindowID-s representing all exported windows supported by the current UI implementation.

isExportedWindowSupported

boolean isExportedWindowSupported(WindowID windowID)

Checks if a window with the given WindowID is contained in the current UI implementation.

Parameters:

windowID - one of the WindowID-s, defined in the ExportedWindow interface.

Returns:

true if the component with the given WindowID is contained in the current UI implementation, false otherwise.

getAccountRegWizardContainer

WizardContainer getAccountRegWizardContainer()

Returns the WizardContainer for the current UIService implementation. The WizardContainer is meant to be implemented by the UI service implementation in order to allow other modules to add to the GUI AccountRegistrationWizard 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.

Returns:

Returns the AccountRegistrationWizardContainer for the current UIService implementation.

getSupportedContainers

Iterator<Container> getSupportedContainers()

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.

Returns:

Iterator An iterator to a set containing containerID-s representing all containers supported by the current UI implementation.

isContainerSupported

boolean isContainerSupported(Container containderID)

Checks if the container with the given Container is supported from the current UI implementation.

Parameters:

containderID - One of the CONTAINER_XXX Container-s.

Returns:

true if the container with the given Container is supported from the current UI implementation, false otherwise.

useMacOSXScreenMenuBar

boolean useMacOSXScreenMenuBar()

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.

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.

Returns:

true 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, false

setConfigurationWindowVisible

@Deprecated
void setConfigurationWindowVisible(boolean visible)

Deprecated. instead use getConfigurationContainer().setVisible(visible)

Shows or hides the "Tools > Settings" configuration window.

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.

Parameters:

visible - true to show the "Tools > Settings" configuration window; false to hide it

getConfigurationContainer

ConfigurationContainer getConfigurationContainer()

Returns the ConfigurationContainer associated with this UIService.

Returns:

the ConfigurationContainer associated with this UIService

getCreateAccountWindow

CreateAccountWindow getCreateAccountWindow()

Returns the create account window.

Returns:

the create account window

addWindowListener

void addWindowListener(WindowListener l)

Adds the given WindowListener 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.

Parameters:

l - the WindowListener to add

removeWindowListener

void removeWindowListener(WindowListener l)

Removes the given WindowListener from the list of registered listener. The WindowListener 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.

Parameters:

l - the WindowListener to remove

getAllChats

Collection<Chat> getAllChats()

Provides all currently instantiated Chats.

Returns:

all active Chats.

addChatListener

void addChatListener(ChatListener listener)

Registers a NewChatListener to be informed when new Chats are created.

Parameters:

listener - listener to be registered

removeChatListener

void removeChatListener(ChatListener listener)

Removes the registration of a NewChatListener.

Parameters:

listener - listener to be unregistered

repaintUI

void repaintUI()

Repaints and revalidates the whole UI. This method is meant to be used to runtime apply a skin and refresh automatically the user interface.

createCall

void createCall(String[] participants)

Creates a new Call with a specific set of participants.

Parameters:

participants - an array of String values specifying the participants to be included into the newly created Call

startChat

void startChat(String[] participants)

Starts a new Chat with a specific set of participants.

Parameters:

participants - an array of String values specifying the participants to be included into the newly created Chat

createContactListComponent

ContactList createContactListComponent()

Creates a contact list component.

Returns:

the created ContactList