Window.py PySide6 Custom QMainWindow — Frameless Window with Animated Panels

Initializes the window by calling super().__init__(), then configures the frameless window appearance and sets up all internal state variables. The constructor does not build any UI widgets — that is deferred to the initUI() method.

Key initialization steps:

1. Frameless window flag — Sets Qt.WindowType.FramelessWindowHint to remove the native window border, and Qt.WindowType.Window to ensure it is still treated as a top-level window.
2. Translucent background — Enables WA_TranslucentBackground so the rounded-corner painting in paintEvent produces actual transparency at the corners.
3. Golden ratio sizing — Calculates the initial window size as screen_dimension × 1.618 × 0.5, giving approximately 80.9% of the screen dimension. This creates a visually pleasing initial window size.
4. Centered positioning — The window is positioned at the horizontal center and slightly above vertical center (70% of calculated Y) for a more natural screen placement.
5. State initialization — All resize state, drag state, panel state, and size-lock flags are set to their default values.

Locks the window to its current size by setting both minimumSize and maximumSize to the current self.size(). This is the only reliable way to prevent Qt's layout system from auto-growing the window when internal widgets change their sizeHint. The layout will reflow inside the locked window boundary instead of pushing it outward.

Also sets self._size_locked = True for tracking purposes.

Relaxes the size constraints so that user-initiated resize operations (edge drag, maximize/restore animations) can change the window size. The minimum size is set to MIN_WINDOW_WIDTH × MIN_WINDOW_HEIGHT (400×300) and the maximum size is set to QWIDGETSIZE_MAX (16777215×16777215). After the operation completes, the window must be re-locked by calling _lock_size().

Convenience method that connects an animation's finished signal to _lock_size, ensuring the window is automatically re-locked as soon as the animation completes. Any previous _lock_size connection on this animation is disconnected first to avoid duplicate calls, which could cause issues if the same animation object is reused.

Constructs and assembles the entire window UI. This method must be called after constructing the AbdhWindow instance and before calling show(). It creates all widgets, layouts, and connections that make up the window.

Initialization sequence:

1. Central widget — Creates a QWidget with the CSS class window-background-layer and sets it as the central widget with zero content margins.
2. Grid layout — Creates a QGridLayout with zero margins and zero spacing for a pixel-perfect layout.
3. Left panel — Creates a QFrame with CSS class left-sidebar-background-layer, fixed width of pane_width (250px), and a QVBoxLayout with top margin equal to titlebar_height to avoid overlap.
4. Right panel — Creates a QFrame with CSS class right-sidebar-background-layer, starting at zero width (collapsed by default), with a QVBoxLayout and a stretch at the bottom for flexible content placement.
5. Toggle button — Creates the hamburger-menu toggle button that expands/collapses the left panel, and a pin button that switches between pinned and overlay modes.
6. Stacked widget — Creates a StackedWidget (custom class from .Widgets) for hosting application pages with back/forward navigation.
7. Titlebar — Calls _create_titlebar() to build the custom titlebar with all control buttons.
8. Grid placement — Adds all widgets to the grid layout in the correct positions with proper alignment and span values.
9. Column stretch — Sets column stretch factors: 0 for left panel, 1 for content, 0 for right panel.
10. Mouse tracking — Enables mouse tracking for edge-resize cursor feedback.
11. Animation setup — Creates the main QPropertyAnimation object for maximize/restore with OutQuad easing and 175ms duration.
12. Event filter — Installs a global event filter on QApplication.instance() to detect clicks outside panels and manage resize cursors.

Overrides the default QMainWindow.show() to add an initialization guard. If initUI() has not been called yet (self.initialized is False), it raises a RuntimeError with a descriptive message. Otherwise, it calls super().show() to display the window normally.

Toggles the left panel between pinned and overlay mode. When switching to overlay mode, the panel is removed from the grid and re-added with col-span = 2, its width is fixed to pane_min_width, and the stacked widget receives a left margin to avoid content occlusion. When switching back to pinned mode, the panel is re-added with col-span = 1 and the stacked widget's left margin is reset to 0. The pin button is hidden in overlay mode since pinning is only relevant in the expanded state.

Animates the left panel open/closed with a smooth width transition. The behavior differs depending on whether the panel is in overlay or pinned mode:

• Overlay mode: Calls toggle_frame() for a simple width toggle between 0 and pane_width.
• Pinned mode: Creates a QParallelAnimationGroup that simultaneously animates both minimumWidth and maximumWidth of the panel. This dual-animation approach prevents layout conflicts where Qt might auto-adjust one property while the other is being animated. The animation uses InOutQuad easing over 400ms for a natural feel.

