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     * Get the Signal Head Appearance.
070     * Changes in this value can be listened to using the
071     * {@literal Appearance} property.
072     *
073     * @return the appearance, e.g. SignalHead.YELLOW
074     */
075    int getAppearance();
076
077    /**
078     * Set the Signal Head Appearance.
079     *
080     * @param newAppearance integer representing a valid Appearance for this head
081     */
082    void setAppearance(int newAppearance);
083
084    
085    /**
086     * Get the current Signal Head Appearance Key.
087     * @return Key, or empty String if no valid appearance set.
088     */
089    @Nonnull
090    String getAppearanceKey();
091
092    /**
093     * Get the Appearance Key for a particular Appearance.
094     * @param appearance id for the key, e.g. SignalHead.GREEN
095     * @return the Appearance Key, e.g. "Green" or empty String if unknown.
096     * The key can be used as a Bundle String, e.g.
097     * Bundle.getMessage(getAppearanceKey(SignalHead.RED))
098     */
099    @Nonnull
100    String getAppearanceKey(int appearance);
101
102    /**
103     * Get the current appearance name.
104     * @return Name of the Appearance, e.g. "Dark" or "Flashing Red"
105     */
106    @Nonnull
107    String getAppearanceName();
108
109    /**
110     * Get the Appearance Name for a particular Appearance.
111     * @param appearance id for the Name.
112     * @return the Appearance Name, or empty String if unknown.
113     */
114    @Nonnull
115    String getAppearanceName(int appearance);
116
117    /**
118     * {@inheritDoc}
119     */
120    @Override
121    boolean getLit();
122
123    /**
124     * {@inheritDoc}
125     */
126    @Override
127    void setLit(boolean newLit);
128
129    /**
130     * {@inheritDoc}
131     */
132    @Override
133    boolean getHeld();
134
135    /**
136     * {@inheritDoc}
137     */
138    @Override
139    void setHeld(boolean newHeld);
140
141    /**
142     * Get an array of appearance indexes valid for the mast type.
143     *
144     * @return array of appearance state values available on this mast type
145     */
146    int[] getValidStates();
147
148    /**
149     * Get an array of non-localized appearance keys valid for the mast type.
150     * For GUI application consider using (capitalized) {@link #getValidStateNames()}
151     *
152     * @return array of translated appearance names available on this mast type
153     */
154    String[] getValidStateKeys();
155
156    /**
157     * Get an array of localized appearance descriptions valid for the mast type.
158     * For persistance and comparison consider using {@link #getValidStateKeys()}
159     *
160     * @return array of translated appearance names
161     */
162    String[] getValidStateNames();
163
164}