001package jmri.jmrit.logixng;
002
003import java.util.List;
004
005/**
006 * The clipboard with actions and expressions
007 * 
008 * @author Daniel Bergqvist (C) 2020
009 */
010public interface Clipboard {
011    
012    /**
013     * Is the clipboard empty?
014     * 
015     * @return true if empty, false otherwise
016     */
017    boolean isEmpty();
018    
019    /**
020     * Add an item to the clipboard.
021     * <P>
022     * The last added item is on the top of the clipboard.
023     * 
024     * @param maleSocket the item to add on the clipboard
025     * @param errors a list of potential errors
026     * @return true if success, false otherwise
027     */
028    boolean add(MaleSocket maleSocket, List<String> errors);
029    
030    /**
031     * Get the top item on the clipboard and remove it from the clipboard.
032     * <P>
033     * The top item is the last item put on the clipboard
034     * 
035     * @return the top item
036     */
037    MaleSocket fetchTopItem();
038    
039    /**
040     * Get the top item on the clipboard without removing it from the clipboard.
041     * <P>
042     * The top item is the last item put on the clipboard
043     * 
044     * @return the top item
045     */
046    MaleSocket getTopItem();
047    
048    /**
049     * Get the female socket root of the clipboard tree.
050     * 
051     * @return the root female socket
052     */
053    FemaleSocket getFemaleSocket();
054    
055    /**
056     * Moves an item on the clipboard to the top of the clipboard.
057     * <P>
058     * If an item on the clipboard that is not the top item is cut, it's
059     * placed as the top item on the clipboard until it's pasted elsewhere.
060     * 
061     * @param maleSocket the male socket to put on the top
062     */
063    void moveItemToTop(MaleSocket maleSocket);
064    
065    /**
066     * Setup this object and its children.
067     * This method is used to lookup system names for child sockets.
068     */
069    void setup();
070    
071}