1 /*
2 * Copyright 2006-2016 The JGUIraffe Team.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License")
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package net.sf.jguiraffe.gui.builder.utils;
17
18 import net.sf.jguiraffe.gui.builder.window.Window;
19
20 /**
21 * <p>
22 * Definition of an interface for creating message boxes in a platform
23 * independent way.
24 * </p>
25 * <p>
26 * This interface defines a main {@code show()} method to display a message box
27 * of a pre-defined type. The type is specified using one of the the constants
28 * defined by this interface. The method expects a title (as string) and an
29 * object representing the message to be displayed. From this object the
30 * {@code toString()} is called in order to obtain the message text to be
31 * displayed. Concrete implementations have to implement a certain amount of
32 * processing on the message text:
33 * <ul>
34 * <li>The character '\n' should cause a newline in the message. That way
35 * messages with multiple lines can be created.</li>
36 * <li>A reasonable line wrapping should be performed to prevent that the
37 * message window becomes too wide or that parts of the message text are cut
38 * off.</li>
39 * </ul>
40 * In addition, this interface defines some constants for the buttons to be
41 * displayed in the constructed message window. For instance, it is possible to
42 * have just an OK button or specify that buttons for a YES/NO/CANCEL question
43 * are generated. The return value of the {@code show()} method indicates the
44 * pressed button.
45 * </p>
46 * <p>
47 * Note that the {@code show()} method must be called in the UI thread! It lies
48 * in the responsibility of the caller to use the current
49 * {@link GUISynchronizer} to ensure that the invocation happens in the correct
50 * thread.
51 * </p>
52 * <p>
53 * Concrete implementations will map the functionality provided by this
54 * interface to GUI library specific classes. A Swing related implementation for
55 * instance could use Swing's {@code JOptionPane} to provide the required
56 * functionality.
57 * </p>
58 *
59 * @author Oliver Heger
60 * @version $Id: MessageOutput.java 205 2012-01-29 18:29:57Z oheger $
61 */
62 public interface MessageOutput
63 {
64 /** Constant for the message type ERROR. */
65 int MESSAGE_ERROR = 1;
66
67 /** Constant for the message type INFO. */
68 int MESSAGE_INFO = 2;
69
70 /** Constant for the message type WARNING. */
71 int MESSAGE_WARNING = 3;
72
73 /** Constant for the message type QUESTION. */
74 int MESSAGE_QUESTION = 4;
75
76 /** Constant for the message type PLAIN. */
77 int MESSAGE_PLAIN = 5;
78
79 /** Constant for the button type OK. */
80 int BTN_OK = 1;
81
82 /** Constant for the button type OK, CANCEL. */
83 int BTN_OK_CANCEL = 2;
84
85 /** Constant for the button type YES, NO. */
86 int BTN_YES_NO = 3;
87
88 /** Constant for the button type YES, NO, CANCEL. */
89 int BTN_YES_NO_CANCEL = 4;
90
91 /** Constant for the return value OK. */
92 int RET_OK = 1;
93
94 /** Constant for the return value CANCEL. */
95 int RET_CANCEL = 2;
96
97 /**
98 * Constant for the return value YES. Note that this value is identical to
99 * the {@code RET_OK} return value. This is analogous to Swing.
100 */
101 int RET_YES = RET_OK;
102
103 /** Constant for the return value NO. */
104 int RET_NO = 4;
105
106 /**
107 * Displays a message box based on the given options. Please refer to the
108 * class comment for further details about the parameters and how they are
109 * interpreted.
110 *
111 * @param parent the parent window
112 * @param message the message itself; can be an arbitrary object whose
113 * {@code toString()} method will be used to obtain the text to be
114 * displayed
115 * @param title the message box's title
116 * @param messageType the type of the message; this must be one the
117 * {@code MESSAGE_XXXX} constants
118 * @param buttonType defines the buttons to be displayed; this must be one
119 * of the {@code BTN_XXXX} constants
120 * @return a flag for the button pressed by the user; this will be one of
121 * the {@code RET_XXXX} constants
122 */
123 int show(Window parent, Object message, String title, int messageType,
124 int buttonType);
125 }