StyleManagers.py PySideAbdhUI — QSS Stylesheet Manager with Accent Color & Validation

Initializes the stylesheet manager with an optional accent color placeholder token. The stylesheet string is set to None initially — no file is loaded until load_stylesheet() is called. The accent color template defaults to '@accent-color', which follows CSS at-rule syntax. This token is expected to appear in the QSS file as a placeholder that will be replaced with an actual hex color value at runtime.

Loads a QSS file from the given path into the self.stylesheet string. The file path is stored as self.qss_file for later use by save_stylesheet(). The file is read with UTF-8 encoding. If the file does not exist, an error is logged and self.stylesheet remains unchanged (still None if this is the first load, or retains the previous content if a file was previously loaded).

After loading, the self.stylesheet attribute contains the complete raw content of the QSS file, including comments, placeholder tokens, and all widget definitions. No parsing or preprocessing is performed at load time.

Saves the current self.stylesheet content back to the file at self.qss_file (the path stored by the most recent call to load_stylesheet()). The file is overwritten completely with the current in-memory content, written with UTF-8 encoding. If the file does not exist at the stored path, an error is logged and no save is performed.

This method is automatically called by add_property_to_widget() after each property modification, ensuring that the file on disk always reflects the in-memory state. This auto-save behavior means every property change immediately persists to disk.

Saves the current stylesheet content to a different file path, analogous to a "Save As" operation. Unlike save_stylesheet(), this method does not update self.qss_file — subsequent calls to save_stylesheet() will still write to the original file. The file must already exist at the specified path; if it does not, an error is logged and no save is performed.

Adds or updates a CSS property within a specific widget's style block in the stylesheet. This is the primary method for fine-grained stylesheet customization. It operates in three modes depending on the current state of the stylesheet:

Mode 1: Update existing property

If the widget block exists and the property already exists within it, the property value is replaced. For example, if QPushButton { color: red; } exists and add_property_to_widget("QPushButton", "color", "blue") is called, the result is QPushButton { color: blue; }.

Mode 2: Append new property to existing block

If the widget block exists but the property does not, the new property is appended before the closing brace with 4-space indentation. For example, if QPushButton { color: red; } exists and add_property_to_widget("QPushButton", "border", "1px solid") is called, the result is:

QPushButton {
    color: red;
    border: 1px solid;
}

Mode 3: Create new widget block

If no block for the widget exists at all, a new block is created and appended to the end of the stylesheet. For example, calling add_property_to_widget("QLabel", "font-size", "14px") when no QLabel block exists produces:

QLabel {
    font-size: 14px;
}

After any modification, save_stylesheet() is called automatically to persist the change to disk.

Removes all stylesheet blocks matching the given widget name, including any pseudo-state variants. The regex pattern name(:\w+)?\s*\{[\s\S]*?\} matches both the base widget (QPushButton { ... }) and any pseudo-states (QPushButton:hover { ... }, QPushButton:pressed { ... }). This is useful for completely removing a widget's styling from the stylesheet without affecting other widgets.

The pattern uses a non-greedy match ([\s\S]*?) to find the shortest possible content between braces, which works correctly for simple blocks but may produce unexpected results for blocks containing nested braces.

Appends raw QSS content to the existing stylesheet string. The new content is joined with a newline separator. This is the simplest way to add stylesheet content — it performs no parsing, validation, or deduplication. The caller is responsible for ensuring the appended content is valid QSS and does not conflict with existing rules.

Checks whether the accent color placeholder exists in the loaded stylesheet and, if it does, attempts to extract its value. The method returns a tuple where the first element is a boolean indicating whether the placeholder was found, and the second element is the extracted hex color value (or an empty string if extraction failed).

The method performs three checks:

1. Stylesheet loaded?: If self.stylesheet is None or the QSS file doesn't exist, returns (False, '').
2. Placeholder present?: Searches for the accent_color_template string in the stylesheet content.
3. Value extractable?: If the placeholder exists, calls extract_accent_color_value() to parse the hex color. Returns (True, color) on success, (True, '') if the placeholder exists but the value couldn't be extracted.

Extracts the hex color value assigned to the accent color placeholder in the stylesheet. The method handles both commented and uncommented definition formats using a single regex with two alternation branches:

• Commented format: /* @accent-color: #0078d7; */ — The regex matches the comment delimiters, the placeholder name, and captures the hex value.
• Uncommented format: @accent-color: #0078d7; — The regex matches the plain definition and captures the hex value.

The regex captures 3-digit (#FFF) and 6-digit (#FFFFFF) hex color values. If a match is found, the first non-None capture group is returned (using a generator expression with next()). If no match is found, an empty string is returned.

Replaces all occurrences of the accent color placeholder token in the stylesheet with the provided hex color string. The replacement uses Python's str.replace(), which performs a global (all occurrences) replacement. This means every instance of @accent-color in the stylesheet — whether used as a CSS value (color: @accent-color;) or in a definition (@accent-color: #0078d7;) — will be replaced.

Convenience method that validates the in-memory self.stylesheet string. Delegates to the static method validate_stylesheet(self.stylesheet).

A static method that performs syntax validation on a given stylesheet string. The validation pipeline consists of three sequential checks, each of which can cause the method to return False early:

1. Null Check

If the stylesheet is None, a warning is logged and the method returns False. This prevents AttributeError when calling string methods on None.

2. Unmatched Curly Braces

Counts the number of { and } characters in the stylesheet. If they don't match, an error is logged and False is returned. This catches the most common QSS error — a missing closing brace that causes all subsequent rules to be absorbed into the unclosed block.

3. Missing Semicolons

Before checking for semicolons, the method preprocesses the stylesheet by removing CSS comments (to avoid false positives) and temporarily replacing the @accent-color placeholder with a valid hex color. Then, each style block is extracted and checked for at least one property ending with a semicolon. A block with zero semicolon-terminated properties is flagged as having missing semicolons.

4. Invalid Characters

Checks for characters outside the allowed QSS character set. The regex [^\w\s:\-;#.%{}(),@"] defines the whitelist of valid characters: word characters, whitespace, colons, hyphens, semicolons, hash, period, percent, braces, parentheses, commas, at-signs, and double quotes. Any other character is flagged as invalid.