Widgets.py PySideAbdhUI — Custom Widget Collection

Initializes the stacked widget by calling super().__init__(), then configures animation and visual properties. The CSS class stack is assigned via setProperty('class', 'stack') for external stylesheet targeting. A solid white background is set using setAutoFillBackground(True) with a white palette color to prevent flickering during animated transitions — without this, the transparent background of the parent would be visible between page slides, causing a visual glitch.

Adds a page widget to the stacked container and automatically navigates to it. The method supports an optional deduplication feature: when allow_same_tyoes is False, it scans all existing pages and removes any widget that has the same Python type as the new page before inserting it. This is useful for ensuring that only one instance of a particular page type exists at any time — for example, preventing multiple "Settings" or "Profile" pages from accumulating in the stack.

When deduplication is active, the scan iterates backwards through the widget list to safely remove items without invalidating indices. Removed widgets are deleted via deleteLater() to ensure proper cleanup. The new page is given setAutoFillBackground(True) to prevent flickering during slide animations.

After adding, go_last() is called to navigate to the newly added page with a slide animation.

Navigates to the next page in the stack (current index + 1). If the current page is already the last one, no action is taken — the boundary check new_index < self.count() prevents out-of-bounds navigation. The transition is animated.

Navigates to the previous page in the stack (current index - 1). If the current page is already the first one, no action is taken — the boundary check new_index >= 0 prevents out-of-bounds navigation. The transition is animated.

Navigates directly to the page at the specified index with an animated transition. Boundary validation is handled by setCurrentIndexAnimated().

Navigates to the last page in the stack (self.count() - 1). This is called automatically by add_page() after a new page is inserted.

Navigates to the first page in the stack (index 0) with an animated transition.

Initiates an animated transition to the page at the specified index. This method performs three guard checks before proceeding:

1. Index bounds: If index < 0 or index >= self.count(), the call is ignored.
2. Same index: If the target index equals the current index, no animation is needed.
3. Animation guard: If self.animating is True, the call is ignored to prevent overlapping animations.

Once the guards pass, the current widget is hidden, the direction is determined (+1 for forward navigation, -1 for backward), and the animation is delegated to setCurrentWidgetAnimated().

Performs the actual animated slide transition between the current widget and the next widget. The method sets up two parallel QPropertyAnimation objects on the geometry property of each widget:

• Outgoing animation: The current widget starts at QRect(0, 0, width, height) and slides to QRect(-width*direction, 0, width, height). When direction = +1 (forward), it slides left; when direction = -1 (backward), it slides right.
• Incoming animation: The next widget starts at QRect(width*direction, 0, width, height) (off-screen) and slides to QRect(0, 0, width, height) (center).

Both animations run in a QParallelAnimationGroup with OutCubic easing over animation_duration (400ms). The animating flag is set to True before starting and reset in _on_animation_finished(). The next widget is raised to the top of the Z-order with raise_() so it paints above the outgoing widget during the transition.

Callback invoked when the parallel animation group finishes. It performs the following cleanup steps:

1. Set final index: Calls self.setCurrentIndex(self.target_index) to update the internal state to the target page.
2. Reset animation flag: Sets self.animating = False to allow new navigation operations.
3. Clean up animation group: Calls self.animation_group.deleteLater() to free the animation objects.
4. Reset widget geometry: Explicitly sets the current widget's geometry to fill the entire stacked widget area, calls updateGeometry() and adjustSize(), and activates the widget's layout to ensure proper sizing after the animation.

This cleanup is essential because the animation manipulates geometry directly, which can leave widgets in an inconsistent layout state if not properly reset.

Overrides the default resize event to ensure the current page's layout is re-activated when the stacked widget is resized. This is necessary because during an animated transition, widget geometries are managed manually and may not automatically adjust to the new container size. When the animation is not running (not self.animating), the current widget's layout is explicitly activated via layout.activate().

Creates a separator line with the specified orientation, stroke width, and color. The orientation determines whether a horizontal (HLine) or vertical (VLine) frame shape is used. The color is applied via a style sheet that sets both color and background-color properties, and constrains the maximum height to the stroke width in pixels for horizontal separators.

Initializes the label with optional text. The text is set via super().setText(text) in the constructor rather than passed to QLabel.__init__() to ensure consistency with the overridden setText() method.

A custom PySide6 signal that is emitted whenever the label's text is changed via setText(). The signal carries the new text as a str parameter, allowing connected slots to react to the updated content. The signal is only emitted when the new text differs from the current text, preventing infinite loops in bidirectional data binding scenarios.

