{"id":26591576,"url":"https://github.com/hasielhassan/qtguidedui","last_synced_at":"2026-04-16T18:02:23.837Z","repository":{"id":283057201,"uuid":"950536693","full_name":"hasielhassan/QtGuidedUI","owner":"hasielhassan","description":"A lightweight interactive UI guide system built with PySide","archived":false,"fork":false,"pushed_at":"2025-03-18T10:17:09.000Z","size":286,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-18T11:30:04.534Z","etag":null,"topics":["gui","guide","pyside","python","qt","ui","ux","widget"],"latest_commit_sha":null,"homepage":"","language":"Python","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/hasielhassan.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-03-18T10:10:48.000Z","updated_at":"2025-03-18T10:16:53.000Z","dependencies_parsed_at":"2025-03-18T11:30:11.461Z","dependency_job_id":null,"html_url":"https://github.com/hasielhassan/QtGuidedUI","commit_stats":null,"previous_names":["hasielhassan/qtguidedui"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasielhassan%2FQtGuidedUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasielhassan%2FQtGuidedUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasielhassan%2FQtGuidedUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hasielhassan%2FQtGuidedUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hasielhassan","download_url":"https://codeload.github.com/hasielhassan/QtGuidedUI/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245111880,"owners_count":20562511,"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":["gui","guide","pyside","python","qt","ui","ux","widget"],"created_at":"2025-03-23T14:18:38.865Z","updated_at":"2026-04-16T18:02:18.792Z","avatar_url":"https://github.com/hasielhassan.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"icon_256.png\" width=\"128\"/\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eQtGuidedUI\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"GitHub top language\" src=\"https://img.shields.io/github/languages/top/hasielhassan/QtGuidedUI\" /\u003e\n    \u003cimg alt=\"GitHub last commit\" src=\"https://img.shields.io/github/last-commit/hasielhassan/QtGuidedUI\" /\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/hasielhassan/QtGuidedUI\" /\u003e\n    \u003cimg alt=\"GitHub release (latest by date)\" src=\"https://img.shields.io/github/v/release/hasielhassan/QtGuidedUI\" /\u003e\n    \u003cimg alt=\"GitHub release downloads\" src=\"https://img.shields.io/github/downloads/hasielhassan/QtGuidedUI/total\" /\u003e\n    \u003cimg alt=\"GitHub release downloads\" src=\"https://img.shields.io/badge/Python Versions-3.7 / 3.9 / 3.11-blue\" /\u003e\n\n\u003c/p\u003e\n\n![Demo](/sample/screenrecording.gif)\n\nQtGuidedUI is a lightweight interactive guide system built with [PySide](https://wiki.qt.io/Qt_for_Python), but using [Qt.py](https://github.com/mottosso/Qt.py) for extended Qt bindings support. \n\nIt allows developers to create guided tours of their applications by configuring a series of steps in a JSON file. \n\nThe guide highlights specific UI elements, displays helpful tooltips with images and descriptions, and manages navigation through the guide steps.\n\n## Features\n\n- **Configurable Steps:** Define steps in a JSON configuration file with descriptions, images, and pre-actions.\n- **Widget Highlighting:** Visually highlight UI elements to draw user attention.\n- **Interactive Dialogs:** Display tooltips and dialogs with navigation controls (Next, Skip).\n- **Dynamic Positioning:** Automatically calculate dialog positions relative to highlighted widgets.\n- **Pre-Action Support:** Execute pre-defined actions before displaying each step.\n\n## Getting Started\n\n### Prerequisites\n\n- **Python 3.7+**\n\nInstall requirements using pip:\n- **Qt.py 1.4.1+** \n\n```bash\npip install -r requirements.txt\n```\n\n### Configuration\n\nCreate a JSON configuration file for your guide. An example configuration (`guide_config.json`) might look like this:\n\n```json\n{\n  \"intro_message\": \"Welcome to the interactive guide!\",\n  \"outro_message\": \"You have completed the guide.\",\n  \"dialog_image_width\": 300,\n  \"steps\": [\n    {\n      \"order\": 1,\n      \"object_name\": \"startButton\",\n      \"description\": \"Click this button to begin.\",\n      \"image\": \"start_button.png\",\n      \"pre_action\": \"prepare_start\"\n    },\n    {\n      \"order\": 2,\n      \"object_name\": \"settingsButton\",\n      \"description\": \"Access settings here.\",\n      \"image\": \"settings.gif\"\n    }\n  ]\n}\n```\n\n- **intro_message:** Message displayed at the beginning of the guide.\n- **outro_message:** Message displayed after the guide is completed.\n- **steps:** An array of guide steps where:\n  - `order` defines the sequence.\n  - `object_name` is the name of the widget to highlight.\n  - `description` is the tooltip text.\n  - `image` (optional) is the image (or GIF) to show.\n    Path is relative to the `guide_config.json` file.\n  - `pre_action` (optional) is the name of a method on the parent widget to call before the step is shown.\n\n## Usage\n\nIntegrate the guided UI into your application by instantiating the `GuidedUI` widget and calling `start_guide()`.\n\nExample:\n\n```python\nimport sys\nfrom Qt.QtWidgets import QApplication\nfrom QtGuidedUI import GuidedUI  # Adjust the import according to your project structure\n\nif __name__ == \"__main__\":\n    app = QApplication(sys.argv)\n    # Pass the path to your JSON configuration file.\n    guide = GuidedUI(\"path/to/guide_config.json\")\n    guide.start_guide()\n    guide.show()  # Display the main UI if necessary\n    sys.exit(app.exec())\n```\n\nA complete and more realistic example is available in the sample folder:\n\n[sample/sample.py](sample/sample.py)\n\n## Attributions\n\n- Logo: [Next step icons created by Danteee82 - Flaticon](https://www.flaticon.com/free-icon/ecommerce_8602327)\n\n- Example image [sample.png](sample/images/sample.png):\n  - [WebArtDevelopers BIG FANCY 3D ROTATING SVG BUTTON](https://webartdevelopers.com/blog/big-fancy-3d-rotating-svg-button-2/)\n- Example gif [sample.gif](sample/images/sample.gif):\n  - [WebArtDevelopers UI/UX EXAMPLE: TAB SWITCH ANIMATION](https://webartdevelopers.com/blog/ui-ux-example-tab-switch-animation/)\n\n## License\n\nThis project is licensed under the MIT License. \n\nSee the [LICENSE](LICENSE) file for details.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasielhassan%2Fqtguidedui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhasielhassan%2Fqtguidedui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhasielhassan%2Fqtguidedui/lists"}