001package jmri;
002
003import java.util.Vector;
004import javax.annotation.Nonnull;
005
006/**
007 * Represent a signal mast. A signal mast is one or more signal heads that are
008 * treated as a single signal. (Imagine several heads attached to a single mast,
009 * though other implementations are possible)
010 * <p>
011 * A mast presents an Aspect, as that's a composite of the appearance(s) of the
012 * entire signal.
013 * <p>
014 * This class has three bound parameters:
015 * <DL>
016 * <DT>Aspect<DD>The specific aspect being shown.
017 * <p>
018 * Aspects are named by a user defined String name.
019 * <DT>Lit<DD>Whether the mast's lamps are lit or left dark.
020 * This differs from the DARK color defined for the appearance parameter, in
021 * that it's independent of that. Lit is intended to allow you to extinguish a
022 * signal mast for approach lighting, while still allowing its color to be set
023 * to a definite value for e.g. display on a panel or evaluation in higher level
024 * logic.
025 * <DT>Held<DD>Whether the mast's lamps should be forced to a specific aspect,
026 * e.g. Stop, in higher-level logic.
027 * <p>
028 * For use in signaling systems, this is a convenient way of storing whether a
029 * higher-level of control (e.g. non-vital system or dispatcher) has "held" the
030 * signal at stop. It does not effect how this signal mast actually works; any
031 * appearance can be set and will be displayed even when "held" is set.
032 * </dl>
033 * The integer state (getState(), setState()) is the index of the current aspect
034 * in the list of all defined aspects.
035 * <hr>
036 * This file is part of JMRI.
037 * <p>
038 * JMRI is free software; you can redistribute it and/or modify it under the
039 * terms of version 2 of the GNU General Public License as published by the Free
040 * Software Foundation. See the "COPYING" file for a copy of this license.
041 * <p>
042 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
043 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
044 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
045 *
046 * @author Bob Jacobsen Copyright (C) 2002, 2008
047 * @author Pete Cressman Copyright (C) 2009
048 */
049public interface SignalMast extends Signal {
050
051    /**
052     * Set aspect to a valid name in the current signal system definition.
053     *
054     * @param aspect the new aspect shown
055     * @throws IllegalArgumentException if not a valid aspect name
056     */
057    public void setAspect(@Nonnull String aspect);
058
059    /**
060     * Get current aspect name. Changes to this property can be listened to
061     * using the property {@literal Aspect}.
062     *
063     * @return the current aspect or null if not set
064     */
065    public String getAspect();
066
067    /**
068     * Get an alphabetically sorted list of valid aspects that have not been disabled.
069     *
070     * @return sorted list of valid aspects; may be empty
071     */
072    @Nonnull
073    public Vector<String> getValidAspects();
074
075    public SignalSystem getSignalSystem();
076
077    public SignalAppearanceMap getAppearanceMap();
078
079    /**
080     * Set the specific mast type for this mast.
081     * This is the
082     * type that appears in the SystemName and filename, i.e. "SL-3-high"
083     * for the
084     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
085     * definition.
086     * @param type mast type.
087     */
088    public void setMastType(@Nonnull String type);
089
090    /**
091     * Get the specific mast type for this mast.
092     * This is the
093     * type that appears in the SystemName and filename, i.e. "SL-3-high"
094     * for the
095     * <a href="http://jmri.org/xml/signals/AAR-1946/appearance-SL-3-high.xml">AAR-1946/appearance-SL-3-high.xml</a>
096     * definition.
097     * @return mast type.
098     */
099    public String getMastType();
100
101    /**
102     * Get if signal mast is lit or dark. Changes to this property can be
103     * listened to using the property {@literal Lit}.
104     *
105     * @return true if lit; false if dark
106     */
107    public boolean getLit();
108
109    public void setLit(boolean newLit);
110
111    /**
112     * Get the held state of the signal mast. It controls what mechanisms can
113     * control the mast's appearance. The actual semantics are defined by those
114     * external mechanisms. Changes to this property can be listened to using
115     * the property {@literal Held}.
116     *
117     * @return true if held; false otherwise
118     */
119    public boolean getHeld();
120
121    public void setHeld(boolean newHeld);
122
123    /**
124     * Determine if the permissive SML logic should be disabled.  The default will be
125     * false which means that automatic permissive processing is allowed.  Prototypical
126     * CTC designs frequently require an additional action, such as Call-On, to enable permissive aspects.
127     * @return true if permissive SML is disabled.
128     */
129    public boolean isPermissiveSmlDisabled();
130
131    public void setPermissiveSmlDisabled(boolean disabled);
132
133    public boolean isAspectDisabled(String aspect);
134
135    /**
136     * Sets whether the Signal Mast is allowed or configured to show an unlit
137     * aspect, or if it is always lit.
138     *
139     * @param boo Set true to allow the UnLit to be used, set false it is not
140     *            supported or allowed.
141     */
142    public void setAllowUnLit(boolean boo);
143
144    public boolean allowUnLit();
145}