Sdk_TV_app/GTK_WRAPPER_README.md

GTK Wrapper for Flask Application

This wrapper embeds your Flask web application in a native GTK window using WebKit2, providing a desktop application experience.

Installation

Prerequisites

• Python 3.6+
• GTK 3.0
• WebKit2 4.0
• PyGObject

Automatic Setup (Linux)

Run the provided setup script:

bash setup_gtk_wrapper.sh

This will install all required system packages and Python dependencies.

Manual Setup

If the automated script doesn't work for your system, install the packages manually:

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y python3-gi gir1.2-gtk-3.0 gir1.2-webkit2-4.1 libgtk-3-0 libwebkit2gtk-4.1-0
pip3 install flask

Fedora/RHEL:

sudo dnf install python3-gobject gtk3 webkit2-gtk3
pip3 install flask

Arch Linux:

sudo pacman -S python-gobject gtk3 webkit2gtk
pip3 install flask

macOS (via Homebrew):

brew install gtk+3 webkit2gtk python3
pip3 install flask

Usage

Run the GTK wrapper with:

python3 gtk_wrapper.py

Or make it executable and run directly:

chmod +x gtk_wrapper.py
./gtk_wrapper.py

Features

• Native GTK Window: Runs your Flask app in a native GTK 3 window
• WebKit2 Rendering: Uses WebKit2 for modern web rendering
• Background Flask Server: Automatically starts your Flask app in a background thread
• Developer Mode: Developer tools are enabled for debugging (inspect element)
• Responsive UI: Window is resizable and responsive

Configuration

You can customize the wrapper by editing gtk_wrapper.py:

Window Size

self.set_default_size(1200, 800)  # Change to desired width, height

Window Title

self.set_title('Your App Title')

Flask Server Port

self.flask_port = 5000  # Change to desired port

Developer Tools

To disable developer tools (inspect element), comment out:

self.webview.get_settings().set_property('enable-developer-extras', True)

Troubleshooting

"No module named 'gi'"

Install PyGObject: pip3 install PyGObject

"gi.repository.Gtk" not found

Install GTK bindings: sudo apt-get install python3-gi gir1.2-gtk-3.0

"gi.repository.WebKit2" not found

Install WebKit2 bindings: sudo apt-get install gir1.2-webkit2-4.0

Flask server won't start

• Check if port 5000 is already in use
• Ensure you're running from the correct directory
• Check Flask app for syntax errors

Page shows "Unable to reach" error

• Wait a few seconds for the Flask server to start
• Check the terminal for Flask startup messages
• Ensure all Flask dependencies are installed

File Structure

TV_APP_V1.0.0/
├── app.py                    # Your Flask application
├── gtk_wrapper.py            # GTK wrapper (this file)
├── setup_gtk_wrapper.sh      # Automated setup script
├── GTK_WRAPPER_README.md     # This file
├── templates/                # Flask templates
├── static/                   # Flask static files
└── locales/                  # Language files

Notes

• The Flask app runs in debug mode disabled to prevent auto-reloading conflicts with GTK
• The app uses threading to run Flask in the background without blocking GTK events
• All Flask features (routing, sessions, file uploads, etc.) work normally

Support

For issues with the Flask app itself, see the main app documentation. For GTK/WebKit issues, refer to the respective project documentation.