Overrides QLabel.setText() to add change detection. The method compares the new text with the current text returned by self.text(). If they differ, it calls super().setText(text) to update the label and then emits the textChanged signal with the new text. If the text is the same, no action is taken, which prevents unnecessary signal emissions and potential infinite loops in signal-slot chains.

Initializes the progress ring with default property values. The minimum widget size is set to 120×120 pixels to ensure the ring is always large enough to be visually meaningful and to prevent layout issues where the widget might be squeezed to zero size.

Sets the current progress value. The value is clamped to the valid range [_min, _max] using max(self._min, min(self._max, val)). After setting, self.update() is called to schedule a repaint of the widget.

Returns the current progress value.

Sets the minimum and maximum values for the progress range. This changes the scale against which the current value is measured. For example, setting setRange(0, 50) means a value of 25 represents 50% progress. After setting, self.update() schedules a repaint.

Sets the color of the progress arc. The input is converted to a QColor object, which accepts CSS color strings ('#FF5722', 'red', 'rgb(255,87,34)') or existing QColor objects.

Sets the color of the background ring track that the progress arc fills over. This is typically a muted or semi-transparent color that provides visual context for the unfilled portion of the ring.

Sets the stroke width of the ring arc in pixels. Larger values create a thicker ring, while smaller values create a thinner one. The ring width also affects the inset of the arc from the widget boundary — the arc is drawn inside the widget rectangle with a margin equal to _ring_width on all sides.

Controls whether the percentage text is rendered in the center of the ring. When False, only the arc is drawn, creating a clean, icon-style progress indicator. When True, the current value followed by a percent sign is rendered at the center.

Renders the ring progress indicator using QPainter. The painting process consists of three layers, drawn in order:

1. Background Ring (Track)

A full 360-degree arc is drawn using the _bg_color pen with RoundCap style for smooth endpoints. The arc rectangle is the widget rectangle inset by _ring_width on all sides, ensuring the ring does not overflow the widget boundary. The arc is drawn with drawArc(rect, 0, 360*16) — Qt uses 1/16th of a degree as the unit for arc angles.

2. Progress Arc

The progress fraction is calculated as (_value - _min) / (_max - _min), producing a value between 0.0 and 1.0. This fraction is multiplied by 360×16 to get the span angle in Qt's 1/16-degree units. The progress arc is drawn starting from 90×16 (the 12 o'clock position) with a negative span angle, meaning it progresses clockwise. If _max == _min, the fraction defaults to 0 to prevent division by zero.

3. Percentage Text

If _show_text is True, the current value followed by a percent sign (f"{_value}%") is rendered at the center of the widget using drawText(self.rect(), Qt.AlignCenter, text). The font size is controlled by _font_size.

Initializes the search box with configurable collapsed and expanded widths, and animation duration. The widget starts in its collapsed state (fixed width = collapsed_width). A QAction with a search icon is added at the leading position, and placeholder text "Search…" is set. A reusable QPropertyAnimation targeting the custom expandingWidth property is created with OutCubic easing for a natural deceleration effect.

A custom Qt property that allows QPropertyAnimation to animate the widget's width. Qt's property animation system requires the target property to be defined as a Property with getter and setter methods. The expandingWidth property wraps the widget's width() and setFixedWidth() calls, making it animatable.

Getter: getExpandingWidth(self) -> int

Returns the current width of the widget via self.width().

Setter: setExpandingWidth(self, width: int)

Sets the widget's fixed width to the given value via self.setFixedWidth(width). Using setFixedWidth ensures the widget does not change size during the animation due to layout constraints.

When the search box receives focus (clicked or tabbed into), it animates from the collapsed width to the expanded width. The animation uses the reusable _animation object with OutCubic easing, creating a smooth expansion that decelerates as it reaches the target width.

When the search box loses focus, it conditionally collapses back to the collapsed width. The collapse only occurs if the text field is empty (checked via self.text().strip()). If the user has typed text, the search box remains expanded to keep the entered content visible. This is a deliberate UX decision — collapsing with text would hide the user's input and create confusion.

Core animation method that drives the width transition. It stops any currently running animation on the reusable _animation object, sets the start value to the current width and the end value to the target width, then starts the animation. Stopping the previous animation before starting a new one prevents conflicts if the user rapidly focuses and unfocuses the widget.