001package jmri.jmrit.throttle.interfaces;
002
003
004import javax.swing.JLabel;
005
006import jmri.DccLocoAddress;
007import jmri.DccThrottle;
008import jmri.jmrit.roster.RosterEntry;
009import jmri.jmrit.roster.swing.RosterEntrySelectorPanel;
010import jmri.jmrit.throttle.implementation.SimpleThrottlePanel;
011
012/**
013 * 
014 * An interface to abstract UI controllers of throttle
015 *  (ThrottleFrame for Swing throttles for instance)
016 * 
017 * @author Lionel Jeanson 2026
018 */
019public interface ThrottleControllerUI {
020    
021    /**
022     * Return that throttle control container
023     *
024     * @return the throttle control container
025     */
026    ThrottleControllersUIContainer getThrottleControllersContainer();
027    
028    /**
029     * Set that throttle control container
030     *
031     * @param tw the throttle control container to set
032     */
033    void setThrottleControllersContainer(ThrottleControllersUIContainer tw);
034    
035    /**
036     * Set that throttle control roster entry
037     *
038     * @param re the roster entry
039     */
040    void setRosterEntry(RosterEntry re);
041
042    /**
043     * Get that throttle control roster entry  
044     * 
045     * @return the roster entry or null
046     */
047    RosterEntry getRosterEntry();
048
049    /**
050     * Set that throttle control address
051     *
052     * @param la locomotive DccLocoAddress
053     */     
054    void setAddress(DccLocoAddress la);
055
056    /**
057     * Get that throttle control address
058     *
059     * @return the throttle control address or null
060     */
061    DccLocoAddress getAddress();
062
063    /**
064     * Set that throttle consist control address
065     * 
066     * @param la consist DccLocoAddress
067     */
068    void setConsistAddress(DccLocoAddress la);
069
070    /**
071     * Check if that throttle control is using that address
072     * 
073     * @param la the DccLocoAddress to check
074     * @return  true if that throttle control is using that address, false otherwise
075     */
076    boolean isUsingAddress(DccLocoAddress la);
077
078    /**
079     * Dispatch that throttle UI, will dispatch for that throttle control UI only.
080     * Throttle will actully be released only if that throttle control UI is the only one using that address.
081     * 
082     */
083    void dispatchAddress();
084
085    /**
086     * Get that throttle control UI throttle object
087     * 
088     * @return the throttle or null
089     */
090    DccThrottle getThrottle();
091
092    /**
093     * Get that throttle control function throttle object (for consists)
094     * 
095     * @return the function throttle or null
096     */
097    DccThrottle getFunctionThrottle();
098
099    /**
100     * Get that throttle control roster entry for the function locomotive
101     * 
102     * @return the roster entry or null
103     */
104    RosterEntry getFunctionRosterEntry();
105    
106    /**
107     * Emergency stop that throttle
108     *
109     */        
110    void eStop();
111
112    /**
113     * Check if that throttle control is running (non null speed)
114     * 
115     * @return true if that throttle control is running, false otherwise
116     */
117    boolean isRunning();
118
119    /**
120     * Check if that throttle control is active (non null speed and at least one active function)
121      *
122     * @return true if that throttle control is active, false otherwise
123     */
124    boolean isActive();
125
126    /**
127     * Bring that throttle UI control to front (window will be activated and raised if it is not already the case).
128     *
129     */        
130    void toFront();
131
132    /**
133     * Check if that throttle control UI is selected (active and visible)
134     *
135     * @return true if that throttle control UI is visible, false otherwise
136     */    
137    boolean isVisible();
138
139    /**
140     * 
141     * Update that throttle control UI containing frame title (if any) with the current address and roster entry.
142     * Called by the throttle core UI when the controlled throttle address or roster entry is updated to update the frame title with the new information.
143     *
144     */
145    void updateFrameTitle();
146
147    /**
148     * 
149     * Update that throttle control UI.
150     * Called by the throttle core UI when the controlled throttle address or roster entry is updated
151     *
152     */
153    void updateGUI();
154
155    /**
156     * Load that throttle control UI from a throttle file.
157      *
158     * @param sfile the throttle file to load, if null a file chooser will be prompted to select the throttle file to load
159     */
160    void loadThrottleFile(String sfile);
161
162    /**
163     * Get a copy of that throttle control UI label (a text or the roster entry icon, for consits a consist icon will be built from the locomotives in the consist).     
164     * See {@link SimpleThrottlePanel} for an example implementation
165     * 
166     * @return  the label or null
167     */
168    JLabel getLabel();
169
170    /**
171     * Check if that throttle control UI is using continuous speed display (a speed slider from -100 to 100)
172     * (Used by external controls like USB game controllers)
173     * See {@link SimpleThrottlePanel} for an example implementation
174     * 
175     * @return true if that throttle control UI is using continuous speed display, false otherwise
176     */
177    boolean isSpeedDisplayContinuous();
178
179    /**
180     * 
181     * Get that throttle control UI roster entry selector panel, or null if that throttle control UI does not have one.
182     * (Used by external controls like USB game controllers)
183     * See {@link SimpleThrottlePanel} for an example implementation
184     * 
185     * @return the roster entry selector panel or null
186     */
187    public RosterEntrySelectorPanel getRosterEntrySelector();
188    
189    /**
190     * Add an address listener to that throttle control UI.
191     * See {@link SimpleThrottlePanel} for an example implementation
192     *
193     * @param l the address listener to add
194     */
195    public void addAddressListener(AddressListener l);
196
197    /**
198     * Remove an address listener from that throttle control UI.
199     * See {@link SimpleThrottlePanel} for an example implementation 
200     *
201     * @param l the address listener to remove
202     */
203    public void removeAddressListener(AddressListener l);
204
205}