# 1 Introduction
[NULL]

## 1.1 Purpose
The purpose of the Qheadache software is to provide a computerized game that displays an interface used to solve a specific headache.

## 1.2 Scope
The software product to be produced is named Qheadache. It is a computerized game that provides an interactive interface for solving a specific puzzle, referred to as a "headache." The application's primary function is to allow users to manipulate blocks on a game board to solve the puzzle.

The objectives of Qheadache include:
*   Presenting a graphical game board with movable blocks.
*   Enabling users to perform and undo/redo actions during gameplay.
*   Tracking and displaying player statistics such as time spent and number of actions.
*   Recording and managing player scores associated with game completion.
*   Providing functionality to save and load game progress.

Qheadache is designed as a simple game suitable for a broad range of users, from beginning level players (starting at age 8) to advanced adult players, offering an engaging puzzle-solving experience.

## 1.3 Product overview
[NULL]

### 1.3.1 Product perspective
The product, Qheadache, runs as a stand-alone application and is not an element of a larger system.

#### System interfaces
[N/A]

#### User interfaces
The software product's user interface utilizes menus, graphics, and sounds. Users interact with the system primarily through a keyboard and a mouse. Other pointing and input devices are allowable, provided they offer similar functionalities, such as the ability to move a cursor onscreen to select buttons and to type names. The main window of the application provides a game board and a menu bar.

#### Hardware interfaces
The software product requires a keyboard and a mouse for user input. It also necessitates a graphical display with a minimum resolution of 800x600 pixels. While the product uses sounds, sound is not a mandatory requirement to play the game.

#### Software interfaces
The product uses the Qt graphical library. It is designed to run on all operating systems that support the Qt library.

#### 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
The Qheadache product performs the following major functions:

*   **Action Management**: Users can undo and redo their last thousand actions within the game.
*   **Time Tracking**: The product counts and displays the total time a user spends playing.
*   **Action Counting**: The product counts and displays the number of actions a user performs during a game.
*   **Score Management**: The product records the score (based on time and action count) of a play, associating it with a user's name.
*   **Score Display**: The product provides a window to display all recorded player scores.
*   **Game State Management**: Users can save the current game state, open previously saved games, and exit the application with an option to save unsaved progress.
*   **Statistics Management**: The product manages player and game statistics, including the ability to display and erase them.

### 1.3.3 User characteristics
The users consist of anyone who wants to play a simple game and knows how to operate a computer. No specific qualification is necessary. The target audience ranges from a beginning level player, starting at age 8, up through an advanced level player who could be an adult.

### 1.3.4 Limitations
The product is limited to running as a stand-alone application.

Hardware limitations include:
*   The product requires the use of a keyboard and a mouse for user interaction. Other pointing and input devices are allowable, provided they offer similar functions.
*   A graphical display with a minimum resolution of 800x600 is required.

Software limitations include:
*   The product must use the Qt graphical library.
*   It must be compatible with all operating systems that the Qt library supports.
*   The software must be portable to the Windows operating system.

The system is limited to supporting only one user per machine.

## 1.4 Definitions
[N/A]

# 2 References
[N/A]

# 3 Requirements
[NULL]

## 3.1 Functions
### 3.1.1 Actions

#### 3.1.1.1 Presentation of the board
The board is a rectangular zone where the user can move blocks.
The height of the board game is 5x, and its width is 4x, where 'x' is a measure unit.
The value of 'x' cannot be less than 50 pixels and cannot be greater than 100 pixels.
The blocks are separated by a margin of 0.1x.
There are four square blocks with a side of x.
There are four rectangular blocks with a height of 2x and a width of x.
There is one block with a height of x and a width of 2x.
There is one square block with a side of 2x.
The board is black, and the blocks are yellow.

#### 3.1.1.2 Block selection
*   **Description:** Allows the user to select a block on the board.
*   **Input:** Left-clicked down on a block.
*   **Processing:** The game state becomes "Block deplacement".
*   **Output:** None.

#### 3.1.1.3 Block deselection
*   **Description:** Allows the user to deselect a previously selected block.
*   **Input:** Left-clicked up on a selected block.
*   **Processing:** The game state becomes "Block selection".
*   **Output:** None.

#### 3.1.1.4 Block movement
*   **Description:** Allows the user to move a selected block.
*   **Input:** Mouse movement during the "Block movement" state.
*   **Processing:** The selected block follows the mouse movement. The block cannot overlap other blocks or exit the game zone. The selected block cannot move closer than 0.05x from other blocks.
*   **Output:** None.

#### 3.1.1.5 Undo Action
*   **Description:** The user can cancel the last movement.
*   **Input:** Menu selection (from the "Action" menu).
*   **Processing:** The game displays the block positions as they were before the last movement. This action is considered a movement. The "undo" action is unavailable if there was no previous movement.
*   **Output:** New game board display.

