|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectjava.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
com.bric.swing.DialogFooter
public class DialogFooter
This is a row of buttons, intended to be displayed at the
bottom of a dialog. This class is strongly related to the
com.bric.swing.QDialog
project, although the
DialogFooter
can exist by itself.
On the left of a footer are controls that should apply to the dialog itself,
such as "Help" button, or a "Reset Preferences" button.
On the far right are buttons that should dismiss this dialog. They
may be presented in different orders on different platforms based
on the reverseButtonOrder
boolean.
Buttons are also generally normalized, so the widths of buttons are equal.
This object will "latch onto" the RootPane that contains it. It is assumed two DialogFooters will not be contained in the same RootPane. It is also assumed the same DialogFooter will not be passed around to several different RootPanes.
In each constant the first option is the default button unless you specify otherwise. The Apple Interface Guidelines advises: "The default button should be the button that represents the action that the user is most likely to perform if that action isn?t potentially dangerous."
The YES_NO options should be approached with special reluctance. Microsoft cautions, "Use Yes and No buttons only to respond to yes or no questions." This seems obvious enough, but Apple adds, "Button names should correspond to the action the user performs when pressing the button?for example, Erase, Save, or Delete." So instead of presenting a YES_NO dialog with the question "Do you want to continue?" a better dialog might provide the options "Cancel" and "Continue". In short: we as developers might tend to lazily use this option and phrase dialogs in such a way that yes/no options make sense, but in fact the commit buttons should be more descriptive.
Partly because of the need to avoid yes/no questions, DialogFooter
introduces the
dialog type: SAVE_DONT_SAVE_CANCEL_OPTION. This is mostly straightforward, but
there is one catch: on Mac the buttons
are reordered: "Save", "Cancel" and "Don't Save". This is to conform with standard
Mac behavior. (Or, more specifically: because the Apple guidelines
state that a button that can cause permanent data loss be as physically far
from a "safe" button as possible.) On all other platforms the buttons are
listed in the order "Save", "Don't Save" and "Cancel".
Also note the field reverseButtonOrder
controls the order each option is presented in the dialog from left-to-right.
com.bric.swing.JLink
.
DialogFooter.reverseButtonOrder
field for details.
Nested Class Summary | |
---|---|
static class |
DialogFooter.ClickAction
This action calls button.doClick() . |
Nested classes/interfaces inherited from class javax.swing.JPanel |
---|
JPanel.AccessibleJPanel |
Nested classes/interfaces inherited from class javax.swing.JComponent |
---|
JComponent.AccessibleJComponent |
Nested classes/interfaces inherited from class java.awt.Container |
---|
Container.AccessibleAWTContainer |
Nested classes/interfaces inherited from class java.awt.Component |
---|
Component.AccessibleAWTComponent, Component.BaselineResizeBehavior, Component.BltBufferStrategy, Component.FlipBufferStrategy |
Field Summary | |
---|---|
protected boolean |
autoClose
|
static int |
CANCEL_OPTION
Used to indicate the user selected "Cancel" in a dialog. |
static Action |
closeDialogAndDisposeAction
This action takes the Window associated with the source of this event, hides it, and then calls dispose() on it. |
protected JButton |
defaultButton
|
protected JComponent[] |
dismissControls
|
static int |
DONT_SAVE_OPTION
Used to indicate the user selected "Don't Save" in a dialog. |
static int |
ESCAPE_KEY_DOES_NOTHING
This (the default behavior) does nothing when the escape key is pressed. |
static int |
ESCAPE_KEY_TRIGGERS_CANCEL
This triggers the cancel button when the escape key is pressed. |
static int |
ESCAPE_KEY_TRIGGERS_DEFAULT
This triggers the default button when the escape key is pressed. |
static int |
ESCAPE_KEY_TRIGGERS_NONDEFAULT
This triggers the non-default button when the escape key is pressed. |
static boolean |
isMac
|
static boolean |
isVista
|
protected JComponent |
lastSelectedComponent
|
protected JComponent[] |
leftControls
|
static int |
NO_OPTION
Used to indicate the user selected "No" in a dialog. |
static int |
OK_CANCEL_OPTION
Used to indicate a dialog should present a "OK" and "Cancel" option. |
static int |
OK_OPTION
Used to indicate the user selected "OK" in a dialog. |
static String |
PROPERTY_META_SHORTCUT
This client property is used to impose a meta-shortcut to click a button. |
static String |
PROPERTY_OPTION
This is the client property of buttons created in static methods by this class. |
static String |
PROPERTY_UNSAFE
This client property is used to indicate a button is "unsafe". |
static boolean |
reverseButtonOrder
This indicates whether the dismiss controls should be displayed in reverse order. |
static int |
SAVE_DONT_SAVE_CANCEL_OPTION
Used to indicate a dialog should present a "Save", "Don't Save", and "Cancel" option. |
static int |
SAVE_OPTION
Used to indicate the user selected "Save" in a dialog. |
static ResourceBundle |
strings
The localized strings used in dialogs. |
static int |
YES_NO_CANCEL_OPTION
Used to indicate a dialog should present a "Yes", "No", and "Cancel" option. |
static int |
YES_NO_OPTION
Used to indicate a dialog should present a "Yes" and "No" option. |
static int |
YES_OPTION
Used to indicate the user selected "Yes" in a dialog. |
Fields inherited from class javax.swing.JComponent |
---|
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW |
Fields inherited from class java.awt.Component |
---|
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT |
Fields inherited from interface java.awt.image.ImageObserver |
---|
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH |
Constructor Summary | |
---|---|
DialogFooter(JComponent[] leftControls,
JComponent[] dismissControls,
boolean autoClose,
JButton defaultButton)
Create a new DialogFooter . |
Method Summary | |
---|---|
void |
addActionListener(ActionListener l)
Adds an ActionListener . |
static JButton |
createCancelButton(boolean escapeKeyIsTrigger)
Creates a new "Cancel" button. |
static DialogFooter |
createDialogFooter(JComponent[] leftComponents,
int options,
int escapeKeyBehavior)
Creates a DialogFooter and assigns a default button. |
static DialogFooter |
createDialogFooter(JComponent[] leftComponents,
int options,
int defaultButton,
int escapeKeyBehavior)
Creates a DialogFooter . |
static JButton |
createDontSaveButton()
Creates a new "Don't Save" button that is not triggered by the escape key. |
static JButton |
createDontSaveButton(boolean escapeKeyIsTrigger)
Creates a new "Don't Save" button. |
static JButton |
createNoButton()
Creates a new "No" button that is not triggered by the escape key. |
static JButton |
createNoButton(boolean escapeKeyIsTrigger)
Creates a new "No" button. |
static JButton |
createOKButton()
Creates a new "OK" button that is not triggered by the escape key. |
static JButton |
createOKButton(boolean escapeKeyIsTrigger)
Creates a new "OK" button. |
static JButton |
createSaveButton()
Creates a new "Save" button that is not triggered by the escape key. |
static JButton |
createSaveButton(boolean escapeKeyIsTrigger)
Creates a new "Save" button. |
static JButton |
createYesButton()
Creates a new "Yes" button that is not triggered by the escape key. |
static JButton |
createYesButton(boolean escapeKeyIsTrigger)
Creates a new "Yes" button. |
JButton |
getButton(int buttonType)
Finds a certain type of button, if it is available. |
JComponent[] |
getDismissControls()
Returns a copy of the dismissControls array used to construct this footer. |
JComponent |
getLastSelectedComponent()
Returns the component last used to dismiss the dialog. |
JComponent[] |
getLeftControls()
Returns a copy of the leftControls array used to construct this footer. |
static void |
makeEscapeKeyActivate(AbstractButton button)
This guarantees that when the escape key is pressed (if its parent window has the keyboard focus) this button is clicked. |
static void |
normalizeButtons(JButton[] buttons)
This takes a set of buttons and gives them all the width/height of the largest button among them. |
void |
removeActionListener(ActionListener l)
Removes an ActionListener . |
void |
reset()
This resets the value of lastSelectedComponent to null. |
Methods inherited from class javax.swing.JPanel |
---|
getAccessibleContext, getUI, getUIClassID, paramString, setUI, updateUI |
Methods inherited from class java.lang.Object |
---|
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Field Detail |
---|
public static final int ESCAPE_KEY_DOES_NOTHING
public static final int ESCAPE_KEY_TRIGGERS_CANCEL
This should only be used if the cancel button does not lead to data loss, because users may quickly press the escape key before reading the text in a dialog.
public static final int ESCAPE_KEY_TRIGGERS_DEFAULT
This should only be used if the default button does not lead to data loss, because users may quickly press the escape key before reading the text in a dialog.
public static final int ESCAPE_KEY_TRIGGERS_NONDEFAULT
This should only be used if the non-default button does not lead to data loss, because users may quickly press the escape key before reading the text in a dialog.
public static ResourceBundle strings
public static String PROPERTY_OPTION
public static final int CANCEL_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.CANCEL_OPTION for DialogFooter.CANCEL_OPTION.
public static final int OK_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.OK_OPTION for DialogFooter.OK_OPTION.
public static final int NO_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.NO_OPTION for DialogFooter.NO_OPTION.
public static final int YES_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.YES_OPTION for DialogFooter.YES_OPTION.
public static final int YES_NO_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.YES_NO_OPTION for DialogFooter.YES_NO_OPTION.
public static final int YES_NO_CANCEL_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.YES_NO_CANCEL_OPTION for DialogFooter.YES_NO_CANCEL_OPTION.
public static final int OK_CANCEL_OPTION
Note the usage is similar to JOptionPane's, but the numerical value is different, so you cannot substitute JOptionPane.OK_CANCEL_OPTION for DialogFooter.OK_CANCEL_OPTION.
public static final int SAVE_DONT_SAVE_CANCEL_OPTION
public static final int SAVE_OPTION
public static final int DONT_SAVE_OPTION
public static final boolean isMac
public static final boolean isVista
public static final String PROPERTY_META_SHORTCUT
public static final String PROPERTY_UNSAFE
public static boolean reverseButtonOrder
By default on Mac this is true, because Macs put the default button on the right side of dialogs. On all other platforms this is false by default.
Window's guidelines advise to, "Position the most important button -- typically the default command -- as the first button in the set."
protected JComponent[] leftControls
protected JComponent[] dismissControls
protected JComponent lastSelectedComponent
protected boolean autoClose
protected JButton defaultButton
public static Action closeDialogAndDisposeAction
dispose()
on it.
(This will not throw an exception if there is no parent window, but it does nothing in that case...)
Constructor Detail |
---|
public DialogFooter(JComponent[] leftControls, JComponent[] dismissControls, boolean autoClose, JButton defaultButton)
DialogFooter
.
leftControls
- the controls on the left side of this dialog, such as a help component, or a "Reset" button.dismissControls
- the controls on the right side of this dialog that should dismiss this dialog. Also
called "action" buttons.autoClose
- whether the dismiss buttons should automatically close the containing window.
If this is false
, then it is assumed someone else is taking care of closing/disposing the
containing dialogdefaultButton
- the optional button in dismissControls
to make the default button in this dialog.
(May be null.)Method Detail |
---|
public static JButton createCancelButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static void makeEscapeKeyActivate(AbstractButton button)
It is assumed that no two buttons will try to consume escape keys in the same window.
button
- the button to trigger when the escape key is pressed.public static JButton createOKButton()
public static JButton createOKButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static JButton createYesButton()
public static JButton createYesButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static JButton createNoButton()
public static JButton createNoButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static JButton createSaveButton()
public static JButton createSaveButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static JButton createDontSaveButton()
public static JButton createDontSaveButton(boolean escapeKeyIsTrigger)
escapeKeyIsTrigger
- if true then pressing the escape
key will trigger this button. (Also on Macs command-period will act
like the escape key.) This should be false
if this button
can lead to permanent data loss.public static DialogFooter createDialogFooter(JComponent[] leftComponents, int options, int escapeKeyBehavior)
DialogFooter
and assigns a default button.
The default button is the first button listed in the button type. For example,
a YES_NO_CANCEL_OPTION dialog will make the YES_OPTION the default button.
To use a different default button, use the other createDialogFooter()
method.
leftComponents
- the components to put on the left side of the footer.
The Apple guidelines state that this area is reserved for "button[s] that affect the contents of the dialog itself, such as Reset [or Help]".
options
- one of the OPTIONS fields in this class, such as YES_NO_OPTION or CANCEL_OPTION.escapeKeyBehavior
- one of the ESCAPE_KEY
constants in this class.
DialogFooter
public static DialogFooter createDialogFooter(JComponent[] leftComponents, int options, int defaultButton, int escapeKeyBehavior)
DialogFooter
.
leftComponents
- the components to put on the left side of the footer.
The Apple guidelines state that this area is reserved for "button[s] that affect the contents of the dialog itself, such as Reset [or Help]".
options
- one of the OPTIONS fields in this class, such as YES_NO_OPTION or CANCEL_OPTION.defaultButton
- the OPTION field corresponding to the button that
should be the default button, or -1 if there should be no default button.escapeKeyBehavior
- one of the ESCAPE_KEY
constants in this class.
DialogFooter
public static void normalizeButtons(JButton[] buttons)
(More specifically, this sets the preferredSize
of each button to the largest preferred size in the list of buttons.
buttons
- an array of buttons.public void addActionListener(ActionListener l)
ActionListener
.
l
- this listener will be notified when a dismissControl
is activated.public void removeActionListener(ActionListener l)
ActionListener
.
public JComponent getLastSelectedComponent()
Note the components on the left side of this footer (such as a "Help" button or a "Reset Preferences" button) do NOT dismiss the dialog, and so this method has nothing to do with those components. This only related to the components on the right side of dialog.
public JButton getButton(int buttonType)
buttonType
- of the options in this class (such as YES_OPTION or CANCEL_OPTION)
public void reset()
lastSelectedComponent
to null.
If this footer is recycled in different dialogs, then you may
need to nullify this value for getLastSelectedComponent()
to remain relevant.
public JComponent[] getDismissControls()
dismissControls
array used to construct this footer.
public JComponent[] getLeftControls()
leftControls
array used to construct this footer.
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |