# 1 Introduction

## 1.1 Purpose
This specification establishes the requirements for the product named Qheadache. The intended audience is the analyst, programmer, and tester of Qheadache.

## 1.2 Scope
Qheadache is a stand-alone computerized game that provides an interface to solve a specific sliding-block puzzle (“headache”). The software:
- Presents a main window with a game board and a menu bar.
- Enables users to move blocks within a defined board.
- Tracks time spent and number of moves.
- Provides undo and redo for recent actions.
- Records and displays scores associated with player names.
- Supports opening and saving game state.

The application benefits include entertainment and challenge for a broad user audience, with simple interaction and basic score tracking.

## 1.3 Product overview

### 1.3.1 Product perspective
Qheadache is a standalone desktop application.

- System interfaces
  - [N/A]

- User interfaces
  - Main window with:
    - A board (rectangular zone) where the user moves blocks.
    - A menu bar with Game, Action, Statistics, and Help menus.
  - User interaction via mouse for selection, movement, and menu activation.
  - The interface uses menus, graphics, and sounds. Sound is not required to play the game.

- Hardware interfaces
  - Requires a keyboard and a mouse for input.
  - Requires a graphical display with a minimum resolution of 800×600.

- Software interfaces
  - Uses the Qt graphical library.
  - Must run with all operating systems that Qt supports.

- Communications interfaces
  - [N/A]

- Memory constraints
  - [N/A]

- Operations
  - [N/A]

- Site adaptation requirements
  - [N/A]

- Interfaces with services
  - [N/A]

### 1.3.2 Product functions
- Game board setup and block manipulation:
  - Display a rectangular board with defined dimensions and block types.
  - Select, move, and deselect blocks with mouse input, constrained to board boundaries and non-overlap rules.
- Undo/Redo:
  - Undo the last movement and redo a previously undone movement, up to a defined recent-history limit.
- End-of-game handling:
  - Detect the winning condition and freeze statistics.
  - Display a finish window; conditionally prompt for player name if qualifying for statistics.
- Statistics management:
  - Track per-game statistics (moves, elapsed time).
  - Maintain a statistics file with up to 10 player records (name, moves, time).
  - Display and erase statistics.
- File management:
  - Open a previously saved game.
  - Save the current game and save as a new file.
  - Exit with option to save unsaved progress.
- Menu system:
  - Game, Action, Statistics, and Help menus, including an About window.

### 1.3.3 User characteristics
- No qualification is necessary.
- Intended for anyone who wants to play a simple game and knows how to operate a computer, from beginning level (starting at age 8) through advanced players.

### 1.3.4 Limitations
- Hardware limitation: minimum display resolution of 800×600; requires keyboard and mouse.
- Capacity: only one user per machine.
- Portability: must run on operating systems supported by Qt; portable to the Windows OS.
- Sound is optional and not required to play the game.

## 1.4 Definitions
[N/A]

# 2 References
[N/A]

# 3 Requirements

## 3.1 Functions

- Main window
  - The main window shall provide:
    - A board for block manipulation.
    - A menu bar with Game, Action, Statistics, and Help menus.

- Board and blocks
  - Board presentation:
    - The board is a rectangular zone where the user moves blocks.
    - Let x be the unit of measure, with 50 px ≤ x ≤ 100 px.
    - Board dimensions: height 5x, width 4x.
    - Blocks are separated by a margin of 0.1x.
    - Blocks:
      - Four square blocks with side x.
      - Four rectangular blocks: height 2x, width x.
      - One rectangular block: height x, width 2x.
      - One square block with side 2x.
    - Colors:
      - Board is black.
      - Blocks are yellow.

- Block selection
  - Input: Left mouse button down on a block.
  - Processing: The game state becomes “Block movement.”
  - Output: None.

- Block deselection
  - Input: Left mouse button up on a selected block.
  - Processing: The game state becomes “Block selection.”
  - Output: None.

- Block movement
  - Input: Mouse movement during the “Block movement” state.
  - Processing:
    - The selected block follows the mouse movement.
    - Blocks shall not overlap other blocks.
    - Blocks shall not exit the board.
    - The selected block shall not move nearer than 0.05x to other blocks.
  - Output: None.

- Undo action
  - Description: The user can cancel the last movement.
  - Input: Menu selection “Undo.”
  - Processing:
    - The game restores the block positions to those before the last movement.
    - This action is considered a movement.
    - “Undo” is unavailable if there was no previous movement.
  - Output: Updated game board display.

- Redo action
  - Description: The user can redo a movement that has been canceled.
  - Input: Menu selection “Redo.”
  - Processing:
    - The game restores the block positions to those before the last movement was canceled.
    - This action is considered a movement.
    - “Redo” is unavailable if the previous action was not an “Undo.”
  - Output: Updated game board display.

- End of the game detection and handling
  - End condition
    - Input: The large square block is moved to the bottom of the board.
    - Processing:
      - All player statistics are frozen.
    - Output:
      - If the current number of block movements is lower than the highest number of block movements recorded in the statistics file, display the “Finish Window with Statistics.”
      - Otherwise, display the “Simple Finish Window.”
  - Finish Window with Statistics
    - Description:
      - Displays the text: “You win! Enter your name:”
      - Provides an edit box that can contain 20 characters.
      - Provides a pushbutton labeled “OK.”
    - Input: End-of-game condition met.
    - Processing:
      - On clicking “OK,” the player statistics are recorded in the statistics file per game statistics management.
    - Output:
      - Close the finish window.
      - Display the statistics window.
  - Simple Finish Window
    - Description:
      - Displays the text: “You win!”
      - Provides a pushbutton labeled “OK.”
    - Input: End-of-game condition met.
    - Processing:
      - On clicking “OK,” close the window.
    - Output:
      - Close the finish window.
      - Display the statistics window.