#### 3.1.1.6 Redo Action
*   **Description:** The user can redo a movement that has been canceled.
*   **Input:** Menu selection (from the "Action" menu).
*   **Processing:** The game displays the block positions as they were before the last movement was canceled. This action is considered a movement. The redo action is unavailable if the previous action was not an "undo" action.
*   **Output:** New game board display.

### 3.1.2 End of the game management

#### 3.1.2.1 End of the game
*   **Description:** Defines how the user finishes the game.
*   **Input:** The great square block 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 statistic file, the "Finish Window with Statistics" is displayed.
    *   Otherwise, the "Simple Finish Window" is displayed.

#### 3.1.2.2 Finish Window with Statistics
*   **Description:** This window contains the text: "You win! Enter your name:", an Edit Box that can contain 20 characters, and a pushbutton with the label "OK".
*   **Input:** The game is over, and the condition for displaying this window is met. The player enters a name and clicks "OK".
*   **Processing:** The player statistics (name, block movement number, time passed) are recorded in the statistic file, as per the game statistics management requirements.
*   **Outputs:** The "Finish" window is closed. The statistic window is displayed.

#### 3.1.2.3 Simple Finish Window
*   **Description:** This window contains the text: "You win!" and a pushbutton with the label "OK".
*   **Input:** The game is over, and the condition for displaying this window is met. The player clicks "OK".
*   **Processing:** The player clicks on the pushbutton "OK".
*   **Outputs:** The Simple Finish Window is closed. The statistic window is displayed.

### 3.1.3 Statistics Management

#### 3.1.3.1 Player Statistics management
*   **Description:** The following statistics are recorded during the game: number of block movements since the start and time since the start.
*   **Input:** A block movement occurs.
*   **Processing:** The number of block movements is incremented by 1. The time difference between the current block movement and the previously recorded time is recorded.
*   **Output:** None.

#### 3.1.3.2 Game Statistics management
*   **Description:** The game statistics are composed of 10 player statistics.
*   **Input:** The Finish Window with Statistics is completed by the player.
*   **Processing:** The statistics of the player (name, block movement number, time passed to solve the headache) are recorded in the statistic file. If 10 player statistics are already recorded, the player statistics in the file with the greatest number of block movements are erased to make room for the new entry.
*   **Output:** If the file was correctly updated, there is no output. If not (e.g., wrong permissions or disk full), an error message is displayed.

#### 3.1.3.3 Statistics erasing
*   **Description:** The user can erase all recorded statistics.
*   **Input:** Menu selection (from the "Statistics" menu).
*   **Processing:** The data stored in the statistic file are erased.
*   **Output:** If the file was correctly updated, there is no output. If not (e.g., wrong permissions or disk full), an error message is displayed.

#### 3.1.3.4 Statistic Window
*   **Description:** The Player Statistics Window is composed of a listbox of 10 lines. Each line displays the name of a player, the number of block movements, and the time used by the player to solve the headache. These statistics are read from the game's statistic file.
*   **Input:** End of the game (after a finish window is closed) or menu selection (from the "Statistics" menu).
*   **Processing:** The window is displayed.
*   **Output:** None.

### 3.1.4 File management

#### 3.1.4.1 Open game
*   **Description:** Allows opening a previously saved game.
*   **Input:** Menu selection (from the "Game" menu).
*   **Processing:** A dialog box is opened, allowing the user to choose a file that contains all the data of a previously saved game.
*   **Output:** The board game is redrawn according to the file data. The player statistics are set to the player statistics from the file data.

#### 3.1.4.2 Save game
*   **Description:** Allows saving the current game.
*   **Input:** Menu selection (from the "Game" menu).
*   **Processing:** If the game was never saved, the processing is identical to the "Save as..." action. Otherwise, the following internal data are saved into the previously used file: the current positions of the blocks, their last 10,000 previous positions, the number of previous movements, and the time passed by the user to solve the headache.
*   **Output:** None.

#### 3.1.4.3 Save game as
*   **Description:** Allows saving the current game to a new file or a specified file.
*   **Input:** Menu selection (from the "Game" menu).
*   **Processing:** A dialog box is opened, allowing the user to choose a file that will contain all the data of the current game. Then, the following internal data are saved into the file: the current positions of the blocks, their previous positions, the number of previous movements, and the time passed by the user to solve the headache.
*   **Output:** None.

#### 3.1.4.4 Exit
*   **Description:** Allows stopping the game.
*   **Input:** Menu selection (from the "Game" menu).
*   **Processing:** If the game is not saved, a dialog box is displayed asking the player if they want to save the game, with "Yes" and "No" choices. If "Yes" is selected, the "Save" action is processed, and the main window disappears. If "No" is selected, the main window disappears.
*   **Output:** None.

### 3.1.5 Menu bar

#### 3.1.5.1 Game menu
*   **Description:** Contains "Open game...", "Save Game...", "Save Game As...", and "Exit" in that order.
*   **Input:** Menu selection.
*   **Processing:** The selected action is performed:
    *   "Open game..." triggers the "Open game" action.
    *   "Save Game..." triggers the "Save Game" action.
    *   "Save Game As..." triggers the "Save game as" action.
    *   "Exit" triggers the "Exit" action.
