001package jmri;
002
003import java.util.List;
004
005import javax.annotation.Nonnull;
006
007/**
008 * Interface for a Cab Signal Object, describing the state of the track ahead
009 * relative to a locomotive with a given address.  This is effectively a mobile
010 * signal mast.
011 *
012 * <hr>
013 * This file is part of JMRI.
014 * <p>
015 * JMRI is free software; you can redistribute it and/or modify it under the
016 * terms of version 2 of the GNU General Public License as published by the Free
017 * Software Foundation. See the "COPYING" file for a copy of this license.
018 * <p>
019 * JMRI is distributed in the hope that it will be useful, but WITHOUT ANY
020 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
021 * A PARTICULAR PURPOSE. See the GNU General Public License for more details.
022 *
023 * @author Steve Young Copyright (C) 2018
024 * @author Paul Bender Copyright (C) 2019
025 */
026public interface CabSignal {
027
028    /**
029     * A method for cleaning up the cab signal 
030     */
031    void dispose();
032
033    /**
034     * Get the LocoAddress associated with the consist
035     *
036     * @return the cab signal address
037     */
038    LocoAddress getCabSignalAddress();
039
040    /**
041     * Set the Block of the locomotive by searching the block list.
042     */
043    void setBlock();
044
045    /**
046     * Set the Block of the locomotive
047     *
048     * @param position is a Block the locomotive is in.
049     */
050    void setBlock(Block position);
051
052    /**
053     * Get the Block position of the locomotive associated with the cab signal.
054     *
055     * @return The current Block position
056     */
057    Block getBlock();
058
059    /**
060     * Get the Next Block the locomotive is expected to enter.
061     * This value is calculated from the current block and direction 
062     * of travel.
063     *
064     * @return The next Block position
065     */
066    Block getNextBlock();
067
068    /**
069     * Get Block List for the CabSignal.
070     * List of Blocks up to the end of Path or a Signal Mast displaying
071     * a Stop condition, whichever comes first.
072     * <p>
073     * The first Block in the list ( if any ), is the current Block.
074     * <p>
075     * This list does NOT guarantee that the Blocks will be unoccupied,
076     * a SignalMast may be displaying a call-on aspect.
077     * @return list of Blocks that the loco address is expected to traverse.
078     */
079    @Nonnull
080    List<Block> getBlockList();
081
082    /**
083     * Get the Next Signal Mast the locomotive is expected to pass.
084     * This value may be calculated from the current block and direction 
085     * of travel.
086     *
087     * @return The next SignalMast position
088     */
089    SignalMast getNextMast();
090
091    /**
092     * Forward the current cab signal value to the layout.
093     */
094    void forwardCabSignalToLayout();
095
096    /*
097     * get whether this cab signal is on or off
098     *
099     * @return true if on, false if off
100     */
101    boolean isCabSignalActive();
102
103    /*
104     * set whether this cab signal is on or off
105     *
106     * @param active true if on, false if off
107     */
108    void setCabSignalActive(boolean active);
109
110    /*
111     * set whether a Master Cab signal button is on or off
112     *
113     * @param active true if on, false if off
114     */
115    void setMasterCabSigPauseActive(boolean active);
116
117    /**
118     * Add a listener for consist events
119     *
120     * @param listener is a PropertyChangeListener object
121     */
122    void addPropertyChangeListener(java.beans.PropertyChangeListener listener);
123
124    /**
125     * Remove a listener for cab signal events
126     *
127     * @param listener is a PropertyChangeListener object
128     */
129    void removePropertyChangeListener(java.beans.PropertyChangeListener listener);
130
131}