Module com.slinky.hackmaster
Package com.slinky.hackmaster.model.cell

Class LetterCell

java.lang.Object
com.slinky.hackmaster.model.cell.LetterCell
All Implemented Interfaces:
Cell
public class LetterCell extends Object
Represents a cell that contains a single alphabetic character within a grid or similar structure.

A LetterCell is designed to hold only alphabetic characters (A-Z, either upper or lower case) and a special valid symbol represented by a dot ('.'). Any attempt to set its content to a non-alphabetic character other than the VALID_SYMBOL will result in an IllegalCharAddition exception.

Each LetterCell is associated with a single LetterCluster instance. This cluster defines the grouping of cells within a larger structure, such as a word or a segment of text within a puzzle. A LetterCell can only belong to one LetterCluster at any given time, ensuring that its association is unambiguous and easy to manage. The class provides mechanisms to add and remove the cell from a LetterCluster, as well as to query its cluster association.

The primary functionalities of the LetterCell include:

  • Validation of Content: The LetterCell only allows alphabetic characters or the special VALID_SYMBOL. Any invalid character will trigger an exception.
  • Cluster Management: The class allows adding the cell to a LetterCluster and removing it when necessary. It ensures that a cell is only part of one cluster at a time and provides methods to check the cell's current cluster status.
  • Uppercase Conversion: When setting content, the character is automatically converted to uppercase to maintain consistency in the cell's content.

This class extends the AbstractCell class, inheriting core functionality related to cell management, while adding specific behaviours and constraints pertinent to alphabetic characters.

Design Considerations:

  • Consistency: The class ensures that all characters within a LetterCell are uppercase, providing a uniform representation of data.
  • Exception Handling: The class handles invalid operations gracefully by throwing meaningful exceptions, such as IllegalCharAddition when an invalid character is attempted to be set.
