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