/*
* Jitsi, the OpenSource Java VoIP and Instant Messaging client.
*
* Copyright @ 2015 Atlassian Pty Ltd
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
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.muc.*;
import net.java.sip.communicator.service.protocol.*;
import net.java.sip.communicator.util.account.*;
/**
* 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 "pluggable" 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
* @author Hristo Terezov
*/
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();
/**
* Called from the systray service when a tray has been initialized and
* hiding (instead of minimizing or exiting) is possible). If hiding is
* possible and the option to minimize is not selected, the application
* gets hidden on clicking 'X'.
*
* @param true if a tray icon was loaded.
*/
public void setMainWindowCanHide(boolean exitOnClose);
/**
* 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>Contact</tt>.
*
* @param contact the <tt>Contact</tt> for which the searched chat is about.
* @param escapedMessageID the message ID of the message that should be
* excluded from the history when the last one is loaded in the chat
* @return the <tt>Chat</tt> corresponding to the given <tt>Contact</tt>.
*/
public Chat getChat(Contact contact, String escapedMessageID);
/**
* 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();
/**
* 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);
/**
* 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>
* @param isSmsEnabled whether sms option should be enabled if possible
*/
public void startChat(String[] participants, boolean isSmsEnabled);
/**
* Creates a contact list component.
*
* @param clContainer the parent contact list container
* @return the created <tt>ContactList</tt>
*/
public ContactList createContactListComponent(
ContactListContainer clContainer);
/**
* Returns a collection of all currently in progress calls.
*
* @return a collection of all currently in progress calls.
*/
public Collection<Call> getInProgressCalls();
/**
* Returns the login manager used by the current UI implementation.
*
* @return the login manager used by the current UI implementation
*/
public LoginManager getLoginManager();
/**
* Opens a chat room window for the given <tt>ChatRoomWrapper</tt> instance.
*
* @param chatRoom the chat room associated with the chat room window
*/
public void openChatRoomWindow(ChatRoomWrapper chatRoom);
/**
* Closes the chat room window for the given <tt>ChatRoomWrapper</tt>
* instance.
*
* @param chatRoom the chat room associated with the chat room window
*/
public void closeChatRoomWindow(ChatRoomWrapper chatRoom);
/**
* Shows Add chat room dialog.
*/
public void showAddChatRoomDialog();
/**
* Shows chat room open automatically configuration dialog.
* @param chatRoomId the chat room id of the chat room associated with the
* dialog
* @param pps the protocol provider service of the chat room
*/
public void showChatRoomAutoOpenConfigDialog(
ProtocolProviderService pps, String chatRoomId);
}