Package com.bric.swing

Class DialogFooter

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
javax.swing.JPanel
com.bric.swing.DialogFooter
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable, Accessible
public class DialogFooter extends JPanel
This is a row of buttons, intended to be displayed at the bottom of a dialog. This class is strongly related to the
invalid reference 
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.

Preset Options

This class has several OPTION constants to create specific buttons.

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.

Platform Differences

These are based mostly on studying Apple and Vista interface guidelines.
  • On Mac, command-period acts like the escape key in dialogs.
  • On Mac the Help component is the standard Mac help icon. On other platforms the help component is a
    invalid reference 
    com.bric.swing.JLink
    .
  • By default button order is reversed on Macs compared to other platforms. See the DialogFooter.reverseButtonOrder field for details.
  • There is a static boolean to control whether button mnemonics should be universally activated. This was added because when studying Windows XP there seemed to be no fixed rules for whether to use mnemonics or not. (Some dialogs show them, some dialogs don't.) So I leave it to your discretion to activate them. I think this boolean should never be activated on Vista or Mac, but on XP and Linux flavors: that's up to you. (Remember using the alt key usually activates the mnemonics in most Java look-and-feels, so just because they aren't universally active doesn't mean you're hurting accessibility needs.)
    • See Also:

    • Field Details

      • ESCAPE_KEY_DOES_NOTHING

        public static final int ESCAPE_KEY_DOES_NOTHING
        This (the default behavior) does nothing when the escape key is pressed.
        See Also:

      • ESCAPE_KEY_TRIGGERS_CANCEL

        public static final int ESCAPE_KEY_TRIGGERS_CANCEL
        This triggers the cancel button when the escape key is pressed. If no cancel button is present: this does nothing. (Also on Macs command+period acts the same as the escape key.)

        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.

        See Also:

      • ESCAPE_KEY_TRIGGERS_DEFAULT

        public static final int ESCAPE_KEY_TRIGGERS_DEFAULT
        This triggers the default button when the escape key is pressed. If no default button is defined: this does nothing. (Also on Macs command+period acts the same as the escape key.)

        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.

        See Also:

      • ESCAPE_KEY_TRIGGERS_NONDEFAULT

        public static final int ESCAPE_KEY_TRIGGERS_NONDEFAULT
        This triggers the non-default button when the escape key is pressed. If no non-default button is defined: this does nothing. (Also on Macs command+period acts the same as the escape key.)

        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.

        See Also:

      • strings

        public static ResourceBundle strings
        The localized strings used in dialogs.

      • PROPERTY_OPTION

        public static String PROPERTY_OPTION
        This is the client property of buttons created in static methods by this class.

      • CANCEL_OPTION

        public static final int CANCEL_OPTION
        Used to indicate the user selected "Cancel" in a dialog.
        Also this can be used as a dialog type, to indicate that "Cancel" should be the only option presented to the user.

        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.

      • OK_OPTION

        public static final int OK_OPTION
        Used to indicate the user selected "OK" in a dialog.
        Also this can be used as a dialog type, to indicate that "OK" should be the only option presented to the user.

        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.

      • NO_OPTION

        public static final int NO_OPTION
        Used to indicate the user selected "No" in a dialog.
        Also this can be used as a dialog type, to indicate that "No" should be the only option presented to the user.

        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.

      • YES_OPTION

        public static final int YES_OPTION
        Used to indicate the user selected "Yes" in a dialog.
        Also this can be used as a dialog type, to indicate that "Yes" should be the only option presented to the user.

        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.

      • YES_NO_OPTION

        public static final int YES_NO_OPTION
        Used to indicate a dialog should present a "Yes" and "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.

      • YES_NO_CANCEL_OPTION

        public static final int YES_NO_CANCEL_OPTION
        Used to indicate a dialog should present a "Yes", "No", and "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.

      • OK_CANCEL_OPTION

        public static final int OK_CANCEL_OPTION
        Used to indicate a dialog should present a "OK" and "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.

      • SAVE_DONT_SAVE_CANCEL_OPTION

        public static final int SAVE_DONT_SAVE_CANCEL_OPTION
        Used to indicate a dialog should present a "Save", "Don't Save", and "Cancel" option.

      • SAVE_OPTION

        public static final int SAVE_OPTION
        Used to indicate the user selected "Save" in a dialog.
        Also this can be used as a dialog type, to indicate that "Save" should be the only option presented to the user.

      • DONT_SAVE_OPTION

        public static final int DONT_SAVE_OPTION
        Used to indicate the user selected "Don't Save" in a dialog.
        Also this can be used as a dialog type, to indicate that "Don't Save" should be the only option presented to the user.

      • isMac

        public static final boolean isMac

      • isVista

        public static final boolean isVista

      • PROPERTY_META_SHORTCUT

        public static final String PROPERTY_META_SHORTCUT
        This client property is used to impose a meta-shortcut to click a button. This should map to a Character.
        See Also:

      • PROPERTY_UNSAFE

        public static final String PROPERTY_UNSAFE
        This client property is used to indicate a button is "unsafe". Apple guidelines state that "unsafe" buttons (such as "discard changes") should be several pixels away from "safe" buttons.
        See Also:

      • reverseButtonOrder

        public static boolean reverseButtonOrder
        This indicates whether the dismiss controls should be displayed in reverse order. When you construct a DialogFooter, the dismiss controls should be listed in order of priority (with the most preferred listed first, the least preferred last). If this boolean is false, then those components will be listed in that order. If this is true, then those components will be listed in the reverse order.

        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."

      • leftControls

        protected JComponent[] leftControls

      • dismissControls

        protected JComponent[] dismissControls

      • lastSelectedComponent

        protected JComponent lastSelectedComponent

      • autoClose

        protected boolean autoClose

      • defaultButton

        protected JButton defaultButton

      • closeDialogAndDisposeAction

        public static Action closeDialogAndDisposeAction
        This action takes the Window associated with the source of this event, hides it, and then calls dispose() on it.

        (This will not throw an exception if there is no parent window, but it does nothing in that case...)

    • Constructor Details

      • DialogFooter

        public DialogFooter(JComponent[] leftControls, JComponent[] dismissControls, boolean autoClose, JButton defaultButton)
        Create a new DialogFooter.
        Parameters:
        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 dialog
        defaultButton - the optional button in dismissControls to make the default button in this dialog. (May be null.)

    • Method Details

      • createCancelButton

        public static JButton createCancelButton(boolean escapeKeyIsTrigger)
        Creates a new "Cancel" button.
        Parameters:
        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.

      • makeEscapeKeyActivate

        public 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.

        It is assumed that no two buttons will try to consume escape keys in the same window.

        Parameters:
        button - the button to trigger when the escape key is pressed.

      • createOKButton

        public static JButton createOKButton()
        Creates a new "OK" button that is not triggered by the escape key.

      • createOKButton

        public static JButton createOKButton(boolean escapeKeyIsTrigger)
        Creates a new "OK" button.
        Parameters:
        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.

      • createYesButton

        public static JButton createYesButton()
        Creates a new "Yes" button that is not triggered by the escape key.

      • createYesButton

        public static JButton createYesButton(boolean escapeKeyIsTrigger)
        Creates a new "Yes" button.
        Parameters:
        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.

      • createNoButton

        public static JButton createNoButton()
        Creates a new "No" button that is not triggered by the escape key.

      • createNoButton

        public static JButton createNoButton(boolean escapeKeyIsTrigger)
        Creates a new "No" button.
        Parameters:
        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.

      • createSaveButton

        public static JButton createSaveButton()
        Creates a new "Save" button that is not triggered by the escape key.

      • createSaveButton

        public static JButton createSaveButton(boolean escapeKeyIsTrigger)
        Creates a new "Save" button.
        Parameters:
        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.

      • createDontSaveButton

        public static JButton createDontSaveButton()
        Creates a new "Don't Save" button that is not triggered by the escape key.

      • createDontSaveButton

        public static JButton createDontSaveButton(boolean escapeKeyIsTrigger)
        Creates a new "Don't Save" button.
        Parameters:
        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.

      • createDialogFooter

        public static DialogFooter createDialogFooter(JComponent[] leftComponents, int options, int escapeKeyBehavior)
        Creates a 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.

        Parameters:
        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.
        Returns:
        a DialogFooter

      • createDialogFooter

        public static DialogFooter createDialogFooter(JComponent[] leftComponents, int options, int defaultButton, int escapeKeyBehavior)
        Creates a DialogFooter.
        Parameters:
        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.
        Returns:
        a DialogFooter

      • normalizeButtons

        public static void normalizeButtons(JButton[] buttons)
        This takes a set of buttons and gives them all the width/height of the largest button among them.

        (More specifically, this sets the preferredSize of each button to the largest preferred size in the list of buttons.

        Parameters:
        buttons - an array of buttons.

      • addActionListener

        public void addActionListener(ActionListener l)
        Adds an ActionListener.
        Parameters:
        l - this listener will be notified when a dismissControl is activated.

      • removeActionListener

        public void removeActionListener(ActionListener l)
        Removes an ActionListener.

      • getLastSelectedComponent

        public JComponent getLastSelectedComponent()
        Returns the component last used to dismiss the dialog.

        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.

        Returns:
        the component last used to dismiss the dialog.

      • getButton

        public JButton getButton(int buttonType)
        Finds a certain type of button, if it is available.
        Parameters:
        buttonType - of the options in this class (such as YES_OPTION or CANCEL_OPTION)
        Returns:
        the button that maps to that option, or null if no such button was found.

      • reset

        public void reset()
        This resets the value of lastSelectedComponent to null.

        If this footer is recycled in different dialogs, then you may need to nullify this value for getLastSelectedComponent() to remain relevant.

      • getDismissControls

        public JComponent[] getDismissControls()
        Returns a copy of the dismissControls array used to construct this footer.

      • getLeftControls

        public JComponent[] getLeftControls()
        Returns a copy of the leftControls array used to construct this footer.