After the animation completes, the stacked widget's width constraints are reset (minimum to 0, maximum to QWIDGETSIZE_MAX) so it can freely expand when the window is resized. The expanded flag is toggled and the pin button visibility is updated accordingly.

A generic panel toggle method that animates any QFrame between collapsed and expanded widths. If the frame's current width is less than pane_width, it animates open to pane_width; otherwise, it animates closed to the given min value. The animation uses OutCubic easing over 400ms for a smooth deceleration effect.

Before starting a new animation, any running animation on the sender is stopped to prevent conflicts. The animation object is scheduled for deletion after it finishes via deleteLater().

Convenience method that calls toggle_frame(self.right_panel, 0) to toggle the right (settings) panel open or closed. The collapsed width is 0, meaning the panel completely disappears when closed.

Performs a combined fade-in and slide-in animation when the window is shown for the first time. Two animations run in parallel:

• Opacity animation: Transitions windowOpacity from 0.0 to 1.0 over 500ms with OutQuad easing, creating a smooth fade-in from transparent to fully opaque.
• Geometry animation: Starts the window 50 pixels above its final position and slides it down to the target geometry over 500ms with OutQuad easing, creating a subtle slide-in effect.

Before starting, the size lock is unlocked so the geometry animation can move the window. After the geometry animation finishes, the size is re-locked via _connect_lock_after_animation(). This method is called from showEvent() only when self.first_show is True.

Toggles between maximized and restored states. If currently maximized, it calls animate_restore() and changes the maximize button icon to a single square. If currently windowed, it calls animate_maximize() and changes the icon to a double-square. The is_maximized flag is toggled after the call.

Animates the window from its current geometry to the full available screen geometry (excluding the taskbar). Before animating, the current geometry is saved as original_geometry — but with bounds checking to ensure the stored geometry is valid. Specifically, if the window is already wider/taller than the screen or positioned off-screen, the geometry is clamped to ensure a valid restore target.

The animation uses the main self.animation object with OutQuad easing over 175ms. After completion, the window is re-locked via _connect_lock_after_animation().

Animates the window from its current (maximized) geometry back to the stored original_geometry. Uses the same self.animation object with OutQuad easing over 175ms. After completion, the window is re-locked.

Determines which edge or corner the cursor is near based on the mouse position relative to the window boundaries. The RESIZE_MARGIN (8 pixels) defines the invisible grab zone around the window perimeter. Corners take priority over edges in the detection logic.

Maps a resize direction string to the appropriate Qt cursor shape. Horizontal edges use SizeHorCursor, vertical edges use SizeVerCursor, and diagonal corners use SizeFDiagCursor or SizeBDiagCursor depending on the diagonal direction. Returns ArrowCursor for unrecognized directions.

Performs the actual resize based on the stored direction and the mouse position delta. It calculates the new geometry by adjusting the appropriate edges of the stored _resize_start_geo rectangle. Each direction flag in _resize_dir (e.g., 'left', 'top') is checked independently, which allows corner resizing to modify two edges simultaneously.

Minimum size constraints (MIN_WINDOW_WIDTH and MIN_WINDOW_HEIGHT) are enforced: if resizing would make the window smaller than the minimum, the corresponding edge is not moved. After setting the geometry, the main layout is explicitly activated via self.main_widget.layout().activate() to force an immediate reflow so the stacked widget expands/contracts to fill the new window size.

Handles left-button mouse press events with two distinct behaviors:

1. Edge/corner resize initiation: If the cursor is near an edge or corner (determined by _get_resize_direction()) and the window is not maximized, the resize state is initialized. The size lock is unlocked, the resize direction and starting geometry/position are stored, and the resize cursor is locked for the entire drag operation.
2. Titlebar drag initiation: If the click is not near an edge, the drag start position is stored as the offset between the global cursor position and the window's top-left corner. This offset is used in mouseMoveEvent() to move the window smoothly.

Handles double-click events on the titlebar area. If the double-click occurs within the titlebar height (self.titlebar_height) from the top of the window, it triggers toggle_maximize_restore(). This mimics the standard Windows/macOS behavior of double-clicking the titlebar to maximize/restore the window.

Handles left-button mouse move events with two behaviors:

