# Python PyQt6 Application Template A modern, feature-rich template for building desktop applications with PyQt6. This template provides a solid foundation with theming, internationalization, settings management, and a modular architecture. ## Features - **Modern UI Framework**: Built with PyQt6 for cross-platform compatibility - **Theme System**: Dark and light themes with easy customization - **Internationalization**: Multi-language support (English and French included) - **Settings Management**: Persistent user preferences with QSettings - **Modular Architecture**: Clean separation of concerns with managers and observers - **Tabbed Interface**: Flexible tab widget system with customizable positioning - **Window State Management**: Remembers window size, position, and maximized state - **Email Integration**: Built-in suggestion/feedback system with secure email configuration - **Build Automation**: Automated building with PyInstaller - **Virtual Environment Management**: Automated environment setup ## Project Structure ``` Template/ ├── app/ │ ├── core/ # Core application managers │ │ ├── main_manager.py # Singleton manager coordinator │ │ ├── settings_manager.py # User settings and configuration │ │ ├── theme_manager.py # Theme and styling management │ │ ├── language_manager.py # Internationalization │ │ └── observer_manager.py # Event notification system │ ├── ui/ │ │ ├── main_window.py # Main application window │ │ ├── widgets/ # Custom widgets │ │ │ └── tabs_widget.py # Customizable tab system │ │ └── windows/ # Application windows │ │ ├── settings_window.py │ │ └── suggestion_window.py │ └── utils/ │ └── paths.py # Path utilities for resources ├── data/ │ ├── assets/ # Icons and images │ ├── lang/ # Language files (JSON) │ ├── themes/ # Theme configuration files │ └── others/ # Default settings ├── tools/ # Build and development tools │ ├── build.bat/.sh/.command # Platform-specific build script │ └── open.bat/.sh/.command # Platform-specific development setup ├── config.json # Application configuration ├── requirements.txt # Python dependencies ├── BUILD.spec # PyInstaller specification └── main.py # Application entry point ``` ### Development Setup 1. **Clone/Download** this template 2. **Configure** your application in `config.json`: ```json { "app_name": "YourAppName", "python_version": "YourPythonVersion", "app_os": "Windows or Linux or Mac", "app_version": "YourAppVersion", "architecture": "x64 or x32", "icon_path": "data/assets/icon.ico", "main_script": "main.py" } ``` 3. **Setup environment configuration**: - Copy `.env.example` to `.env` - Configure your Python path and email credentials: ```env # Python Configuration PYTHON_PATH=C:/Path/To/Your/Python/python.exe # Email Configuration (optional) EMAIL_ADDRESS=your_email@gmail.com EMAIL_PASSWORD=your_app_password EMAIL_SMTP_SERVER=smtp.gmail.com EMAIL_SMTP_PORT=587 ``` - For Gmail, use an [App Password](https://support.google.com/accounts/answer/185833) instead of your regular password 4. **Run development environment**: - **Windows**: `tools\open.bat` - **Linux**: `tools/open.sh` - **macOS**: `tools/open.command` This will: - Create a virtual environment - Install dependencies - Open VS Code with proper environment ### Building for Production - **Windows**: `tools\build.bat` - **Linux**: `tools/build.sh` - **macOS**: `tools/build.command` This creates a standalone executable in the `build/` directory. ### Adding Themes Create JSON files in `data/themes/`. **Important**: Use the predefined color names as they are used throughout the application's styling system. ```json { "theme_name": "custom", "colors": { "background": "#FFFFFF", // Main background color "background2": "#F5F5F5", // Secondary background "background3": "#E0E0E0", // Tertiary background "font_color": "#000000", // Text color "selected_icon": "#000000", // Selected icon color "unselected_icon": "#5D5A5A", // Unselected icon color "selected_border_icon": "#000000", // Selected border color "hover_icon": "#000000" // Hover state color } } ``` **Warning**: Do not change the color property names (`background`, `background2`, etc.) as they are hardcoded in the theme system. Only modify the hex color values. ### Adding Languages Create JSON files in `data/lang/`. **Important**: Use the existing translation keys to ensure proper functionality. ```json { "lang_name": "Español", "yes": "Sí", "no": "No", "language": "Idioma:", "settings": "Configuración", "theme": "Tema:", "dark_theme": "Tema Oscuro", "light_theme": "Tema Claro", "suggestion_text": "¿Tienes una pregunta o idea para mejorar esta aplicación?", "suggestion_placeholder": "Escribe tu mensaje aquí...", "send_suggestion": "Enviar", "sending": "Enviando...", "success": "Éxito", "error": "Error", "suggestion_sent_success": "¡Tu mensaje ha sido enviado exitosamente!", "suggestion_send_error": "Error al enviar el mensaje. Inténtalo de nuevo más tarde.", "email_credentials_error": "Credenciales de email no configuradas. Por favor configura tu email y contraseña en el archivo .env." } ``` **Warning**: Do not change the translation keys (left side of the colon) as they are used throughout the application code. Only translate the values (right side). ## Architecture ### Manager Pattern The application uses a centralized manager system: - **MainManager**: Singleton coordinator for all managers - **SettingsManager**: Handles user preferences and persistence - **ThemeManager**: Manages themes and styling - **LanguageManager**: Handles internationalization - **ObserverManager**: Event notification system ### Observer Pattern Components can subscribe to events: ```python self.observer_manager.subscribe(NotificationType.THEME, self.update_theme) self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language) ``` ### Tab System The flexible tab widget supports multiple positioning options: ```python # Add a tab with custom positioning self.side_menu.add_widget( widget=your_widget, button_text="", icon_path=paths.get_asset_svg_path("icon_name"), position=ButtonPosition.CENTER ) ``` ## Email Integration The template includes a suggestion system with email capabilities. Configure in your `.env` file: **Security Note**: Never commit your `.env` file to version control. It's already included in `.gitignore`. For Gmail users: - Enable 2-factor authentication - Generate an App Password specifically for this application - Use the App Password in the `EMAIL_PASSWORD` field ## Customization ### Adding New Windows 1. Create window class inheriting from `QWidget` 2. Subscribe to language notifications 3. Add to main window tab system ```python class YourWindow(QWidget): def __init__(self, parent=None): super().__init__(parent) self.main_manager = MainManager.get_instance() # Subscribe to notifications self.observer_manager.subscribe(NotificationType.LANGUAGE, self.update_language) self.setup_ui() ``` ### Custom Widgets Place custom widgets in `app/ui/widgets/` and follow the existing patterns for theme integration. ## Dependencies - **PyQt6**: Modern GUI framework - **pyinstaller**: Executable building - **python-dotenv**: Environment variable management Add additional dependencies to `requirements.txt`. ## Building The build system automatically: - Creates virtual environments per architecture - Installs dependencies - Builds with PyInstaller - Names executables with config.json - Includes all assets and data files ## Cross-Platform Notes The template supports multiple platforms with platform-specific scripts: - **Windows**: Uses `.bat` files - **Linux**: Uses `.sh` files - **macOS**: Uses `.command` files Adjust config.json for your target platform. ## License MIT License - see LICENSE file for details. ## Contributing 1. Fork the repository 2. Create a feature branch 3. Make your changes 4. Test thoroughly 5. Submit a pull request ## Support For issues or questions: - Check existing issues - Create detailed bug reports - Include system information and error logs --- **Happy coding!** 🚀