{"id":26116569,"url":"https://github.com/shoaib-programmer/gridguru","last_synced_at":"2025-03-10T09:46:49.672Z","repository":{"id":273732161,"uuid":"920697358","full_name":"Shoaib-Programmer/GridGuru","owner":"Shoaib-Programmer","description":"A Sudoku Solver GUI in C","archived":false,"fork":false,"pushed_at":"2025-03-08T12:40:45.000Z","size":297,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-08T13:32:42.011Z","etag":null,"topics":["c","css","gtk","gtk-css","sudoku-solver"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shoaib-Programmer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-22T16:08:09.000Z","updated_at":"2025-03-08T12:40:48.000Z","dependencies_parsed_at":"2025-03-08T13:39:36.452Z","dependency_job_id":null,"html_url":"https://github.com/Shoaib-Programmer/GridGuru","commit_stats":null,"previous_names":["shoaib-programmer/gridguru"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shoaib-Programmer%2FGridGuru","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shoaib-Programmer%2FGridGuru/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shoaib-Programmer%2FGridGuru/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shoaib-Programmer%2FGridGuru/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shoaib-Programmer","download_url":"https://codeload.github.com/Shoaib-Programmer/GridGuru/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242828106,"owners_count":20191993,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["c","css","gtk","gtk-css","sudoku-solver"],"created_at":"2025-03-10T09:46:48.749Z","updated_at":"2025-03-10T09:46:49.641Z","avatar_url":"https://github.com/Shoaib-Programmer.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n---\n\n# Grid Guru: A Sudoku Solver with GTK GUI  \n**Grid Guru** is a feature-complete Sudoku puzzle solver implemented in C with a GTK-based graphical interface. Designed for both enthusiasts and developers, it combines algorithmic problem-solving with intuitive user interaction. This project emphasizes code clarity, efficient backtracking, and robust error handling while demonstrating practical GUI development in C.\n\n---\n\n## Table of Contents  \n1. [Project Overview](#project-overview)  \n2. [Key Features](#key-features)  \n3. [Installation](#installation)  \n4. [File Structure \u0026 Implementation](#file-structure--implementation)  \n5. [Design Choices \u0026 Rationale](#design-choices--rationale)  \n6. [Usage Guide](#usage-guide)  \n7. [Screenshots](#screenshots)  \n8. [Future Improvements](#future-improvements)  \n9. [Acknowledgments](#acknowledgments)  \n10. [License](#license)  \n\n---\n\n## Project Overview  \nGrid Guru solves Sudoku puzzles using a backtracking algorithm, rendered through a GTK 3 GUI. Users can input puzzles, validate their correctness, solve them, and reset or revert changes. The project serves as a case study in:  \n- **Algorithm Design**: Efficient backtracking for constraint satisfaction problems.  \n- **GUI Development**: GTK widget management, event handling, and state synchronization.  \n- **Software Engineering**: Modular code structure, error handling, and build automation.  \n\n---\n\n## Key Features  \n- **Interactive GTK Interface**:  \n  - Input cells with validation (digits 1–9 or empty).  \n  - Visual feedback for invalid configurations.  \n- **Backtracking Solver**: Recursive algorithm to find valid solutions.  \n- **State Management**:  \n  - **Solve**: Computes and displays the solution.  \n  - **Reset**: Clears the grid to zeros.  \n  - **Back**: Reverts to the user’s original input post-solution.  \n- **Input Sanitization**: Rejects non-digit characters and out-of-range values.  \n\n---\n\n## Installation  \n### Dependencies  \n- **GTK 3**: GUI framework.  \n- **GCC**: C compiler.  \n- **Make**: Build automation.  \n\n### Steps  \n```bash\n# Debian/Ubuntu\nsudo apt install build-essential libgtk-3-dev\n\n# macOS (Homebrew)\nbrew install gtk+3\n\n# Clone \u0026 Build\ngit clone https://github.com/Shoaib-Programmer/GridGuru.git\ncd GridGuru\nmake        # Compile\n./sudoku_solver # Run\n```\n\n---\n\n## File Structure \u0026 Implementation  \n### `src/main.c`  \n- **Purpose**: GTK GUI setup and event handling.  \n- **Key Components**:  \n  - `create_main_window()`: Initializes the 9x9 grid of `GtkEntry` widgets with stylistic subgrid separators.  \n  - `on_solve_button_clicked()`: Validates the puzzle, triggers the solver, and updates the UI.  \n  - **State Management**: Toggles button visibility (Solve/Back) and syncs the grid with `initial_grid`.  \n\n### `src/sudoku.c`  \n- **Purpose**: Core Sudoku logic.  \n- **Functions**:  \n  - `isValid()`: Checks row, column, and 3x3 subgrid constraints.  \n  - `solveSudoku()`: Recursive backtracking implementation.  \n- **Algorithm**: Prioritizes empty cells dynamically (no fixed order) for efficiency.  \n\n### `src/sudoku.h`  \n- Header file declaring function prototypes (`isValid`, `solveSudoku`) and constants (`SIZE=9`).  \n\n### `Makefile`  \n- **Build Automation**: Compiles `main.c` and `sudoku.c` into `grid_guru`.  \n- **Targets**:  \n  - `all`: Default build.  \n  - `clean`: Remove binaries.  \n  - `run`: Compile and execute.  \n\n### `resources/`  \n- Directory for screenshots demonstrating UI states:  \n  - `initial-state.png`: Default puzzle.  \n  - `solved-state.png`: Post-solution.  \n  - `invalid-state.png`: Error feedback.  \n  - `nosolution-state.png`: No solution exists.\n\n---\n\n## Design Choices \u0026 Rationale  \n### 1. **GTK for GUI**  \n- **Why GTK?**  \n  - **Native Performance**: Lightweight compared to Electron or web-based tools.  \n  - **C Compatibility**: Direct integration without language bindings.  \n- **Tradeoff**: Steeper learning curve vs. simplicity of terminal-only solvers.  \n\n### 2. **Backtracking Algorithm**  \n- **Choice**: Classic recursive backtracking.  \n- **Rationale**:  \n  - **Simplicity**: Easy to implement and debug for a 9x9 grid.  \n  - **Adequate Performance**: Solves most puzzles in \u003c1ms.  \n- **Limitation**: Not optimized for \"hard\" Sudokus with sparse initial clues.  \n\n### 3. **Grid State Management**  \n- **`initial_grid` Array**: Stores the user’s initial input to enable the \"Back\" functionality.  \n- **Why Global State?** Simplifies callback handling in GTK without passing structs.  \n\n### 4. **Input Validation**  \n- **Sanitization**: In `get_grid_from_entries()`, invalid characters are coerced to `0`.  \n- **Pre-Solve Check**: `isValid()` ensures no duplicates before invoking the solver.  \n\n---\n\n## Usage Guide  \n1. **Launch**: Run `./grid_guru` to load the default puzzle.  \n2. **Input**: Click cells and type numbers (1–9). Leave empty for unknowns.  \n3. **Solve**: Click \"Solve\" to compute the solution (if valid).  \n4. **Reset**: \"Reset\" clears all cells.  \n5. **Back**: After solving, \"Back\" restores your original input.  \n\n---\n\n## Screenshots  \n| Initial Puzzle | Solved State | Invalid Input | No Solution |  \n|----------------|--------------|---------------|-------------|  \n| ![Initial](resources/screenshots/initial-state.png) | ![Solved](resources/screenshots/solved-state.png) | ![Invalid](resources/screenshots/invalid-state.png) | ![No Solution](resources/screenshots/nosolution-state.png) |  \n\n---\n\n\u003c!-- ## Future Improvements  \n1. **Optimized Solvers**: Implement Dancing Links (Algorithm X) for harder puzzles.  \n2. **Puzzle Generator**: Create random valid Sudokus of varying difficulty.  \n3. **Undo/Redo**: Enhance user experience with action history.  \n\n--- --\u003e\n\n## Acknowledgments  \n- **GTK Team**: For maintaining the GUI framework.  \n- **Classic Sudoku Literature**: Inspired the backtracking approach.  \n\n---\n\n## License  \nMIT License. See [LICENSE](LICENSE) for details.\n\n--- \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoaib-programmer%2Fgridguru","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshoaib-programmer%2Fgridguru","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshoaib-programmer%2Fgridguru/lists"}