001package jmri;
002
003import javax.annotation.Nonnull;
004
005/**
006 * Represent a single signal head. (Try saying that ten times fast!) A signal
007 * may have more than one of these (e.g. a signal mast consisting of several
008 * heads) when needed to represent more complex aspects, e.g. Diverging Approach
009 * etc.
010 * <p>
011 * This allows access to explicit appearance information. We don't call this an
012 * Aspect, as that's a composite of the appearance of several heads.
013 * <p>
014 * This class has three bound parameters:
015 * <DL>
016 * <DT>Appearance<DD>The specific color being shown. Values are the various
017 * color constants defined in the class.
018 * <p>
019 * The appearance constants form a bit mask, so they can be used with hardware
020 * that can display e.g. more than one lit color at a time. Individual
021 * implementations may not be able to handle that, however; most of the early
022 * ones probably won't. If a particular implementation can't display a commanded
023 * color, it doesn't try to replace it, but rather just leaves that color off
024 * the resulting display.
025 * <DT>Lit<DD>Whether the head's lamps are lit or left dark.
026 * <p>
027 * This differs from the DARK color defined for the appearance parameter, in
028 * that it's independent of that. Lit is intended to allow you to extinguish a
029 * signal head for approach lighting, while still allowing it's color to be set
030 * to a definite value for e.g. display on a panel or evaluation in higher level
031 * logic.
032 *
033 * <DT>Held<DD>Whether the head's lamps should be forced to a specific
034 * appearance, e.g. RED in higher-level logic.
035 * <p>
036 * For use in signaling systems, this is a convenient way of storing whether a
037 * higher-level of control (e.g. non-vital system or dispatcher) has "held" the
038 * signal at stop. It does not effect how this signal head actually works; any
039 * appearance can be set and will be displayed even when "held" is set.
040 * </dl>
041 *
042 * <hr>
043 * This file is part of JMRI.
044 * <p>
045 * JMRI is free software; you can redistribute it and/or modify it under the
046 * terms of version 2 of the GNU General Public License as published by the Free
047 * Software Foundation. See the "COPYING" file for a copy of this license.
048 * <p>
049 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
050 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
051 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
052 *
053 * @author Bob Jacobsen Copyright (C) 2002, 2008
054 */
055public interface SignalHead extends Signal {
056
057    int DARK = 0x00;
058    int RED = 0x01;
059    int FLASHRED = 0x02;
060    int YELLOW = 0x04;
061    int FLASHYELLOW = 0x08;
062    int GREEN = 0x10;
063    int FLASHGREEN = 0x20;
064    int LUNAR = 0x40;
065    int FLASHLUNAR = 0x80;
066    int HELD = 0x100;
067
068    /**
069     * String constant for the appearance property.
070     */
071    String PROPERTY_APPEARANCE = "Appearance";
072
073    /**
074     * Get the Signal Head Appearance.
075     * Changes in this value can be listened to using the
076     * {@literal Appearance} property.
077     *
078     * @return the appearance, e.g. SignalHead.YELLOW
079     */
080    int getAppearance();
081
082    /**
083     * Set the Signal Head Appearance.
084     *
085     * @param newAppearance integer representing a valid Appearance for this head
086     */
087    void setAppearance(int newAppearance);
088
089    
090    /**
091     * Get the current Signal Head Appearance Key.
092     * @return Key, or empty String if no valid appearance set.
093     */
094    @Nonnull
095    String getAppearanceKey();
096
097    /**
098     * Get the Appearance Key for a particular Appearance.
099     * @param appearance id for the key, e.g. SignalHead.GREEN
100     * @return the Appearance Key, e.g. "Green" or empty String if unknown.
101     * The key can be used as a Bundle String, e.g.
102     * Bundle.getMessage(getAppearanceKey(SignalHead.RED))
103     */
104    @Nonnull
105    String getAppearanceKey(int appearance);
106
107    /**
108     * Get the current appearance name.
109     * @return Name of the Appearance, e.g. "Dark" or "Flashing Red"
110     */
111    @Nonnull
112    String getAppearanceName();
113
114    /**
115     * Get the Appearance Name for a particular Appearance.
116     * @param appearance id for the Name.
117     * @return the Appearance Name, or empty String if unknown.
118     */
119    @Nonnull
120    String getAppearanceName(int appearance);
121
122    /**
123     * {@inheritDoc}
124     */
125    @Override
126    boolean getLit();
127
128    /**
129     * {@inheritDoc}
130     */
131    @Override
132    void setLit(boolean newLit);
133
134    /**
135     * {@inheritDoc}
136     */
137    @Override
138    boolean getHeld();
139
140    /**
141     * {@inheritDoc}
142     */
143    @Override
144    void setHeld(boolean newHeld);
145
146    /**
147     * Get an array of appearance indexes valid for the mast type.
148     *
149     * @return array of appearance state values available on this mast type
150     */
151    int[] getValidStates();
152
153    /**
154     * Get an array of non-localized appearance keys valid for the mast type.
155     * For GUI application consider using (capitalized) {@link #getValidStateNames()}
156     *
157     * @return array of translated appearance names available on this mast type
158     */
159    String[] getValidStateKeys();
160
161    /**
162     * Get an array of localized appearance descriptions valid for the mast type.
163     * For persistance and comparison consider using {@link #getValidStateKeys()}
164     *
165     * @return array of translated appearance names
166     */
167    String[] getValidStateNames();
168
169}