1. Resizing: If self._resizing is True, calls _do_resize() with the current global position to update the window geometry.
2. Titlebar dragging: If a drag start position exists and the cursor is within the titlebar's Y range, the window is moved to follow the cursor. If the window is maximized, it is first restored to windowed mode before dragging begins, allowing the user to "pull" the window out of maximized state — a common UX pattern.

Handles left-button mouse release events. If the user was resizing (self._resizing is True), the resize state is reset and the window is re-locked to its new size via _lock_size(). The cursor is also unset, allowing the eventFilter to set the correct cursor on the next hover move. The drag start position is always cleared on release.

Triggers the fade-in animation when the window is shown for the first time. If self.first_show is True, it sets it to False and calls animate_fadeIn(). Subsequent show events (e.g., after minimizing and restoring) do not trigger the animation.

Custom paint event that draws a rounded rectangle over the entire window area. This is necessary because the window is frameless with a translucent background, so without custom painting the corners would show the desktop or other windows behind. The method uses QPainter with antialiasing to draw a QPainterPath containing a rounded rect (8px radius), filled with the window palette's background color.

Resets the cursor to the default arrow when the mouse leaves the window entirely. This prevents the resize cursor from persisting when the mouse moves away from the window edge without being over any child widget.

A global event filter installed on QApplication.instance() that handles two critical functions that cannot be implemented in regular event handlers:

1. Cursor Management (MouseMove, no buttons)

When the mouse moves without any buttons pressed, the filter checks if the cursor is near a window edge or corner. If so, it sets the appropriate resize cursor. If not, it unsets the cursor. This must be in the event filter (not mouseMoveEvent) because mouseMoveEvent only fires when the mouse is directly over the window's own area — not over child widgets. Without the event filter, the resize cursor would get "stuck" or appear over child widgets that inherit the parent's cursor. The filter is only active when the window is not maximized and is visible.

2. Auto-Close Panels on Outside Click (MouseButtonPress)

When a mouse button press is detected anywhere in the application, the filter checks whether the click target is one of the control buttons (toggle, pin, settings, maximize, minimize, close). If it is, the event is passed through normally. Otherwise:

• Right panel: If the right panel is open (width > 0) and the click is outside its geometry, it is auto-closed via toggle_frame().
• Left panel (overlay mode): If the left panel is in overlay mode and expanded, and the click is outside its geometry, it is auto-collapsed via animate_content().

Builds the custom titlebar widget with all its child widgets and layout. The titlebar is a QWidget with object name Titlebar, fixed height of titlebar_height (42px), and a QHBoxLayout containing the following widgets from left to right:

All buttons use the grouped_mini CSS class (except the close button which uses closebutton) and are aligned to the top of the titlebar. The layout direction is forced to LeftToRight regardless of the application's layout direction, ensuring the window controls always appear on the right side.

Shows or hides the settings button in the titlebar. This is useful when a particular page or application state does not require a settings panel.

Shows or hides both the back and forward navigation buttons in the titlebar simultaneously. This is useful for pages that do not support navigation history.

Sets the layout direction of the stacked widget, enabling right-to-left (RTL) support for languages like Arabic or Hebrew. The titlebar and side panels are not affected — they maintain their forced LeftToRight direction.

Independently controls the visibility of the back and forward navigation buttons. This is typically called after a page navigation event to reflect the current navigation history state — the back button is visible only if there is a previous page to return to, and the forward button is visible only if there is a next page.

Inserts a widget into the right panel layout, positioned before the bottom stretch. The stretch was added during initialization with addStretch(1), so new items are inserted at index count - 1 to appear above the stretch. This ensures that content is always pushed to the top of the panel with flexible space at the bottom.

Appends a widget to the end of the left panel layout. Widgets are added in order from top to bottom, after the toggle and pin buttons that were added during initUI().

Returns the widget at the given index in the left panel layout. This is useful for accessing or modifying previously added panel items.

Adds a page widget to the central stacked widget. Pages are managed by the StackedWidget class, which provides navigation history (back/forward) functionality. The first page added becomes the initially visible page. Each subsequent page is hidden until navigated to via the stacked widget's methods.

Applies a Qt style sheet string directly to the window. This is the programmatic way to set styles, useful for dynamically generated or modified style sheets. The style sheet affects the window and all its child widgets.

Loads a Qt style sheet from an external file and applies it to the window. The file is read as UTF-8 text. If the file does not exist, a warning is printed to the console and None is returned. This method is useful for separating style definitions from application code and allowing runtime theme switching.