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