# 1 Introduction
[NULL]

## 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 computerized game that displays an interface used to solve a specific puzzle (“headache”). The software enables the user to manipulate blocks on a board to reach a goal state, track play time and move count, undo/redo actions, record and view scores, and save/open games.

## 1.3 Product overview
[NULL]

### 1.3.1 Product perspective
Qheadache is a stand-alone desktop application. It relies on the Qt graphical library and shall run on all operating systems supported by Qt.

- System interfaces
  - [N/A]

- User interfaces
  - The product runs as a stand-alone application.
  - The user interface uses menus, graphics, and sounds.
  - Sound is not required to play the game.
  - The main window provides:
    - A board (see 3.1 Functions for board and gameplay).
    - A menu bar (see 3.1 Functions for menu details).

- Hardware interfaces
  - Keyboard and mouse (or equivalent pointing/typing devices) are required.
  - A graphical display with at least 800×600 screen resolution is required.

- Software interfaces
  - Qt graphical library; the game must run on all operating systems supported by Qt.

- Communications interfaces
  - [N/A]

- Memory constraints
  - [N/A]

- Operations
  - User-initiated, interactive operation via mouse and keyboard.
  - Normal operation includes starting the application, playing the game, saving/opening games, viewing and erasing statistics, and exiting.
  - Backup and recovery are limited to user-initiated save/open of game files and statistics error reporting.

- Site adaptation requirements
  - [N/A]

- Interfaces with services
  - [N/A]

### 1.3.2 Product functions
- Present a block-based board and allow selection, movement, and placement of blocks within defined geometric and spacing constraints.
- Detect end-of-game condition when the great square block reaches the bottom of the board.
- Track and display elapsed play time and number of block movements.
- Undo and redo user actions (up to the last thousand actions).
- Record player statistics (name, move count, time) on win; manage a top-10 statistics file.
- Display a statistics window; allow erasing all statistics.
- Provide file management for opening and saving games (including game state and history).
- Provide menus for Game actions, Action (Undo/Redo), Statistics (Display/Erase), and Help (About).

### 1.3.3 User characteristics
- The users consist of anyone who wants to play a simple game and knows how to operate a computer, from beginning level players starting at age 8 up to advanced adult players.
- No qualification is necessary.

### 1.3.4 Limitations
- Only one user per machine at a time.
- Requires keyboard and mouse (or equivalent) and at least 800×600 display resolution.
- Must run on operating systems supported by Qt; portability to Windows OS is required.
- Sound is optional and not required for gameplay.
- Undo/redo limited to the last thousand actions.
- Statistics are limited to 10 player entries in the statistics file.
- No communications interfaces are required.

## 1.4 Definitions
- x: Unit length used to define the board and blocks. 50 pixels ≤ x ≤ 100 pixels.
- Statistic file: The game’s file that stores up to 10 player statistics (player name, number of block movements, elapsed time).

# 2 References
[N/A]

# 3 Requirements
[NULL]

## 3.1 Functions
- Game board and block manipulation
  - Board presentation
    - The board is a rectangular zone where the user can move blocks.
    - Board dimensions: height = 5x; width = 4x; with 50 pixels ≤ x ≤ 100 pixels.
    - Blocks are separated by a margin of 0.1x; blocks must not be closer than 0.05x to other blocks when moving.
    - Block set:
      - Four square blocks with side x.
      - Four rectangular blocks of height 2x and width x.
      - One block of height x and width 2x.
      - One square block with side 2x (the “great square”).
    - Colors: board is black; blocks are yellow.
  - Block selection
    - Inputs: Left-click down on a block.
    - Processing: The game state becomes “Block deplacement.”
    - Outputs: None.
  - Block deselection
    - Inputs: Left-click up on a selected block.
    - Processing: The game state becomes “Block selection.”
    - Outputs: None.
  - Block movement
    - Inputs: Mouse movement during the “Block movement” state.
    - Processing:
      - The selected block follows the mouse movement without overlapping other blocks and without exiting the game zone.
      - The selected block cannot move nearer than 0.05x to other blocks.
    - Outputs: None.

