GridState Modes refactor, take 2

Status: Implemented | Jan 2024

Status: Updated | Dec 2024

See also: xword-state-modes.md

Summary

Supplement the GridStateMode enum with a set of distinct behaviors. These behaviors can be set individually on a state.

This will make grid-state.c easier to understand and debug (and test), as well as let us create modes on demand later on.

Rationale

The current grid modes have been created on demand when we need a new grid type. The modes combine some rendering options, cursor behaviors, and thematic functionality all in one. They are hard to reason about, and have proven fragile and brittle over time.

Proposal

We decompose the current modes into a set of behaviors that are independently settable. The current modes are:

typedef enum
{
  GRID_STATE_SOLVE,       /* @ Solve a crossword @ */
  GRID_STATE_BROWSE,      /* @ Browse through a board without modifying it @ */
  GRID_STATE_EDIT,        /* @ Edit the grid @ */
  GRID_STATE_EDIT_BROWSE, /* @ Browse through an editable board without modifying it @ */
  GRID_STATE_SELECT,      /* @ Select cells @ */
  GRID_STATE_VIEW,        /* @ Display a board with no interaction @ */
} GridStateMode;

Tenets

The behaviors indicate how the grid behaves. We have the following rules for behaviors:

• Each behavior acts independently, and shouldn’t depend on another behavior. That is to say, we never have if (behavior1 && behavior2) {... in the code. || statements are fine.

• We add new behaviors rather than special casing the code. While occasionally complex to implement, it’s better to add a new one rather than overloading them.

• Modes are just a convenience. It’s possible and plausible to just use a set of behaviors.

Decomposition

Here’s the decomposition into behaviors:

	SOLVE	BROWSE	EDIT	EDIT_BROWSE	SELECT	VIEW
USE_CURSOR	true	true	true	true	true	false
SHOW_GUESS	true	true	false	false	true	false
SELECTABLE	false	false	false	false	true	false
EDIT_CELLS	true	false	true	false	false	false
NORMAL_ONLY	true	true	false	true	true	false
QUIRKS_ADVANCE	true	false	false	false	false	false
EMIT_DRAG	false	false	true	false	true	false

Each behavior is described below:

• USE_CURSOR: The state has a valid cursor, and a direction

• SHOW_GUESS: The grid displays the guess instead of the solution in a cell

• SELECTABLE: The grid can select cells

• EDIT_CELLS: The grid allows the user to edit the cell

• NORMAL_ONLY: The grid only allows the cursor to exist on normal cells. BLOCK and NULL cells can’t have a cursor set

• QUIRKS_ADVANCE: Whether to honor the quirks GuessAdvance setting when going to the next cell after a guess.

• EMIT_DRAG: Emit the drag signals. This can be used to either trigger a selection, or update an existing one.

This set of booleans is represented by the GridState.behavior bitfield. Setting the mode will set the bitfield to a well known state.

Changing the behavior afterwards is possible. We will add a GRID_STATE_CUSTOM mode to capture when that has happened.

NOTE: Not all combinations of behaviors are valid

Other Considerations

• Selection may need multiple selection types in the future (like GtkEditable, for instance.)

• We want to move an overlay mode for things like reveal errors, pencil markings, or heat maps. That might factor into this design.