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}