## 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 specified in this document is named Qheadache. It is a computerized game that provides an interactive interface for users to solve a specific puzzle. The application's objective is to offer an engaging puzzle-solving experience for players.

### 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 will perform the following major functions:
*   Allow users to undo and redo their last thousand actions.
*   Track and display the time a user spends playing the game.
*   Count and display the total number of actions performed by the user during a play session.
*   Record the score (based on time and action count) for a play session, associated with a user's name.
*   Display a window showing all recorded player scores.
*   Manage game progression, including block selection, movement, and determining the end of the game.
*   Handle game statistics, including player-specific and overall game statistics, and allow for their display and erasure.
*   Provide file management capabilities, such as opening previously saved games, saving the current game, and saving the game under a new name.
*   Offer a menu bar with options for game control, actions (undo/redo), statistics management, and help information.

### 1.3.3 User characteristics
The intended users are anyone who wants to play a simple game and knows how to operate a computer. No specific qualifications or technical expertise are necessary. The user base ranges from beginning level players, starting at age 8, up through advanced level adult players.

### 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.1 Functions

### 3.1.1 Game Actions

#### 3.1.1.1 Board Presentation
The game board is a rectangular zone where blocks can be moved.
The board has a height of 5x and a width of 4x, where 'x' is a unit of measure. 'x' must be between 50 and 100 pixels, inclusive.
Blocks are separated by a margin of 0.1x.
The board contains:
*   Four square blocks with a side of x.
*   Four rectangular blocks with a height of 2x and a width of x.
*   One rectangular block with a height of x and a width of 2x.
*   One square block with a side of 2x.
The board is black, and the blocks are yellow.

#### 3.1.1.2 Block Selection
*   **Input:** A left-click down event on a block.
*   **Processing:** The game state transitions to "Block deplacement".
*   **Output:** None.

#### 3.1.1.3 Block Deselection
*   **Input:** A left-click up event on a selected block.
*   **Processing:** The game state transitions to "Block selection".
*   **Output:** None.

#### 3.1.1.4 Block Movement
*   **Input:** Mouse movement while the game is in the "Block movement" state.
*   **Processing:** The selected block follows the mouse movement. The movement is constrained such that the block:
    *   Does not overlap other blocks.
    *   Does not exit the game zone.
    *   Maintains a minimum distance of 0.05x from other blocks.
*   **Output:** None.

#### 3.1.1.5 Undo Action
This function allows the user to cancel the last performed movement.
*   **Input:** Selection of "Undo" from the Action menu. This option is unavailable if no previous movement has occurred.
*   **Processing:** The game displays the block positions as they were before the last movement. This action itself is considered a movement for the purpose of subsequent undo/redo operations.
*   **Output:** The game board is redrawn to reflect the previous block positions.

#### 3.1.1.6 Redo Action
This function allows the user to re-apply a movement that was previously canceled by an "Undo" action.
*   **Input:** Selection of "Redo" from the Action menu. This option is unavailable if the immediately preceding action was not an "Undo" action.
*   **Processing:** The game displays the block positions as they were before the last movement was canceled. This action itself is considered a movement for the purpose of subsequent undo/redo operations.
*   **Output:** The game board is redrawn to reflect the re-applied block positions.

### 3.1.2 Game End Management

#### 3.1.2.1 Game Completion
*   **Input:** The great square block is moved to the bottom of the board.
*   **Processing:** All current player statistics (number of block movements, time passed) are frozen.
*   **Output:**
    *   If the current player's number of block movements is lower than the highest number of block movements recorded in the statistics file, the "Finish Window with Statistics" (see 3.1.2.2) is displayed.
    *   Otherwise, the "Simple Finish Window" (see 3.1.2.3) is displayed.

#### 3.1.2.2 Finish Window with Statistics
This window is displayed upon game completion when the player achieves a score worthy of recording.
*   **Description:** The window contains the text "You win ! Enter your name : ", an editable text box capable of holding up to 20 characters, and a pushbutton labeled "OK".
*   **Input:** The game is over (as per 3.1.2.1), and the player clicks the "OK" pushbutton after optionally entering a name.
*   **Processing:** The player's statistics (name, block movement number, time passed) are recorded in the software's statistic file, as described in 3.1.3.2.
*   **Output:** The "Finish Window with Statistics" is closed, and the "Statistic Window" (see 3.1.3.4) is displayed.

