diff --git a/src/net/java/sip/communicator/service/gui/ContainerID.java b/src/net/java/sip/communicator/service/gui/ContainerID.java new file mode 100644 index 000000000..59ffa4f53 --- /dev/null +++ b/src/net/java/sip/communicator/service/gui/ContainerID.java @@ -0,0 +1,15 @@ +package net.java.sip.communicator.service.gui; + +public class ContainerID{ + + private String containerName; + + public ContainerID(String containerName){ + this.containerName = containerName; + } + + public String getID(){ + return this.containerName; + } + +} diff --git a/src/net/java/sip/communicator/service/gui/UIService.java b/src/net/java/sip/communicator/service/gui/UIService.java index 8d1d9ccad..61493d546 100644 --- a/src/net/java/sip/communicator/service/gui/UIService.java +++ b/src/net/java/sip/communicator/service/gui/UIService.java @@ -6,157 +6,147 @@ */ package net.java.sip.communicator.service.gui; -import net.java.sip.communicator.service.protocol.*; +import java.util.Iterator; /** - * The UIService provides an interface towards towards that part of the - * SIP Communicator that interacts with users and offers them a way to make, - * accept, manage or handup calls. - * - * In order for the UIService to support a communications protocol, a - * Provider implementation of the specified protocol needs to be registered with - * the service. - * * Plugins using the service in order to add featuress to the user interface * may do that using one of the addXxx() methods. * - * - * @author Emil Ivov + * @author Yana Stamcheva */ public interface UIService { - public static final String COMPONENT_CONSTRAINT_MENU_FILE = "File"; - public static final String COMPONENT_CONSTRAINT_MENU_VIEW = "View"; - public static final String COMPONENT_CONSTRAINT_MENU_TOOLS = "Tools"; - public static final String COMPONENT_CONSTRAINT_MENU_SETTINGS = "Settings"; - public static final String COMPONENT_CONSTRAINT_MENU_HELP = "Help"; - public static final String COMPONENT_CONSTRAINT_MENU_CALL = "Call"; - public static final String COMPONENT_CONSTRAINT_MENU_ACCOUNT = "Account"; - public static final String COMPONENT_CONSTRAINT_MENU_CONTACT = "Contact"; - public static final String COMPONENT_CONSTRAINT_MENU_BAR = "Menu Bar"; - - public static final String UI_LIB_SWING = "Swing"; - public static final String UI_LIB_SWT = "SWT"; - public static final String UI_LIB_AWT = "AWT"; - - /** - * Registers the specified telephony provider with the user interface. The - * PhoneUIService implementation will automatically add itself as a state - * listener of the specified provider and react in accordance with states - * coming from that listener. It will also deliver all relevant user - * call control requests to that provider. - * @param provider the provider to register. - */ - public void registerProvider(ProtocolProviderService provider); - - /** - * Specifies whether or not the phone ui should be visible (In case for - * example we'd only like a sys tray icon or a contact list to show). - * @param visible a boolean specifying whether the phone ui should be visible - */ - public void setVisible(boolean visible); - - //services offered to bundles/plugins that would like to interact with the - //gui. + public static final ContainerID CONTAINER_FILE_MENU + = new ContainerID("File"); + public static final ContainerID CONTAINER_TOOLS_MENU + = new ContainerID("Tools"); + public static final ContainerID CONTAINER_VIEW_MENU + = new ContainerID("View"); + public static final ContainerID CONTAINER_HELP_MENU + = new ContainerID("Help"); + public static final ContainerID CONTAINER_SETTINGS_MENU + = new ContainerID("Settings"); + public static final ContainerID CONTAINER_MAIN_TOOL_BAR + = new ContainerID("MainToolBar"); + public static final ContainerID CONTAINER_CHAT_TOOL_BAR + = new ContainerID("ChatToolBar"); + public static final ContainerID CONTAINER_CHAT_NEW_TOOL_BAR + = new ContainerID("NewChatToolBar"); + public static final ContainerID CONTAINER_RIGHT_BUTTON_MENU + = new ContainerID("RightButtonMenu"); + public static final ContainerID CONTAINER_CONFIGURATION_MENU + = new ContainerID("ConfigurationMenu"); + public static final ContainerID CONTAINER_CHAT_MENU_BAR + = new ContainerID("ChatMenuBar"); + public static final ContainerID CONTAINER_CHAT_FILE_MENU + = new ContainerID("ChatFileMenu"); + public static final ContainerID CONTAINER_CHAT_EDIT_MENU + = new ContainerID("ChatEditMenu"); + public static final ContainerID CONTAINER_CHAT_SETTINGS_MENU + = new ContainerID("ChatSettingsMenu"); + public static final ContainerID CONTAINER_CHAT_HELP_MENU + = new ContainerID("ChatHelpMenu"); + + public static final String START = "Start"; + public static final String END = "End"; + public static final String TOP = "Top"; + public static final String BOTTOM = "Bottom"; + public static final String LEFT = "Left"; + public static final String RIGHT = "Right"; + /** - * Returns an array of Call objects containing the current set of ongoing - * calls. One could obtain specific call participants through by querying - * Call methods - * @return an array of Call objects reflecting on-going calls. - */ - public Call[] getActiveCalls(); - - /** - * Returns the name of the library used to implement the service. In case - * the implementation is using Swing, SWT, or pure AWT it MUST return one of - * the UI_LIB_XXX constants. The method may be used by plugins that would - * like to retrieve ui components - * @return String - */ - public String getUiLibName(); - - /** - * Returns an array of UI lib names indicating that the implementation is - * able to handle components registered by external plugins/bungles in case - * they are implemented using one of the returned lib names. The lib names - * returned by this method should be one or more of the UI_LIB_XXX constants, - * but callers of this method must properly handle unknown Strings which might - * be returned by implementations of future versions of this service. - * - * @return an array containing one or more UI_LIB_XXX constants. - */ - public String[] getSupportedUiLibNames(); - - /** - * Adds the specified menuItem to the specified parent menu. The parent String - * MUST be one of the MENU_XXX constants. It is up to the service - * implementation to verify that "menuItem" is an instance of a class - * compatible with the gui library used by it. If this is not the case and - * adding the requested object would not be possible the implementation - * MUST through an exception. - * - * @param parent one of the MENU_XXX string constants indicating the parent - * menu that this menuItem should be added to. - * @param menuItem the item to add. - * @throws ClassCastException if the menuItem is an - * instance of a class not supported by the service implementation. - * @throws IllegalArgumentException if the specified parent is not - * recognized by the implementation (note that implementations MUST properly - * handle all MENU_XXX strings as eventual parents even if they do not - * correspond to a menu with the same title and may be organized at the will - * of the implementor). + * Adds the specified UI component to the container given by ContainerID. + * The method is meant to be used by plugins or bundles that would like to add + * components to the user interface. The containerID is used by the + * implementation to determine the place where the component should be added. + * The containerID SHOULD be one of the CONTAINER_XXX constants. It is up + * to the service implementation to verify that component is an + * instance of a class compatible with the gui library used by it. If this + * is not the case and adding the requested object would not be possible the + * implementation MUST through a ClassCastException exception. + * Implementations of this service MUST understand and know how to handle + * all ContainerID-s defined by this interface, they MAY also define additional constraints. + * In case the addComponent method is called with a containerID that the + * implementation does not understand it MUST through a java.lang.IllegalArgumentException + *
+ * @param containerID One of the CONTAINER_XXX ContainerID-s. + * @param component The component to be added. + * @throws ClassCastException if component is not an + * instance of a class supported by the service implementation. An SWT impl + * would, for example through a ClassCastException if handed a + * java.awt.Component + * @throws IllegalArgumentException if the specified containerID + * is not recognized by the implementation (note that implementations + * MUST properly handle all CONTAINER_XXX containerID-s. */ - public void addMenuItem(String parent, Object menuItem) + public void addComponent(ContainerID containerID, Object component) throws ClassCastException, IllegalArgumentException; - + /** - * Adds the specified UI component to the user interface according to the - * provided string constraint. The method is meant to be used by plugins or - * bundles that would like to add components to the user interface. The - * constraint string is used by the implementation to determine - * the place where the component should be added. The constraint - * String SHOULD be one of the COMPONENT_CONSTRAINT_XXX constants. It is up - * to the service implementation to verify that component is an + * Adds the specified UI component to the container given by containerID at + * the position specified by constraint String. The method is meant to be used + * by plugins or bundles that would like to add components to the user interface. + * The containerID is used by the implementation to determine the place where + * the component should be added. The containerID SHOULD be one of the + * CONTAINER_XXX constants. The constraint String is used to determine the + * exact position of the component in the container (LEFT, RIGHT, START, etc.). The + * constraint String SHOULD be one of the START, END, TOP, BOTTOM, etc. + * String constants. + *
+ * It is up to the service implementation to verify that component is an * instance of a class compatible with the gui library used by it. If this * is not the case and adding the requested object would not be possible the * implementation MUST through a ClassCastException exception. - * Implementations of this service MUST understant and know how to handle - * all COMPONENT_CONSTRAINT_XXX Strings defined by this interface, they - * MAY also define additional constraints. In case the addComponent method - * is called with a constraint that the implementation does - * not understand it MUST through a java.lang.IllegalArgumentException
+ * Implementations of this service MUST understand and know how to handle + * all ContainerID-s defined by this interface, they MAY also define additional constraints. + * In case the addComponent method is called with a containerID that the + * implementation does not understand it MUST through a java.lang.IllegalArgumentException *
- * @param component the component we'd like to add - * @param constraint a String (possibly one of the COMPONENT_CONSTRAINT_XXX - * strings) indicating the place where the component should be added. + * @param containerID One of the CONTAINER_XXX ContainerID-s. + * @param component The component to be added. * @throws ClassCastException if component is not an * instance of a class supported by the service implementation. An SWT impl * would, for example through a ClassCastException if handed a * java.awt.Component - * @throws IllegalArgumentException if the specified constraint + * @throws IllegalArgumentException if the specified containerID * is not recognized by the implementation (note that implementations - * MUST properly handle all COMPONENT_CONSTRAINT_XXX strings. + * MUST properly handle all CONTAINER_XXX containerID-s. */ - public void addComponent(Object component, String constraint) + public void addComponent(ContainerID containerID, String constraint, Object component) throws ClassCastException, IllegalArgumentException; - - public void addUserActionListener(); - - //========================== CONFIG FORM CONTAINER ============================= + /** - * Returns the ConfigurationContainer object. The method is meant to be used to - * add or remove configuration form to or from the currently used configuration dialog. - */ - public ConfigurationContainer getConfigurationContainer(); + * Returns an iterator to 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 getSupportedContainers(); - //========================== CONFIG ====================================== - //maybe add a method to show the config dialog - - //========================== AuthenticationService ======================= - //these should probably go to a different service - public void requestAuthentication(String realm, String userName, - char[] password); - public String getAuthenticationUserName(); - - //get main frame (for dialogs) + /** + * Returns an iterator to a set containing all constraints supported by the given + * containerID. Each constraint in the set is one of the START, END, TOP, + * BOTTOM, etc. constants. This method is meant to be used to obtain all layout + * constraints supported by a given container. + * + * @param containerID The containerID pointing to the desired container. + * @return Iterator An iterator to a set containing all component constraints + */ + public Iterator getConstraintsForContainer(ContainerID containerID); + + /** + * Returns an Iterator to a set containing all components added to a given constraint. + * Meant to be called in the process of initialization of the container, defined by the + * given constraint in order to obtain all external components that should be added in it. + * + * @param constraint One of the constraints supported by the current UI implementation. + * @return An Iterator to a set containing all components added to a given constraint. + */ + public Iterator getComponentsForContainer(ContainerID containerID) + throws IllegalArgumentException; }