diff options
| author | Warry <FunWarry@users.noreply.github.com> | 2025-11-30 15:37:32 +0100 |
|---|---|---|
| committer | Warry <FunWarry@users.noreply.github.com> | 2025-11-30 15:37:32 +0100 |
| commit | 121dbb788d051c76375261cd18fa8dca0f23b935 (patch) | |
| tree | cab3f2df3aa9e1437fdd0b5c60ab22780f8d717d /docs | |
| parent | 28a6fe5a7dbadc9532de228a539c47ec49ca4aa2 (diff) | |
| download | tidal-dl-ng-121dbb788d051c76375261cd18fa8dca0f23b935.tar.gz | |
feat: refactor settings UI with category navigation and add Delimiters page
Closes #640
## Changes
### UI Refactoring
- Replace monolithic settings dialog with category-based navigation
- Add QListWidget (lw_categories) for category selection on the left
- Add QStackedWidget (sw_categories) for content pages on the right
- Organize settings into 5 distinct pages:
- Flags (14 checkboxes)
- Quality (3 combo boxes)
- Numbers (2 spin boxes)
- Paths & Formats (7 line edits + 2 browse buttons)
- Delimiters (4 line edits) — NEW
### New Feature: Delimiters Category
- Add customizable separators for artists in metadata and filenames:
- metadata_delimiter_artist
- metadata_delimiter_album_artist
- filename_delimiter_artist
- filename_delimiter_album_artist
- Auto-integration with DialogPreferences via parameters_line_edit
- Line edits with max width 100px for compact display
### Styling
- Apply dark theme to settings dialog:
- Category list: #2b2b2b background, #3d5a80 selection, #3a3a3a hover
- Settings area: #333333 background, styled GroupBoxes (#3a3a3a)
- Light text (#e0e0e0) for better contrast
- Add spacing property (6px) to category list for better readability
- Style QListWidget items with padding (4px 3px) and margin (2px 0px)
### Testing
- Add comprehensive test suite (61 tests total):
- test_settings_ui.py: UI and basic integration (14 tests)
- test_settings_dialog_structure.py: detailed structure validation (20 tests)
- test_dialog_preferences_integration.py: DialogPreferences integration (14 tests)
- test_delimiters_category.py: new Delimiters page validation (13 tests)
- Fix ruff issues (F841, S108) in test files
- All tests passing with 100% success rate
### Documentation
- Add docs/refactor_settings_ui.md: comprehensive refactor overview
- Add docs/delimiters_category.md: Delimiters feature documentation
- Add docs/ui_styles.md: dark theme style guide
- Add docs/testing_summary.md: testing overview and commands
### Code Quality
- Apply ruff/black/pyupgrade via pre-commit hooks
- Fix F841 (unused variable) in test_dialog_preferences_integration.py
- Fix S108 (insecure temp path) using Path.home() in test_settings_ui.py
- End-of-file fixes applied automatically
## Files Modified
- tidal_dl_ng/ui/dialog_settings.ui (complete restructure)
- tidal_dl_ng/ui/dialog_settings.py (auto-generated from .ui)
- tidal_dl_ng/dialog.py (add 4 delimiter params + Delimiters category)
- tests/* (4 new test files with 61 tests)
- docs/* (4 new documentation files)
## Impact
- Improved UX: intuitive category navigation, better visual organization
- Extensibility: easy to add new settings pages/categories
- Quality: comprehensive test coverage ensures robustness
- User flexibility: customizable separators for metadata and filenames
## Technical Notes
- QStackedWidget pages indexed 0-4 matching category list order
- Navigation via QListWidget::currentRowChanged signal
- Automatic save/load through existing DialogPreferences methods
- No breaking changes to existing settings or configuration
## Testing Commands
```powershell
poetry run pre-commit run -a
poetry run pytest -q
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/delimiters_category.md | 43 | ||||
| -rw-r--r-- | docs/refactor_settings_ui.md | 128 | ||||
| -rw-r--r-- | docs/testing_summary.md | 32 | ||||
| -rw-r--r-- | docs/ui_styles.md | 23 |
4 files changed, 226 insertions, 0 deletions
diff --git a/docs/delimiters_category.md b/docs/delimiters_category.md new file mode 100644 index 0000000..0ef148b --- /dev/null +++ b/docs/delimiters_category.md @@ -0,0 +1,43 @@ +# "Delimiters" Category + +## Goal + +Allow users to customize separators used for artists and album artists, both in metadata and filenames. + +## Parameters + +- `metadata_delimiter_artist`: artists separator (metadata) +- `metadata_delimiter_album_artist`: album artists separator (metadata) +- `filename_delimiter_artist`: artists separator (filename) +- `filename_delimiter_album_artist`: album artists separator (filename) + +## UI + +- Page `page_delimiters` inside `sw_categories` +- GroupBox `gb_delimiters` +- 4 `QLineEdit` entries (`le_*`) with max width 100px + +## Integration + +- Add the 4 fields to `DialogPreferences.parameters_line_edit` +- Load values via `populate_line_edit()` +- Save via `to_settings()` + +## Tests + +- `tests/test_delimiters_category.py`: 13 tests + - Page existence + - Widgets accessibility + - Navigation to the page + - Width constraints + +## Examples + +- Semicolon: `"; "` → `Artist1; Artist2` +- Ampersand: `" & "` → `Artist1 & Artist2` +- Slash: `" / "` → `Artist1 / Artist2` + +## Notes + +- Default values are `", "` (comma + space) +- Fields are kept short (max 100px) to avoid breaking the layout diff --git a/docs/refactor_settings_ui.md b/docs/refactor_settings_ui.md new file mode 100644 index 0000000..651427c --- /dev/null +++ b/docs/refactor_settings_ui.md @@ -0,0 +1,128 @@ +# Settings Window Refactor + +Date: 2025-11-30 +Author: Automation (Copilot) + +## Goal + +Refactor the settings window to improve usability and maintainability: + +- Category list on the left +- Settings content on the right via QStackedWidget +- Clear separation of pages (Flags, Quality, Numbers, Paths & Formats, Delimiters) +- Consistent dark styling and tuned spacing +- Add unit and integration tests (61 total) + +## Key Changes + +### 1. UI Architecture + +- Navigation column: `QListWidget (lw_categories)` +- Pages container: `QStackedWidget (sw_categories)` +- Pages created: + - `page_flags` (GroupBox: gb_flags) + - `page_quality` (GroupBox: gb_choices) + - `page_numbers` (GroupBox: gb_numbers) + - `page_paths` (GroupBox: gb_path) + - `page_delimiters` (GroupBox: gb_delimiters) — NEW + +Impacted file: `tidal_dl_ng/ui/dialog_settings.ui` (auto-generated `dialog_settings.py`). + +### 2. New Category: Delimiters + +- "Delimiters" page with 4 `QLineEdit` fields to edit separators: + - `metadata_delimiter_artist` + - `metadata_delimiter_album_artist` + - `filename_delimiter_artist` + - `filename_delimiter_album_artist` +- Automatic integration with `DialogPreferences` through `parameters_line_edit`, `populate_line_edit()` and `to_settings()`. + +Files touched: + +- `tidal_dl_ng/ui/dialog_settings.ui` (new page) +- `tidal_dl_ng/ui/dialog_settings.py` (regenerated) +- `tidal_dl_ng/dialog.py` (added 4 parameters and new category in `_init_categories`). + +### 3. Styles & Spacing + +- Category list: dark style, blue selection, gray hover, light text. +- Vertical spacing: list item margin `2px 0px` (and optional view spacing). +- Settings area: dark background (QStackedWidget), styled GroupBoxes. + +Files touched: + +- `tidal_dl_ng/ui/dialog_settings.ui` (stylesheets on lw_categories and sw_categories) +- `tidal_dl_ng/ui/dialog_settings.py` (regenerated). + +### 4. Tests + +- New files: + - `tests/test_settings_ui.py`: UI and basic integration (14) + - `tests/test_settings_dialog_structure.py`: detailed structure (20) + - `tests/test_dialog_preferences_integration.py`: DialogPreferences integration (14) + - `tests/test_delimiters_category.py`: Delimiters page (13) +- Total: **61 tests**; ruff/black/pyupgrade applied via pre-commit. + +### 5. Pre-commit & Quality + +- Ruff fixes: + - F841 (unused variable) in `test_dialog_preferences_integration.py` + - S108 (using /tmp) replaced by `Path.home()` and safe values +- end-of-file-fixer and black reformatted automatically. + +## Usage + +### Launch the UI + +- Via the app: `poetry run tidal-dl-ng-gui` (or `python -m tidal_dl_ng.gui`) + +### Navigate + +- Select a category in `lw_categories` +- The corresponding page shows in `sw_categories`. + +### Edit separators + +- Open the "Delimiters" category +- Edit fields `le_metadata_delimiter_*` and `le_filename_delimiter_*` +- Confirm via OK + +## Known issue: poetry+dulwich KeyError b'HEAD + +- Cause: dulwich cannot resolve HEAD in the Git repo when Poetry queries VCS info. +- Fix: ensure `.git/HEAD` points to an existing branch (e.g. `ref: refs/heads/main`) and the branch exists; then re-run `poetry install`. See commands below. + +## Useful Commands (PowerShell) + +```powershell +cd C:\Users\mathe\PycharmProjects\tidal-dl-ng +poetry check --lock +poetry run pre-commit run -a +pytest -q +``` + +To fix HEAD if needed: + +```powershell +cd C:\Users\mathe\PycharmProjects\tidal-dl-ng +Get-Content .git\HEAD +# If empty/incorrect: +git init +git add . +git commit -m "Initialize repo for Poetry/Dulwich" +git branch -M main +Get-Content .git\HEAD +poetry install -vvv --no-interaction --all-extras --with dev,docs +``` + +## Impact + +- Better UX: category navigation, improved readability +- Extensible: easy to add new pages/settings +- Quality: comprehensive tests ensure robustness + +## Next Steps + +- Add contextual help (tooltips) for new delimiter fields +- Optionally adjust list spacing (8–10) based on feedback +- Add a preview of resulting formatting (e.g., sample metadata) diff --git a/docs/testing_summary.md b/docs/testing_summary.md new file mode 100644 index 0000000..5229548 --- /dev/null +++ b/docs/testing_summary.md @@ -0,0 +1,32 @@ +# Created Tests and Results + +## Test files + +- `tests/test_settings_ui.py` (14 tests) +- `tests/test_settings_dialog_structure.py` (20 tests) +- `tests/test_dialog_preferences_integration.py` (14 tests) +- `tests/test_delimiters_category.py` (13 tests) + +## Total + +- **61 tests** (unit + integration) + +## Coverage + +- UI creation and structure +- Category navigation +- Widgets presence and accessibility +- New "Delimiters" page +- Quality: ruff/black/pyupgrade enforced by pre-commit + +## Commands + +```powershell +cd C:\Users\mathe\PycharmProjects\tidal-dl-ng +poetry run pre-commit run -a +pytest -q +``` + +## Note + +If `poetry install` fails with KeyError b'HEAD, see "Settings Window Refactor" doc to fix the Git repo’s HEAD. diff --git a/docs/ui_styles.md b/docs/ui_styles.md new file mode 100644 index 0000000..6e2a81e --- /dev/null +++ b/docs/ui_styles.md @@ -0,0 +1,23 @@ +# UI Styles (Dark) + +## Category List (QListWidget) + +- Background: `#2b2b2b` +- Selection: blue `#3d5a80` + white text +- Hover: gray `#3a3a3a` +- Text: light gray `#e0e0e0` +- Padding: 4px +- Item margin: 2px vertical +- View spacing: 0 (can be set to 6–10 for more breathing room) + +## Settings Area (QStackedWidget) + +- Background: `#333333` +- Border: `#3d3d3d` +- GroupBox: background `#3a3a3a`, border `#4a4a4a`, radius 6 + +## Tuning Tips + +- Increase view spacing to 8–10 if preferred visually +- Harmonize corner radius with global UI style +- Use tooltips to explain parameters |