#### 3.1.2.3 Simple Finish Window
This window is displayed upon game completion when the player does not achieve a score worthy of recording.
*   **Description:** The window contains the text "You win !" and a pushbutton labeled "OK".
*   **Input:** The game is over (as per 3.1.2.1), and the player clicks the "OK" pushbutton.
*   **Processing:** [N/A]
*   **Output:** The "Simple Finish Window" is closed, and the "Statistic Window" (see 3.1.3.4) is displayed.

### 3.1.3 Statistics Management

#### 3.1.3.1 Player Statistics Tracking
*   **Description:** The system continuously records the following statistics during gameplay:
    *   Number of block movements since the start of the game.
    *   Time elapsed since the start of the game.
*   **Input:** A block movement occurs.
*   **Processing:** The number of block movements is incremented by 1. The difference of time between the current block movement and the previous recorded time is recorded.
*   **Output:** None.

#### 3.1.3.2 Game Statistics Recording
This function manages the persistent storage of player scores.
*   **Description:** The game statistics file stores up to 10 player statistics entries.
*   **Input:** The "Finish Window with Statistics" is completed by the player (see 3.1.2.2).
*   **Processing:** The player's statistics (name, block movement number, time passed to solve the headache) are recorded in the statistic file. If 10 player statistics are already recorded, the entry with the greatest number of block movements is erased to make space for the new entry.
*   **Output:**
    *   None, if the file is correctly updated.
    *   An error message is displayed if issues such as wrong permissions or disk full prevent the file from being updated.

#### 3.1.3.3 Statistics Erasing
This function allows the user to clear all recorded game statistics.
*   **Input:** Selection of "Erase" from the Statistics menu.
*   **Processing:** All data stored in the statistic file are erased.
*   **Output:**
    *   None, if the file is correctly updated.
    *   An error message is displayed if issues such as wrong permissions or disk full prevent the file from being updated.

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

### 3.1.4 Game File Management

#### 3.1.4.1 Open Game
This function allows the user to load a previously saved game state.
*   **Input:** Selection of "Open game ..." from the Game menu.
*   **Processing:** A dialog box is opened, allowing the user to choose a file containing previously saved game data.
*   **Output:** The game board is redrawn according to the data from the selected file. The player statistics (movements, time) are reset to the values stored in the file.

#### 3.1.4.2 Save Game
This function allows the user to save the current game state.
*   **Input:** Selection of "Save Game ..." from the Game menu.
*   **Processing:**
    *   If the game has never been saved before, the processing is identical to the "Save game as" action (see 3.1.4.3).
    *   Otherwise, the following internal data are saved into the file that was previously used to save the game: the current positions of the blocks, their last 10000 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
This function allows the user to save the current game state to a new or specified file.
*   **Input:** Selection of "Save Game As..." 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. The following internal data are then saved into the chosen 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 Game
This function allows the user to terminate the game application.
*   **Input:** Selection of "Exit" from the Game menu.
*   **Processing:** If the current game state has unsaved changes, 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 Game" action (see 3.1.4.2) is processed, and then the main window disappears.
    *   If "No" is selected, the main window disappears without saving.
*   **Output:** None.

### 3.1.5 Menu Bar Functions

#### 3.1.5.1 Game Menu
*   **Description:** This menu contains the following options, in order: "Open game ...", "Save Game ...", "Save Game As...", and "Exit".
*   **Input:** Selection of an option from the Game menu.
*   **Processing:** The corresponding action is performed:
    *   "Open game ..." triggers the "Open Game" function (see 3.1.4.1).
    *   "Save Game ..." triggers the "Save Game" function (see 3.1.4.2).
    *   "Save Game As ..." triggers the "Save Game As" function (see 3.1.4.3).
    *   "Exit" triggers the "Exit Game" function (see 3.1.4.4).