Author:
Kheagen Haskins

  • Nested Class Summary

    Nested classes/interfaces inherited from interface com.slinky.hackmaster.model.cell.Cell

    Cell.IllegalCharAddition

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final char
    VALID_SYMBOL
    The valid non-alphabetic symbol that can be added to a LetterCell.

  • Constructor Summary

    Constructors
    Constructor
    Description
    LetterCell(char content)
    Constructs a new LetterCell with the specified content.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addClickListener(javafx.beans.value.ChangeListener<? super Boolean> cl)
    Adds a listener that will be notified whenever the value of the `clickCount` property changes.
    void
    addContentListener(javafx.beans.value.ChangeListener<? super Character> listener)
    Registers a listener that will be notified when the content of the cell changes, such as when it is filled or modified.
    void
    addStateListener(javafx.beans.value.ChangeListener<? super Boolean> listener)
    Adds a listener to the `isActiveProperty` to monitor changes in its value.
    boolean
    addToCluster(CellCluster cluster)
    Adds this LetterCell to the specified LetterCluster.
    void
    click()
    Toggles the value of the `clickProperty`, thereby triggering any event listeners that are bound to this property.
    char
    getContent()
    Retrieves the character content of this cell.
    CellCluster
    getMainCluster()
    Returns the CellCluster instance that this LetterCell currently belongs to.
    boolean
    inActiveCluster()
    Checks whether the cluster this LetterCell belongs to is currently active.
    boolean
    inCluster()
    Indicates whether this LetterCell is part of a LetterCluster.
    boolean
    isActive()
    Checks if the cell is currently active.
    boolean
    matches(Cell cell)
    Compares this Cell with the specified Cell to determine if their content is identical.
    boolean
    removeCluster(CellCluster cluster)
    Removes this LetterCell from the specified CellCluster.
    void
    setActive(boolean newState)
    Sets the active state of this cell.
    final void
    setContent(char content)
    Sets the content of this LetterCell to the specified character.
    boolean
    sharesClusterWith(Cell cell)
    Determines whether this LetterCell shares the same cluster with the specified Cell.
    String
    toString()
    Returns a string representation of the LetterCell object.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Field Details

    • VALID_SYMBOL

      public static final char VALID_SYMBOL
      The valid non-alphabetic symbol that can be added to a LetterCell.

      The VALID_SYMBOL is a dot ('.') and is the only non-letter character that a LetterCell can contain without throwing an exception.

      See Also:

  • Constructor Details

    • LetterCell

      public LetterCell(char content)
      Constructs a new LetterCell with the specified content.

      The content must be an alphabetic character; otherwise, an IllegalCharAddition exception is thrown. If the provided content is valid, it is passed to the superclass constructor, which sets the initial value of the cell's content.

      Parameters:
      content - The character to set as the content of this LetterCell.
      Throws:
      Cell.IllegalCharAddition - If the provided character is not an alphabetic character.

  • Method Details

    • setContent

      public final void setContent(char content)
      Sets the content of this LetterCell to the specified character.

      This method ensures that only alphabetic characters or the VALID_SYMBOL (a dot, '.') can be added to a LetterCell. If an invalid character is provided, an IllegalCharAddition exception is thrown.

      The content is automatically converted to uppercase before being set, ensuring uniformity within the cell.

      Specified by:
      setContent in interface Cell
      Parameters:
      content - The character to set as the content of this LetterCell.
      Throws:
      Cell.IllegalCharAddition - If the provided character is neither an alphabetic character nor the VALID_SYMBOL.

    • addToCluster

      public boolean addToCluster(CellCluster cluster)
      Adds this LetterCell to the specified LetterCluster.

      This method makes sure that a LetterCell can only be part of one LetterCluster at a time. If you try to add this cell to a cluster that isn't a LetterCluster, the method will throw an IllegalArgumentException.

      Inside the method, the provided CellCluster is cast to a LetterCluster before adding this cell to it. This is necessary so the LetterCluster knows that this cell belongs to it, helping manage the cluster effectively.

      Parameters:
      cluster - The LetterCluster that this LetterCell should be added to. Must be an instance of LetterCluster.
      Returns:
      true if the cell was successfully added to the cluster.
      Throws:
      IllegalArgumentException - If the given CellCluster isn't a LetterCluster.

    • removeCluster

      public boolean removeCluster(CellCluster cluster)
      Removes this LetterCell from the specified CellCluster.

      This method clears the reference to the cluster that this LetterCell belongs to by setting it to null. If this cell isn't part of the given cluster, the method doesn't do anything.

      It's important that this method is only called from inside the managing LetterCluster to prevent unintended recursive calls, which could cause infinite loops.

      Note that this method doesn't modify the provided CellCluster. It simply removes the link between this cell and the cluster since a LetterCell can only be part of one cluster at a time.

      Parameters:
      cluster - The CellCluster from which this LetterCell should be removed. This argument is not modified by this method.
      Returns:
      true (always) to indicate the operation was successful.

    • getMainCluster

      public CellCluster getMainCluster()
      Returns the CellCluster instance that this LetterCell currently belongs to.
      Returns:
      The CellCluster associated with this LetterCell, or null if it doesn't belong to any cluster.

    • inActiveCluster

      public boolean inActiveCluster()
      Checks whether the cluster this LetterCell belongs to is currently active.
      Returns:
      true if the cluster is active, false otherwise.

    • inCluster

      public boolean inCluster()
      Indicates whether this LetterCell is part of a LetterCluster.

      This method should return true in most cases, as a LetterCell generally belongs to a single LetterCluster.

      Returns:
      true if this LetterCell is part of a cluster, false otherwise.

    • toString

      public String toString()
      Returns a string representation of the LetterCell object.

      This method overrides the toString method to provide a detailed description of the LetterCell instance. The output includes the content of the cell enclosed in square brackets, followed by information about the cluster to which the cell belongs. If the cell is not part of any cluster, the output will indicate "None"; otherwise, it will display the text content of the associated cluster.

      Overrides:
      toString in class Object
      Returns:
      A string that represents the LetterCell, including its content and associated cluster information.

    • sharesClusterWith

      public boolean sharesClusterWith(Cell cell)
      Determines whether this LetterCell shares the same cluster with the specified Cell.

      This implementation specifically checks if the provided Cell is not an instance of SymbolCell. If the specified Cell is a SymbolCell, the method immediately returns false as LetterCells and SymbolCells are not considered to be in the same cluster due to differing characteristics.

      If the specified Cell is not a SymbolCell, this method then checks if the specified Cell is contained within the same cluster as this LetterCell. This check is performed by calling the contains method on the cluster associated with this LetterCell.

      Parameters:
      cell - the Cell to compare with this instance for cluster membership.
      Returns:
      true if this LetterCell and the specified Cell are part of the same cluster; false otherwise.

    • getContent

      public char getContent()
      Retrieves the character content of this cell.
      Specified by:
      getContent in interface Cell
      Returns:
      the character content of this cell.

    • isActive

      public boolean isActive()
      Checks if the cell is currently active.
      Specified by:
      isActive in interface Cell
      Returns:
      true if the cell is active, false otherwise.

    • setActive

      public void setActive(boolean newState)
      Sets the active state of this cell.
      Specified by:
      setActive in interface Cell
      Parameters:
      newState - the new active state of this cell.

    • addStateListener

      public void addStateListener(javafx.beans.value.ChangeListener<? super Boolean> listener)
      Adds a listener to the `isActiveProperty` to monitor changes in its value. The listener will be notified whenever the value of the `isActiveProperty` changes.
      Specified by:
      addStateListener in interface Cell
      Parameters:
      listener - the listener to add; it must be an implementation of ChangeListener that can handle the value of type Boolean.

    • addContentListener

      public void addContentListener(javafx.beans.value.ChangeListener<? super Character> listener)
      Registers a listener that will be notified when the content of the cell changes, such as when it is filled or modified. The listener will receive a notification whenever the character content within the cell is altered.
      Specified by:
      addContentListener in interface Cell
      Parameters:
      listener - the ChangeListener to be added; it will be triggered with a Character when the cell's content changes

    • addClickListener

      public void addClickListener(javafx.beans.value.ChangeListener<? super Boolean> cl)
      Adds a listener that will be notified whenever the value of the `clickCount` property changes.
      Specified by:
      addClickListener in interface Cell
      Parameters:
      cl - the listener to be added, which should implement the ChangeListener<? super Number> interface. This listener will be notified with the new value whenever the `clickCount` changes.

    • click

      public void click()
      Toggles the value of the `clickProperty`, thereby triggering any event listeners that are bound to this property. When called, this method switches the current state of the `clickProperty` to its opposite value, which causes any registered listeners to react accordingly.
      Specified by:
      click in interface Cell

    • matches

      public boolean matches(Cell cell)
      Compares this Cell with the specified Cell to determine if their content is identical.

      This method returns true if the specified Cell is of the same subclass and their content matches. If the cells are of different subclasses, it returns false.

      Specified by:
      matches in interface Cell
      Parameters:
      cell - The Cell to compare with this Cell.
      Returns:
      true if the cells are of the same subclass and have identical content; false otherwise.