Play State Modes refactor

Status: Deprecated (Feb 6, 2024)

Changes

NOTE: There have been some substantial updates to the code since this was authored. Most of the information included is not wrong, but it’s insufficient to describe this enum. In particular:

Original Doc

Rationale:

As per Issue #45 and Issue #11, we have a confusing set of interactions between settings and modes. This is an attempt to clean them up and document them better. It also cleans up some pathologies along the way.

XwordState

We propose the new structure and enums:

typedef enum
{
  XWORD_STATE_SOLVE,       /* @ Solve a crossword @ */
  XWORD_STATE_BROWSE,      /* @ Browse through a board without modifying it @ */
  XWORD_STATE_EDIT,        /* @ Edit the grid @ */
  XWORD_STATE_EDIT_BROWSE, /* @ Browse through a board without modifying it @ */
  XWORD_STATE_SELECT,      /* @ Select cells @ */
  XWORD_STATE_VIEW,        /* @ Display a board with no interaction @ */
} XwordStateMode;

typedef enum
{
  XWORD_REVEAL_NONE,         /* @ Reveal nothing. Display the crossword as normal @ */
  XWORD_REVEAL_ALL,          /* @ Reveal all unsolved letters. Effectively give up @ */
  XWORD_REVEAL_ERRORS_BOARD, /* @ Reveal all incorrect guesses on the board @ */
  XWORD_REVEAL_ERRORS_CLUE,  /* @ Reveal all incorrect guesses in the current clue @ */
  XWORD_REVEAL_ERRORS_CELL,  /* @ Reveal all incorrect guesses in the current cell @ */
} XwordRevealMode;

typedef enum
{
  XWORD_SELECTION_SINGLE,            /* @ Select individual cells, only @ */
  XWORD_SELECTION_TYPE_LETTERS_ONLY, /* @ Only lets the user select guessed letters @ */
  XWORD_SELECTION_TYPE_BLANKS_ONLY,  /* @ Only lets the user select empty spaces @ */
} XwordSelectionMode;

typedef struct
{
  XwordStateMode mode;
  IPuzPuzzle *xword;

  /* Current keyboard state */
  IPuzCellCoord cursor;
  ClueId clue;

  /* Modifiers to the current display and behavior */
  XwordRevealMode reveal_mode;
  XwordSelectionMode selection_mode;
  CellArray *cell_array;
  CrosswordsQuirks *quirks; 
} XwordState;

Modes:

This is a description of each mode, and which fields affect each mode.

  • XWORD_STATE_SOLVE - Play the game. Lets the user guess answers

    • reveal_: Enum to indicate whether to reveal any errors

    • keyboard state: Current cursor position and direction

    • quirks: Uses the quirks to affect behaviours

  • XWORD_STATE_BROWSE - It’s similar to play but the user can only select cells, and can’t edit the board.

    • keyboard state: Current cursor position and direction

  • XWORD_STATE_EDIT - The answer is editable and shown. The guesses struct is ignored.

    • keyboard state: Current cursor position and direction

    • quirks: Uses the quirks to affect behaviours

  • XWORD_STATE_EDIT_BROWSE - Similar to browse, but with slightly different movement behaviors. The guesses struct is ignored. Used for clue editing.

    • keyboard state: Current cursor position and direction

  • XWORD_STATE_SELECT - The cell selection mode. Used for the the autofill and clue header. The guesses struct is ignored.

    • select-mode: enum to define the selection behavior. This acts very different than a list, so won’t reuse any other selection modes

    • keyboard state: Current cursor position and direction

    • cell_array: Current selection

  • XWORD_STATE_VIEW - No interaction with the user possible. Used for the hero graphics, etc.

Note: PlayXword can’t render XWORD_STATE_EDIT and EditXword can’t render XWORD_STATE_SOLVE.

Next Steps:

  • [X] Rename PlayState to XwordState, as well as the various enums and fields listed above

  • [X] Add XWORD_STATE_VIEW

  • [X] Add XWORD_STATE_EDIT_BROWSE

  • [X] Change reveal and selection to enums

  • [ ] Composable handlers to adjust the state from a more semantic model and the mode /quirk based changes

  • [X] Use IPuzCellCoord everywhere, and drop the row/column args

  • [ ] (TBD) Change all the actions into a _dispatch() call, and create a single XwordEvent type

  • [ ] (TBD) separate the guesses from the board

  • [ ] Update xword-state.md and xword-state-modes.md to match new reality