*   **Output:** The menu disappears. Further outputs are determined by the triggered action.

#### 3.1.5.2 Action Menu
*   **Description:** This menu contains the following options, in order: "Undo" and "Redo". Menu options are unavailable if their associated action is currently unavailable.
*   **Input:** Selection of an option from the Action menu.
*   **Processing:** The corresponding action is performed:
    *   "Undo" triggers the "Undo Action" function (see 3.1.1.5).
    *   "Redo" triggers the "Redo Action" function (see 3.1.1.6).
*   **Output:** The menu disappears. Further outputs are determined by the triggered action.

#### 3.1.5.3 Statistics Menu
*   **Description:** This menu contains the following options, in order: "Display" and "Erase".
*   **Input:** Selection of an option from the Statistics menu.
*   **Processing:** The corresponding action is performed:
    *   "Display" triggers the "Statistic Window Display" function (see 3.1.3.4).
    *   "Erase" triggers the "Statistics Erasing" function (see 3.1.3.3).
*   **Output:** The menu disappears. Further outputs are determined by the triggered action.

#### 3.1.5.4 Help Menu
*   **Description:** This menu contains the option: "About".
*   **Input:** Selection of "About" from the Help menu.
*   **Processing:** The "About Window" is displayed. This window contains the text "Qheadache 1.0 by Jean-Philippe Brossat jp_brossat@yahoo.fr".
*   **Output:** The menu disappears. The "About Window" is displayed.

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

## 3.3 Usability requirements
[N/A]

## 3.5 Logical database requirements

The product manages two primary types of persistent data: game statistics and saved game states. This data is stored in files on the local file system.

### a) Types of information used by various functions

*   **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.
    *   History of the last 10,000 previous block positions (for undo/redo functionality).
    *   Number of movements made in the current game.
    *   Time passed by the user in the current game.

### b) Frequency of use

*   **Player Statistics:**
    *   Recorded at the end of a game if the score qualifies for the top 10.
    *   Displayed in a dedicated statistics window upon game completion or menu selection.
    *   Erased via menu selection.
*   **Game State:**
    *   Saved to a file via menu selection ("Save Game", "Save Game As...").
    *   Loaded from a file via menu selection ("Open game...").
    *   Internal history of block positions is updated with every block movement and accessed for undo/redo actions.

### c) Accessing capabilities

*   The system can read from and write to a designated "statistic file" for managing player scores.
*   The system can read from and write to user-selected files for saving and loading game states.
*   The system provides a user interface to display the top 10 player statistics.
*   The system provides menu options for opening, saving, saving as, and erasing statistics.

### d) Data entities and their relationships

*   **Player Statistic:** An individual record comprising a player's name, block movement count, and time.
*   **Game Statistics:** A collection of up to 10 Player Statistics, where the player statistics with the greatest number of block movements can be replaced by a new, better score.
*   **Game State:** A single record representing the current progress of a game, including block positions, movement history, and elapsed time.

### e) Integrity constraints

*   **Game Statistics:**
    *   Limited to a maximum of 10 player statistics.
    *   When a new score is recorded, if the list is full, the existing statistic with the greatest number of block movements is replaced if the new score is better.
*   **Undo/Redo History:** The system maintains a history of the last 1,000 actions for undo/redo functionality. Saved game states include the last 10,000 previous positions.
*   **File Operations:** The system should handle potential errors during file operations (e.g., wrong permissions, disk full) by displaying an error message.

### f) Security

[N/A]

### g) Data retention requirements

*   **Game Statistics:** Persistently stored in a "statistic file" until explicitly erased by the user or replaced by a new, qualifying score.
*   **Saved Games:** Persistently stored in user-specified files until explicitly deleted by the user through the operating system.
*   **Undo/Redo History:** Maintained within the current game session for the last 1,000 actions, and up to 10,000 previous positions are saved as part of a game file.

## 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.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 software's portability to the Windows OS shall be verified by installing and executing the application on a Windows operating system.

## 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
*   SRS: Software Requirements Specification
*   OS: Operating System