QtGuidedUI is a lightweight interactive guide system built with PySide, but using Qt.py for extended Qt bindings support.

It allows developers to create guided tours of their applications by configuring a series of steps in a JSON file.

The guide highlights specific UI elements, displays helpful tooltips with images and descriptions, and manages navigation through the guide steps.

• Configurable Steps: Define steps in a JSON configuration file with descriptions, images, and pre-actions.
• Widget Highlighting: Visually highlight UI elements to draw user attention.
• Interactive Dialogs: Display tooltips and dialogs with navigation controls (Next, Skip).
• Dynamic Positioning: Automatically calculate dialog positions relative to highlighted widgets.
• Pre-Action Support: Execute pre-defined actions before displaying each step.

• Python 3.7+

Install requirements using pip:

• Qt.py 1.4.1+

pip install -r requirements.txt

Create a JSON configuration file for your guide. An example configuration (guide_config.json) might look like this:

{
  "intro_message": "Welcome to the interactive guide!",
  "outro_message": "You have completed the guide.",
  "dialog_image_width": 300,
  "steps": [
    {
      "order": 1,
      "object_name": "startButton",
      "description": "Click this button to begin.",
      "image": "start_button.png",
      "pre_action": "prepare_start"
    },
    {
      "order": 2,
      "object_name": "settingsButton",
      "description": "Access settings here.",
      "image": "settings.gif"
    }
  ]
}

• intro_message: Message displayed at the beginning of the guide.
• outro_message: Message displayed after the guide is completed.
• steps: An array of guide steps where:
  • order defines the sequence.
  • object_name is the name of the widget to highlight.
  • description is the tooltip text.
  • image (optional) is the image (or GIF) to show. Path is relative to the guide_config.json file.
  • pre_action (optional) is the name of a method on the parent widget to call before the step is shown.

Integrate the guided UI into your application by instantiating the GuidedUI widget and calling start_guide().

Example:

import sys
from Qt.QtWidgets import QApplication
from QtGuidedUI import GuidedUI  # Adjust the import according to your project structure

if __name__ == "__main__":
    app = QApplication(sys.argv)
    # Pass the path to your JSON configuration file.
    guide = GuidedUI("path/to/guide_config.json")
    guide.start_guide()
    guide.show()  # Display the main UI if necessary
    sys.exit(app.exec())

A complete and more realistic example is available in the sample folder:

sample/sample.py

• Logo: Next step icons created by Danteee82 - Flaticon

• Example image sample.png:

  • WebArtDevelopers BIG FANCY 3D ROTATING SVG BUTTON

• Example gif sample.gif:

  • WebArtDevelopers UI/UX EXAMPLE: TAB SWITCH ANIMATION

This project is licensed under the MIT License.

See the LICENSE file for details.