001package jmri.util.swing;
002
003import java.awt.Dimension;
004import java.util.ArrayList;
005import java.util.List;
006
007import javax.annotation.Nonnull;
008import javax.swing.JMenu;
009import javax.swing.JPanel;
010
011/**
012 * JPanel extension to handle automatic creation of window title and help
013 * reference.
014 * <p>
015 * For use with {@link JmriAbstractAction} or preferably
016 * {@link JmriNamedPaneAction}.
017 * <p>
018 * The expected initialization sequence is:
019 * <ol>
020 * <li>The constructor, which can initialize internal variables, but shouldn't
021 * expose the object by installing any listeners, etc.
022 * <li>initComponents() is called, which initializes Swing components and can
023 * make other external references.
024 * <li>initContext(Object context) is called, which can make outside
025 * connections.
026 * <li>Optionally, other usage-specific initialization methods can be called as
027 * needed.
028 * </ol>
029 * <p>
030 * A {@link WindowInterface} property is provided for use when the JmriPanel's
031 * controller logic wants to open a window or dialog in a position relative to
032 * this panel.
033 *
034 * @author Bob Jacobsen Copyright 2010
035 * @since 2.9.4
036 */
037public class JmriPanel extends JPanel {
038
039    /**
040     * Provide a help target string which an enclosing frame can provide as a
041     * help reference.
042     * <p>
043     * This automatically provides a reference to the usual place for JMRI
044     * window-specific help pages that are named for the implementing class, but
045     * note this is a Pane class, not a Frame class.
046     *
047     * @return the target String
048     */
049    public String getHelpTarget() {
050        return "package." + this.getClass().getName();
051    }
052
053    /**
054     * Provide a recommended title for an enclosing frame.
055     *
056     * @return the title; a null value will be treated as "" by the enclosing
057     *         frame
058     */
059    public String getTitle() {
060        return null;
061    }
062
063    /**
064     * Can multiple instances of a specific pane subclass exist?
065     *
066     * @return true if multiple panels of this class can be open at once; false
067     *         if only one instance of this panel can exist.
068     */
069    public boolean isMultipleInstances() {
070        return true;
071    }
072
073    /**
074     * Provide menu items to add to a menu bar.
075     *
076     * @return a list of menu items to add or an empty list
077     */
078    @Nonnull
079    public List<JMenu> getMenus() {
080        return new ArrayList<>();
081    }
082
083    public Dimension getMinimumDimension() {
084        return new Dimension(10, 10);
085    }
086
087    public WindowInterface getWindowInterface() {
088        return wi;
089    }
090    private WindowInterface wi = null;
091
092    public void setWindowInterface(WindowInterface w) {
093        wi = w;
094    }
095
096    /**
097     * 2nd stage of initialization, invoked after the constructor is complete.
098     */
099    public void initComponents() {
100    }
101
102    /**
103     * 3rd stage of initialization, invoked after Swing components exist.
104     *
105     * @param context the context that this panel may be initialized with
106     */
107    public void initContext(Object context) {
108    }
109
110    public void dispose() {
111    }
112}