- Undo/redo actions
  - Undo
    - Description: The user can cancel a movement.
    - Inputs: Menu selection (“Undo”).
    - Processing:
      - The game displays the block positions as they were before the last movement.
      - This action is considered a movement.
      - “Undo” is unavailable if there was no previous movement.
    - Outputs: Updated game board display.
  - Redo
    - Description: The user can redo a canceled movement.
    - Inputs: Menu selection (“Redo”).
    - Processing:
      - The game displays the block positions as they were before the last movement was canceled.
      - This action is considered a movement.
      - “Redo” is unavailable if the previous action was not an “Undo.”
    - Outputs: Updated game board display.
  - Capacity constraint
    - The user must be able to undo and redo the last thousand actions.

- End-of-game management
  - End of the game
    - Description: How the user finishes the game.
    - Inputs: The great square is moved to the bottom of the board.
    - Processing: All player statistics are frozen.
    - Outputs:
      - If the number of block movements of the current player 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: Contains the text “You win ! Enter your name : ”, an edit box that can contain 20 characters, and a pushbutton labeled “OK.”
    - Inputs: The game is over.
    - Processing:
      - The player clicks “OK.”
      - The player statistics are recorded in the statistics file according to Game Statistics management.
    - Outputs:
      - The finish window closes.
      - The statistics window is displayed.
  - Simple Finish Window
    - Description: Contains the text “You win !” and a pushbutton labeled “OK.”
    - Inputs: The game is over.
    - Processing: The player clicks “OK.”
    - Outputs:
      - The finish window closes.
      - The statistics window is displayed.

- Statistics management
  - Player statistics
    - Description: Statistics recorded during the game are:
      - Number of block movements since the start.
      - Time elapsed since the start.
    - Inputs: A block movement occurs.
    - Processing:
      - Increment the number of block movements by 1.
      - Record the time difference between the current movement and the previous recorded time.
    - Outputs: None.
  - Game statistics
    - Description: The game statistics file is composed of 10 player statistics entries.
    - Inputs: The Finish Window with Statistics is completed by the player (name entered and “OK” pressed).
    - Processing:
      - Record the player’s name, number of block movements, and time to solve the puzzle in the statistics file.
      - If 10 player statistics are already recorded, erase the entry with the greatest number of block movements.
    - Outputs:
      - If the file was correctly updated, no output.
      - Otherwise (e.g., wrong permissions or disk full), display an error message.
  - Statistics erasing
    - Description: The user can erase all statistics.
    - Inputs: Menu selection (“Erase”).
    - Processing: Erase the data stored in the statistics file.
    - Outputs:
      - If the file was correctly updated, no output.
      - Otherwise (e.g., wrong permissions or disk full), display an error message.
  - Statistics window
    - Description:
      - The Player Statistics Window is composed of a listbox of 10 lines.
      - Each line shows the player name, number of block movements, and time used to solve the puzzle, read from the statistics file.
    - Inputs: End of the game or menu selection (“Display”).
    - Processing: Display the window.
    - Outputs: None.

- File management
  - Open game
    - Description: Open a previously saved game.
    - Inputs: Menu selection (“Open game …”).
    - Processing: Open a dialog box for the user to choose a file containing previously saved game data.
    - Outputs:
      - The board is redrawn according to the file data.
      - The player statistics are set to the file’s stored statistics.
  - Save game
    - Description: Save the current game.
    - Inputs: Menu selection (“Save Game …”).
    - Processing:
      - If the game was never saved, perform “Save game as …”
      - Otherwise, save to the previously used file the following internal data:
        - Current positions of the blocks.
        - Their last 10000 previous positions.
        - The number of previous movements.
        - The time elapsed to solve the puzzle so far.
    - Outputs: None.
  - Save game as
    - Description: Save the current game to a new file.
    - Inputs: Menu selection (“Save Game As…”).
    - Processing:
      - Open a dialog for the user to choose a file.
      - Save the following internal data:
        - Current positions of the blocks.
        - Their previous positions.
        - The number of previous movements.
        - The time elapsed to solve the puzzle so far.
    - Outputs: None.
  - Exit
    - Description: Stop the game.
    - Inputs: Menu selection (“Exit”).
    - Processing:
      - If the game is not saved, display a dialog asking whether to save the game with choices “Yes” and “No.”
      - If “Yes,” perform “Save” and close the main window.
      - If “No,” close the main window.
    - Outputs: None.