*   **Output:** The menu disappears. The continuation is determined by the requirements of the specific action performed.

#### 3.1.5.2 Action menu
*   **Description:** Contains "Undo" and "Redo" in that order. The menu selection is unavailable if the associated action is unavailable.
*   **Inputs:** Menu selection.
*   **Processing:** The selected action is performed:
    *   "Undo" triggers the "Undo Action".
    *   "Redo" triggers the "Redo Action".
*   **Outputs:** The menu disappears. The continuation is determined by the requirements of the specific action performed.

#### 3.1.5.3 Statistics menu
*   **Description:** Contains "Display" and "Erase" in that order.
*   **Inputs:** Menu selection.
*   **Processing:** The selected action is performed:
    *   "Display" displays the statistic window.
    *   "Erase" erases the statistics.
*   **Outputs:** The menu disappears. The continuation is determined by the requirements of the specific action performed.

#### 3.1.5.4 Help menu
*   **Description:** Contains "About".
*   **Inputs:** Menu selection.
*   **Processing:** The "About Window" is displayed. The "About Window" contains the text "Qheadache 1.0 by Jean-Philippe Brossat jp_brossat@yahoo.fr".
*   **Outputs:** The menu disappears. The continuation is determined by the requirements of the specific action performed.

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

## 3.3 Usability requirements
The system shall be usable by individuals with no special qualifications. The target users range from beginning level players, starting at age 8, who know how to operate a computer, up through advanced adult players. This implies a requirement for high learnability and ease of use for a broad audience.

[N/A] for measurable effectiveness, efficiency, satisfaction criteria, and avoidance of harm.

## 3.5 Logical database requirements
The product manages and stores two primary types of data: game statistics and game state.

### a) Types of Information Used

*   **Player Statistics:**
    *   Player name (up to 20 characters).
    *   Number of block movements for a completed game.
    *   Time taken to solve the headache for a completed game.
*   **Game State:**
    *   Current positions of all blocks on the board.
    *   Last 10,000 previous positions of blocks (for undo/redo functionality).
    *   Current number of movements made in the ongoing game.
    *   Current time passed in the ongoing game.

### b) Frequency of Use

*   **Player Statistics:**
    *   Recorded at the end of a game if the player achieves a score worthy of inclusion in the top 10.
    *   Read and displayed when the "Statistic Window" is opened (either at game end or via menu selection).
    *   Erased on user request via the "Erase" menu option.
*   **Game State:**
    *   Saved on user request via "Save Game" or "Save Game As" menu options.
    *   Loaded on user request via the "Open game" menu option.

### c) Accessing Capabilities

*   The system must be able to read from and write to a designated "statistic file" for managing player statistics.
*   The system must be able to read from and write to user-selected files for saving and loading game states.

### d) Data Entities and Their Relationships

*   **Player Statistic Entity:** Consists of a player's name, their block movement count, and their game completion time.
*   **Game Statistics Collection:** A collection of up to 10 Player Statistic entities, stored in a single statistic file.
*   **Game State Entity:** Represents the complete state of an ongoing game, including current block positions, historical block positions, movement count, and elapsed time. Each saved game corresponds to one Game State entity stored in a file.

### e) Integrity Constraints

*   **Game Statistics File:**
    *   Must maintain a maximum of 10 Player Statistic entries.
    *   When a new Player Statistic is to be recorded and the file is full, the existing Player Statistic with the greatest number of block movements (i.e., the worst score) must be replaced by the new one if the new score is better.
*   **Undo/Redo History:** The system must store the last 10,000 previous block positions to support undo/redo actions.

### f) Security

[N/A]

### g) Data Retention Requirements

*   **Player Statistics:** Retained in the statistic file until explicitly erased by the user or replaced by a new, better score when the file is full.
*   **Game State:** Saved game files are retained indefinitely until deleted by the user through the operating system's file management. The application prompts the user to save an unsaved game before exiting.

## 3.6 Design constraints
The product must use the Qt graphical library.
The product must run with all operating systems that Qt supports.
The hardware and operating system must provide an 800x600 screen resolution.
The software must be portable to the Windows OS.

## 3.7 Software system attributes
The software must be portable to the Windows OS. It must also run with all operating systems that the Qt graphical library supports.

## 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
The portability of the software to the Windows OS will be verified by installing and executing the application on a Windows operating system. All functional requirements will be tested on the Windows environment to ensure correct operation.

# 5 Appendices
[NULL]

## 5.1 Assumptions and dependencies
*   The target operating environment will provide a graphical display with a resolution of at least 800x600 pixels, and standard input devices such as a keyboard and a mouse.
*   The operating system on which the product runs will be one that is supported by the Qt graphical library.
*   The operating environment will provide a file system with adequate storage space and appropriate write permissions for the application to store game statistics and saved games.

## 5.2 Acronyms and abbreviations
*   **OS**: Operating System
*   **SRS**: Software Requirements Specification
