/*
* 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;
/**
* 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 ExportedWindow
{
public static final WindowID WINDOW_GENERAL_POPUP
= new WindowID("GeneralPopupWindow");
//
// Option types
//
/** Type used for <code>showConfirmDialog</code>. */
public static final int YES_NO_OPTION = 0;
/** Type used for <code>showConfirmDialog</code>. */
public static final int YES_NO_CANCEL_OPTION = 1;
/** Type used for <code>showConfirmDialog</code>. */
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 <code>Object</code> to display.
* @return user's input, or <code>null</code> 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 <code>initialSelectionValue</code>.
*
* @param message the <code>Object</code> to display
* @param initialSelectionValue the value used to initialize the input
* field
* @return user's input, or <code>null</code> meaning the user
* canceled the input
*/
public abstract String showInputPopupDialog(Object message,
String initialSelectionValue);
/**
* Shows a dialog with title <code>title</code> and message type
* <code>messageType</code>, 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 <code>Object</code> to display
* @param title the <code>String</code> to display in the dialog
* title bar
* @param messageType the type of message that is to be displayed:
* <code>ERROR_MESSAGE</code>,
* <code>INFORMATION_MESSAGE</code>,
* <code>WARNING_MESSAGE</code>,
* <code>QUESTION_MESSAGE</code>,
* or <code>PLAIN_MESSAGE</code>
* @return user's input, or <code>null</code> 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
* <code>selectionValues</code>, where <code>null</code> implies the
* users can input whatever they wish.
* <code>initialSelectionValue</code> is the initial value to prompt
* the user with.
* It is up to the UI implementation to decide how best to represent the
* <code>selectionValues</code>. In the case of swing per example it could
* be a <code>JComboBox</code>, <code>JList</code> or
* <code>JTextField</code>. The message type is meant to be used by the ui
* implementation to determine the icon of the dialog.
*
* @param message the <code>Object</code> to display
* @param title the <code>String</code> to display in the
* dialog title bar
* @param messageType the type of message to be displayed:
* <code>ERROR_MESSAGE</code>,
* <code>INFORMATION_MESSAGE</code>,
* <code>WARNING_MESSAGE</code>,
* <code>QUESTION_MESSAGE</code>,
* or <code>PLAIN_MESSAGE</code>
*
* @param selectionValues an array of <code>Object</code>s that
* gives the possible selections
* @param initialSelectionValue the value used to initialize the input
* field
* @return user's input, or <code>null</code> 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 <code>Object</code> to display
*/
public abstract void showMessagePopupDialog(Object message);
/**
* Shows a dialog that displays a message using a default
* icon determined by the <code>messageType</code> parameter.
*
* @param message the <code>Object</code> to display
* @param title the title string for the dialog
* @param messageType the type of message to be displayed:
* <code>ERROR_MESSAGE</code>,
* <code>INFORMATION_MESSAGE</code>,
* <code>WARNING_MESSAGE</code>,
* <code>QUESTION_MESSAGE</code>,
* or <code>PLAIN_MESSAGE</code>
*/
public abstract void showMessagePopupDialog(Object message,
String title, int messageType);
/**
* Shows a dialog that prompts the user for confirmation.
*
* @param message the <code>Object</code> 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 <code>optionType</code> parameter.
*
* @param message the <code>Object</code> to display
* @param title the title string for the dialog
* @param optionType an int designating the options available on the dialog:
* <code>YES_NO_OPTION</code>, or
* <code>YES_NO_CANCEL_OPTION</code>
* @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 <code>optionType</code> parameter, where the
* <code>messageType</code> parameter determines the icon to display.
* The <code>messageType</code> parameter is primarily used to supply
* a default icon for the dialog.
*
* @param message the <code>Object</code> to display
* @param title the title string for the dialog
* @param optionType an integer designating the options available
* on the dialog: <code>YES_NO_OPTION</code>,
* or <code>YES_NO_CANCEL_OPTION</code>
* @param messageType an integer designating the kind of message this is;
* <code>ERROR_MESSAGE</code>,
* <code>INFORMATION_MESSAGE</code>,
* <code>WARNING_MESSAGE</code>,
* <code>QUESTION_MESSAGE</code>,
* or <code>PLAIN_MESSAGE</code>
* @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);
/**
* Implements the
* <tt>PopupDialog.showInputPopupDialog(Object, String, int, Object[],
* Object)</tt> method. Invokes the corresponding
* <tt>JOptionPane.showInputDialog</tt> method.
*
* @param message the message to display
* @param messageType the type of message to be displayed: ERROR_MESSAGE,
* INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE
* @param title the String to display in the dialog title bar
* @param selectionValues an array of Objects that gives the possible
* selections
* @param initialSelectionValue the value used to initialize the input field
* @param icon the icon to show in the input window.
*/
public Object showInputPopupDialog(Object message, String title,
int messageType, Object[] selectionValues,
Object initialSelectionValue, byte[] icon);
/**
* Implements the <tt>PopupDialog.showMessagePopupDialog(Object, String,
* int)</tt> method. Invokes the corresponding
* <tt>JOptionPane.showMessageDialog</tt> method.
*
* @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
* @param icon the image to display in the message dialog.
*/
public void showMessagePopupDialog(Object message, String title,
int messageType, byte[] icon);
/**
* Implements the <tt>PopupDialog.showConfirmPopupDialog(Object, String,
* int, int)</tt> method. Invokes the corresponding
* <tt>JOptionPane.showConfirmDialog</tt> method.
*
* @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;
* primarily used to determine the icon from the pluggable Look and Feel:
* ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE,
* or PLAIN_MESSAGE
* @param icon the icon to display in the dialog
*/
public int showConfirmPopupDialog(Object message, String title,
int optionType, int messageType, byte[] icon);
}