- Menu bar and help
  - Game menu
    - Description: Contains “Open game …”, “Save Game …”, “Save Game As…”, and “Exit” (in this order).
    - Inputs: Menu selection.
    - Processing:
      - “Open game …” → Open game.
      - “Save Game …” → Save game.
      - “Save Game As …” → Save game as.
      - “Exit” → Exit.
    - Outputs: Menu disappears; the selected action’s requirements determine follow-on behavior.
  - Action menu
    - Description: Contains “Undo” and “Redo” (in this order). Menu items are unavailable if their associated actions are unavailable.
    - Inputs: Menu selection.
    - Processing:
      - “Undo” → Undo Action.
      - “Redo” → Redo Action.
    - Outputs: Menu disappears; the selected action’s requirements determine follow-on behavior.
  - Statistics menu
    - Description: Contains “Display” and “Erase” (in this order).
    - Inputs: Menu selection.
    - Processing:
      - “Display” → Display the statistics window.
      - “Erase” → Erase the statistics.
    - Outputs: Menu disappears; the selected action’s requirements determine follow-on behavior.
  - Help menu
    - Description: Contains “About”.
    - Inputs: Menu selection.
    - Processing:
      - Display “About Window” composed of the text:
        - “Qheadache 1.0 by Jean-Philippe Brossat jp_brossat@yahoo.fr”
    - Outputs: Menu disappears; the selected action’s requirements determine follow-on behavior.

## 3.2 Performance requirements
- Capacity
  - Only one user per machine is supported.
  - The system shall maintain undo/redo history for the last 1000 actions.
- [N/A] for additional measurable timing/throughput constraints.

## 3.3 Usability requirements
- Menu items for actions shall be disabled when the associated actions are unavailable (e.g., Undo when there is no previous movement).
- The UI is intended for users aged 8 and above with basic computer operation skills.
- [N/A] for measurable effectiveness, efficiency, and satisfaction criteria.

## 3.5 Logical database requirements
- Data entities
  - PlayerStatistic: playerName (max 20 characters), moveCount (integer), elapsedTime (time duration).
  - StatisticsFile: collection of up to 10 PlayerStatistic entries.
  - GameSave: current block positions, previous positions (history), moveCount, elapsedTime.
- Accessing capabilities
  - Read: display statistics window; open game.
  - Write: record statistics upon win; save game; erase all statistics.
- Integrity constraints
  - Statistics file shall contain at most 10 entries; if adding an 11th, erase the entry with the greatest move count.
  - On write failure (e.g., permissions, disk full), an error message shall be displayed.
- Security
  - [N/A]
- Data retention
  - Statistics persist between application sessions in a statistics file (up to 10 entries).
  - Saved games persist block positions and history:
    - Save operation retains last 10000 previous positions.
    - Save As operation retains previous positions (count not specified).

## 3.6 Design constraints
- The product uses the Qt graphical library.
- The product must run on all operating systems that Qt supports.
- The software must be portable to the Windows OS.
- Requires keyboard and mouse (or equivalent pointing/typing devices).
- Requires a display resolution of at least 800×600.
- Sound is optional and not required.

## 3.7 Software system attributes
- Portability
  - The software must run on operating systems supported by Qt.
  - The software must be portable to the Windows OS.
- Reliability
  - [N/A]
- Availability
  - [N/A]
- Security
  - [N/A]
- Maintainability
  - [N/A]

## 3.8 Supporting information
[N/A]

# 4 Verification
[NULL]

## 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
[NULL]

## 5.1 Assumptions and dependencies
- The Qt graphical library is available on the target operating system.
- A keyboard and mouse (or equivalent devices) are available.
- A display with at least 800×600 resolution is available.
- Single-user operation per machine is acceptable for the intended use.

## 5.2 Acronyms and abbreviations
- OS: Operating System
