PythonApplicationTemplate/README.md

# 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!** 🚀