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}