true if the dialog is visible and
+ * false otherwise.
+ */
+ public boolean isDialogVisible();
+
+ /**
+ * Shows the dialog.
+ */
+ public void showDialog();
+
+ /**
+ * Hides the dialog.
+ */
+ public void hideDialog();
+
+ /**
+ * Resizes the dialog with the given width and height.
+ *
+ * @param width The new width.
+ * @param height The new height.
+ */
+ public void resizeDialog(int width, int height);
+
+ /**
+ * Moves the dialog to the given coordinates.
+ *
+ * @param x The x coordinate.
+ * @param y The y coordinate.
+ */
+ public void moveDialog(int x, int y);
+}
diff --git a/src/net/java/sip/communicator/service/gui/PopupDialog.java b/src/net/java/sip/communicator/service/gui/PopupDialog.java
new file mode 100644
index 000000000..c732b94b6
--- /dev/null
+++ b/src/net/java/sip/communicator/service/gui/PopupDialog.java
@@ -0,0 +1,216 @@
+/*
+ * SIP Communicator, 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;
+
+/**
+ * A configurable popup dialog, that could be used from other services for
+ * simple interactions with the user, throught the gui interface. This dialog
+ * allows showing error, warning or info messages, prompting the user for simple
+ * one field input or choice, or asking the user for certain confirmation.
+ *
+ * Three types of dialogs are differentiated: Message, Confirm and Input dialog.
+ * Each of them has several show methods corresponging, allowing additional
+ * specific configuration, like specifying or not a title, confirmation option
+ * or initial value.
+ *
+ * @author Yana Stamcheva
+ */
+public interface PopupDialog extends ExportedDialog {
+ //
+ // Option types
+ //
+ /** Type used for showConfirmDialog. */
+ public static final int YES_NO_OPTION = 0;
+ /** Type used for showConfirmDialog. */
+ public static final int YES_NO_CANCEL_OPTION = 1;
+ /** Type used for showConfirmDialog. */
+ public static final int OK_CANCEL_OPTION = 2;
+
+ //
+ // Return values.
+ //
+ /** Return value from class method if YES is chosen. */
+ public static final int YES_OPTION = 0;
+ /** Return value from class method if NO is chosen. */
+ public static final int NO_OPTION = 1;
+ /** Return value from class method if CANCEL is chosen. */
+ public static final int CANCEL_OPTION = 2;
+ /** Return value form class method if OK is chosen. */
+ public static final int OK_OPTION = 0;
+ /**
+ * Return value from class method if user closes window without
+ * selecting anything.
+ */
+ public static final int CLOSED_OPTION = -1;
+
+ /*
+ * Message types. Meant to be used by the UI implementation to determine
+ * what icon to display and possibly what behavior to give based on the
+ * type.
+ */
+ /** Used for error messages. */
+ public static final int ERROR_MESSAGE = 0;
+ /** Used for information messages. */
+ public static final int INFORMATION_MESSAGE = 1;
+ /** Used for warning messages. */
+ public static final int WARNING_MESSAGE = 2;
+ /** Used for questions. */
+ public static final int QUESTION_MESSAGE = 3;
+ /** No icon is used. */
+ public static final int PLAIN_MESSAGE = -1;
+
+ /**
+ * Shows a question-message dialog requesting input from the user.
+ *
+ * @param message the Object to display.
+ * @return user's input, or null meaning the user
+ * canceled the input
+ */
+ public abstract String showInputPopupDialog(Object message);
+
+ /**
+ * Shows a question-message dialog requesting input from the user, with
+ * the input value initialized to initialSelectionValue.
+ *
+ * @param message the Object to display
+ * @param initialSelectionValue the value used to initialize the input
+ * field
+ * @return user's input, or null meaning the user
+ * canceled the input
+ */
+ public abstract String showInputPopupDialog(Object message,
+ String initialSelectionValue);
+
+
+ /**
+ * Shows a dialog with title title and message type
+ * messageType, requesting input from the user. The message
+ * type is meant to be used by the ui implementation to determine the
+ * icon of the dialog.
+ *
+ * @param message the Object to display
+ * @param title the String to display in the dialog
+ * title bar
+ * @param messageType the type of message that is to be displayed:
+ * ERROR_MESSAGE,
+ * INFORMATION_MESSAGE,
+ * WARNING_MESSAGE,
+ * QUESTION_MESSAGE,
+ * or PLAIN_MESSAGE
+ * @return user's input, or null meaning the user
+ * canceled the input
+ */
+ public abstract String showInputPopupDialog(Object message, String title,
+ int messageType);
+
+ /**
+ * Shows an input dialog, where all options like title, type of message
+ * etc., could be configured. The user will be able to choose from
+ * selectionValues, where null implies the
+ * users can input whatever they wish.
+ * initialSelectionValue is the initial value to prompt
+ * the user with.
+ * It is up to the UI implementation to decide how best to represent the
+ * selectionValues. In the case of swing per example it could
+ * be a JComboBox, JList or
+ * JTextField. The message type is meant to be used by the ui
+ * implementation to determine the icon of the dialog.
+ *
+ * @param message the Object to display
+ * @param title the String to display in the
+ * dialog title bar
+ * @param messageType the type of message to be displayed:
+ * ERROR_MESSAGE,
+ * INFORMATION_MESSAGE,
+ * WARNING_MESSAGE,
+ * QUESTION_MESSAGE,
+ * or PLAIN_MESSAGE
+ *
+ * @param selectionValues an array of Objects that
+ * gives the possible selections
+ * @param initialSelectionValue the value used to initialize the input
+ * field
+ * @return user's input, or null meaning the user
+ * canceled the input
+ */
+ public abstract Object showInputPopupDialog(Object message, String title,
+ int messageType, Object[] selectionValues,
+ Object initialSelectionValue);
+
+ /**
+ * Shows an information-message dialog titled "Message".
+ *
+ * @param message the Object to display
+ */
+ public abstract void showMessagePopupDialog(Object message);
+
+ /**
+ * Shows a dialog that displays a message using a default
+ * icon determined by the messageType parameter.
+ *
+ * @param message the Object to display
+ * @param title the title string for the dialog
+ * @param messageType the type of message to be displayed:
+ * ERROR_MESSAGE,
+ * INFORMATION_MESSAGE,
+ * WARNING_MESSAGE,
+ * QUESTION_MESSAGE,
+ * or PLAIN_MESSAGE
+ */
+ public abstract void showMessagePopupDialog(Object message,
+ String title, int messageType);
+
+ /**
+ * Shows a dialog with the options Yes, No and Cancel.
+ *
+ * @param message the Object to display
+ * @return one of the YES_OPTION, NO_OPTION,.., XXX_OPTION, indicating the
+ * option selected by the user
+ */
+ public abstract int showConfirmPopupDialog(Object message);
+
+ /**
+ * Shows a dialog where the number of choices is determined
+ * by the optionType parameter.
+ *
+ * @param message the Object to display
+ * @param title the title string for the dialog
+ * @param optionType an int designating the options available on the dialog:
+ * YES_NO_OPTION, or
+ * YES_NO_CANCEL_OPTION
+ * @return one of the YES_OPTION, NO_OPTION,.., XXX_OPTION, indicating the
+ * option selected by the user
+ */
+ public abstract int showConfirmPopupDialog(Object message,
+ String title, int optionType);
+
+ /**
+ * Shows a dialog where the number of choices is determined
+ * by the optionType parameter, where the
+ * messageType parameter determines the icon to display.
+ * The messageType parameter is primarily used to supply
+ * a default icon for the dialog.
+ *
+ * @param message the Object to display
+ * @param title the title string for the dialog
+ * @param optionType an integer designating the options available
+ * on the dialog: YES_NO_OPTION,
+ * or YES_NO_CANCEL_OPTION
+ * @param messageType an integer designating the kind of message this is;
+ * ERROR_MESSAGE,
+ * INFORMATION_MESSAGE,
+ * WARNING_MESSAGE,
+ * QUESTION_MESSAGE,
+ * or PLAIN_MESSAGE
+ * @return one of the YES_OPTION, NO_OPTION,.., XXX_OPTION, indicating the
+ * option selected by the user
+ */
+ public abstract int showConfirmPopupDialog(Object message, String title,
+ int optionType, int messageType);
+
+}
+
diff --git a/src/net/java/sip/communicator/service/gui/UIService.java b/src/net/java/sip/communicator/service/gui/UIService.java
index 972fe6a0f..a0888c2ba 100644
--- a/src/net/java/sip/communicator/service/gui/UIService.java
+++ b/src/net/java/sip/communicator/service/gui/UIService.java
@@ -8,14 +8,48 @@
import java.util.Iterator;
+import net.java.sip.communicator.service.protocol.Contact;
/**
- * Plugins using the service in order to add featuress to the user interface
- * may do that using one of the addXxx() methods.
- *
+ * 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 + * ContainerIDs corresponding to different "places", 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 dialogs 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 application dialogs within the GUI, like "Configuration" or
+ * "AddContact" dialogs, could be also shown from outside the ui. To make one of
+ * these dialogs showable, the UIService implementation should attach to
+ * it a DialogID and export it. A dialog then could be shown, by
+ * invoking getApplicationDialog(DialogID) and then
+ * show. The DialogID above should be one of the exported
+ * DialogIDs obtained from getExportedDialogs.
+ *
+ * Each UIService implementation should implement the method
+ * getChatDialog(Contact contact), which is meant to provide an
+ * access to the chat component for the given contact in the form of
+ * ExportedDialog.
+ *
* @author Yana Stamcheva
*/
public interface UIService
{
+ /*
+ * ContainerID-s
+ */
public static final ContainerID CONTAINER_FILE_MENU
= new ContainerID("File");
public static final ContainerID CONTAINER_TOOLS_MENU
@@ -47,6 +81,9 @@ public interface UIService
public static final ContainerID CONTAINER_CHAT_HELP_MENU
= new ContainerID("ChatHelpMenu");
+ /*
+ * Constraints
+ */
public static final String START = "Start";
public static final String END = "End";
public static final String TOP = "Top";
@@ -54,20 +91,144 @@ public interface UIService
public static final String LEFT = "Left";
public static final String RIGHT = "Right";
+ /*
+ * DialogID-s
+ */
+ public static final DialogID DIALOG_MAIN_CONFIGURATION
+ = new DialogID("MainConfigurationDialog");
+
+ public static final DialogID DIALOG_CONFIGURATION1
+ = new DialogID("Configuration1Dialog");
+
+ public static final DialogID DIALOG_CONFIGURATION2
+ = new DialogID("Configuration2Dialog");
+
+ public static final DialogID DIALOG_CONFIGURATION3
+ = new DialogID("Configuration3Dialog");
+
+ public static final DialogID DIALOG_ADD_CONTACT
+ = new DialogID("AddContactDialog");
+
+ /**
+ * 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 true if the application is visible and
+ * false otherwise.
+ *
+ * @see #setVisible(boolean)
+ */
+ public boolean isVisible();
+
+ /**
+ * 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.
+ *
+ * @param visible if true, shows the main application window;
+ * otherwise, hides the main application window.
+ *
+ * @see #isVisible()
+ */
+ public void setVisible(boolean visible);
+
+ /**
+ * Minimizes the main application window.
+ */
+ public void minimize();
+
+ /**
+ * Mawimizes 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);
+
+ /**
+ * Returns a common application dialog given by DialogID. This
+ * could be per example a "Configuration" dialog, "Add contact" dialog
+ * or any other dialog within the application, which could be simply shown
+ * without need of additional arguments. The dialogID SHOULD be
+ * one of the DIALOG_XXX obtained by the getExportedDialogs method.
+ *
+ * @param dialogID One of the DIALOG_XXX DialogID-s.
+ * @return the dialog to be shown
+ * @see #getExportedDialogs()
+ */
+ public ExportedDialog getApplicationDialog(DialogID dialogID);
+
+ /**
+ * 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 PopupDialog.
+ * @see PopupDialog
+ */
+ public PopupDialog getPopupDialog();
+
+ /**
+ * Returns the ExportedDialog corresponding to the component
+ * representing the chat for the given contact. Meant to be used from other
+ * bundles to allow them to check the visibility of a chat, hide it or show
+ * it.
+ * @param contact
+ * @return The ExportedDialog corresponding to the component
+ * representing the chat for the given contact.
+ */
+ public ExportedDialog getChatDialog(Contact contact);
+
+ /**
+ * Returns an iterator over a set of dialogID-s. Each DialogID points to
+ * a common dialog in the current UI implementation that could be shown
+ * using the showApplicationDialog method. Each
+ * DialogID in the set is one of the DIALOG_XXX constants.
+ * The method is meant to be used by bundles that would like to show common
+ * dialogs like "Configuration" or "Add contact" dialog. Before showing any
+ * dialog they should use this method to obtain all possible dialogs, which
+ * could be shown for the current ui implementation.
+ *
+ * @return Iterator An iterator to a set containing containerID-s
+ * representing all containers supported by the current UI implementation.
+ */
+ public Iterator getExportedDialogs();
+
/**
* 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
+ * 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.
@@ -83,26 +244,29 @@ public void addComponent(ContainerID containerID, Object component)
throws ClassCastException, IllegalArgumentException;
/**
- * 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.
+ * 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.
+ * 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
+ * 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 containerID One of the CONTAINER_XXX ContainerID-s.
+ * @param constraint One of the START, END, BOTTOM, etc. String constants.
* @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
@@ -112,40 +276,46 @@ public void addComponent(ContainerID containerID, Object component)
* is not recognized by the implementation (note that implementations
* MUST properly handle all CONTAINER_XXX containerID-s.
*/
- public void addComponent(ContainerID containerID, String constraint, Object component)
+ public void addComponent(ContainerID containerID,
+ String constraint, Object component)
throws ClassCastException, IllegalArgumentException;
/**
- * 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.
+ * 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.
+ * @return Iterator An iterator to a set containing containerID-s
+ * representing all containers supported by the current UI implementation.
*/
public Iterator getSupportedContainers();
/**
- * 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.
+ * Returns an iterator over a set of 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
+ * @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.
+ * Returns an Iterator over a set of 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 containerID One of the containerID-s supported by the current UI implementation.
- * @return An Iterator to a set containing all components added to a given constraint.
+ * @param containerID One of the containerID-s 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;