- Statistics management
  - Player statistics tracking
    - Description:
      - During the game, record:
        - Number of block movements since the start.
        - Time since the start.
    - Input: A block movement occurs.
    - Processing:
      - Increment number of block movements by 1.
      - Record the time difference between this movement and the previous recorded time.
    - Output: None.
  - Game statistics file management
    - Description:
      - The game statistics consist of 10 player statistics.
    - Input:
      - Completion of the Finish Window with Statistics by the player (name entry).
    - Processing:
      - Record the player’s name, the number of block movements, and the time taken to solve the puzzle into the statistics file.
      - If 10 player statistics are already recorded, erase the player statistics in the file with the greatest number of block movements.
    - Output:
      - No output if the file was correctly updated.
      - If update fails (e.g., wrong permissions or disk full), display an error message.
  - Statistics erasing
    - Description: The user can erase all statistics.
    - Input: Menu selection “Erase.”
    - Processing: Erase data stored in the statistics file.
    - Output:
      - No output if the file was correctly updated.
      - If update fails (e.g., wrong permissions or disk full), display an error message.
  - Statistics window
    - Description:
      - A window listing up to 10 lines.
      - Each line contains the player name, number of block movements, and time used to solve the puzzle.
      - Data are read from the statistics file.
    - Input: End-of-game completion or menu selection “Display.”
    - Processing: Display the window.
    - Output: None.

- File management
  - Open game
    - Description: Open a previously saved game.
    - Input: Menu selection “Open game...”
    - Processing:
      - Open a dialog box for the user to choose a saved game file containing all game data.
    - Output:
      - Redraw the board according to the file data.
      - Set player statistics to the statistics from the file.
  - Save game
    - Description: Save the current game.
    - Input: Menu selection “Save game...”
    - Processing:
      - If the game was never saved, behave identically to “Save game as...”
      - Otherwise, save to the previously used file:
        - Current positions of the blocks.
        - Their last 10000 previous positions.
        - The number of previous movements.
        - The time spent by the user.
    - Output: None.
  - Save game as
    - Description: Save the current game to a new file.
    - Input: Menu selection “Save game as...”
    - Processing:
      - Open a dialog box for the user to choose a destination file for the current game.
      - Save to the chosen file:
        - Current positions of the blocks.
        - Their previous positions.
        - The number of previous movements.
        - The time spent by the user.
    - Output: None.
  - Exit
    - Description: Stop the game.
    - Input: Menu selection “Exit.”
    - Processing:
      - If the game is not saved, display a dialog asking if the player wants to save the game with choices “Yes” and “No.”
      - If “Yes,” perform Save and close the main window.
      - If “No,” close the main window.
    - Output: None.

- Menu bar
  - Game menu
    - Contains, in order: “Open game...”, “Save Game...”, “Save Game As...”, “Exit.”
    - Input: Menu selection.
    - Processing: Perform the corresponding action.
    - Output: Menu closes; subsequent behavior per the selected action.
  - Action menu
    - Contains, in order: “Undo”, “Redo.”
    - Menu item is unavailable if the associated action is unavailable.
    - Input: Menu selection.
    - Processing: Perform Undo or Redo.
    - Output: Menu closes; subsequent behavior per the selected action.
  - Statistics menu
    - Contains, in order: “Display”, “Erase.”
    - Input: Menu selection.
    - Processing: Display statistics window or erase statistics.
    - Output: Menu closes; subsequent behavior per the selected action.
  - Help menu
    - Contains: “About.”
    - Input: Menu selection.
    - Processing:
      - Display “About” window composed of the text:
        - “Qheadache 1.0 by Jean‑Philippe Brossat jp_brossat@yahoo.fr”
    - Output: Menu closes; subsequent behavior per the selected action.

## 3.2 Performance requirements
- There can be only one user per machine.

## 3.3 Usability requirements
[N/A]

## 3.5 Logical database requirements
- Types of information
  - Player statistics record: player name (up to 20 characters in input), number of block movements, elapsed time.
  - Statistics file contains up to 10 player statistics.
- Frequency of use
  - Updated at end of game upon name entry; displayed on demand.
- Accessing capabilities
  - Read for display; write for recording new results and erasing.
- Data entities and relationships
  - [N/A]
- Integrity constraints
  - Maintain at most 10 records by erasing the record with the greatest number of block movements when adding a new one to a full file.
- Security
  - [N/A]
- Data retention requirements
  - Persist statistics across sessions until erased by the user.

## 3.6 Design constraints
- The product uses the Qt graphical library.
- The product must run with all operating systems that Qt supports.
- Requires a keyboard and mouse.
- Requires a display with at least 800×600 resolution.

## 3.7 Software system attributes
- Reliability
  - [N/A]
- Availability
  - [N/A]
- Security
  - [N/A]
- Maintainability
  - [N/A]
- Portability
  - Must be portable to the Windows OS.
  - Must run with all operating systems that Qt supports.

## 3.8 Supporting information
[N/A]

# 4 Verification

## 4.1 Functions
[N/A]

## 4.2 Performance requirements
[N/A]

## 4.3 Usability requirements
[N/A]

## 4.5 Logical database requirements
[N/A]

## 4.6 Design constraints
[N/A]

## 4.7 Software system attributes
[N/A]

# 5 Appendices

## 5.1 Assumptions and dependencies
- The operating system is supported by Qt.
- A keyboard and mouse are available.
- A display with at least 800×600 resolution is available.
- File operations depend on sufficient permissions and disk space; otherwise, an error message is displayed when updating statistics.

## 5.2 Acronyms and abbreviations
[N/A]