QCustomQStackedWidget

QCustomQStackedWidget is an enhanced version of Qt's standard QStackedWidget that provides smooth animated transitions between pages. It supports both slide and fade animations with customizable timing and easing curves.

---

Overview

• Animated Transitions:
  Smooth slide and fade animations when switching between widget pages.

• Customizable Effects:
  Configurable animation duration, easing curves, and transition directions.

• Easy Navigation:
  Built-in methods for next/previous page navigation with animations.

• Designer Integration:
  Full Qt Designer support with custom properties and preview.

• Flexible Configuration:
  Supports both programmatic and JSON-based configuration.

---

Constructor

QCustomQStackedWidget(parent=None)

• parent:
  The parent widget (defaults to None).

---

Key Properties

fadeTransition (bool)

• Purpose:
  Enables or disables fade animation between pages.

• Getter:
  Returns True if fade transition is enabled.

• Setter:
  Toggles fade animation.

• Example:

  stacked.fadeTransition = True

slideTransition (bool)

• Purpose:
  Enables or disables slide animation between pages.

• Getter:
  Returns True if slide transition is enabled.

• Setter:
  Toggles slide animation.

• Example:

  stacked.slideTransition = True

transitionTime (int)

• Purpose:
  Duration of slide animations in milliseconds.

• Getter:
  Returns current slide animation duration.

• Setter:
  Updates slide animation duration.

• Example:

  stacked.transitionTime = 500

fadeTime (int)

• Purpose:
  Duration of fade animations in milliseconds.

• Getter:
  Returns current fade animation duration.

• Setter:
  Updates fade animation duration.

• Example:

  stacked.fadeTime = 300

transitionEasingCurve (str)

• Purpose:
  Easing curve for slide animations.

• Getter:
  Returns current slide easing curve.

• Setter:
  Updates slide animation easing curve.

• Example:

  stacked.transitionEasingCurve = "OutBack"

fadeEasingCurve (str)

• Purpose:
  Easing curve for fade animations.

• Getter:
  Returns current fade easing curve.

• Setter:
  Updates fade animation easing curve.

• Example:

  stacked.fadeEasingCurve = "Linear"

---

Methods

setTransitionDirection(direction)

• Description:
  Sets the direction for slide animations.

• Parameters:

  • direction: Qt.Horizontal or Qt.Vertical

• Example:

  stacked.setTransitionDirection(Qt.Horizontal)

setTransitionSpeed(speed)

• Description:
  Sets the duration for slide animations.

• Parameters:

  • speed: Duration in milliseconds

• Example:

  stacked.setTransitionSpeed(500)

setFadeSpeed(speed)

• Description:
  Sets the duration for fade animations.

• Parameters:

  • speed: Duration in milliseconds

• Example:

  stacked.setFadeSpeed(300)

setTransitionEasingCurve(curve)

• Description:
  Sets the easing curve for slide animations.

• Parameters:

  • curve: Easing curve name string

• Example:

  stacked.setTransitionEasingCurve("OutCubic")

setFadeCurve(curve)

• Description:
  Sets the easing curve for fade animations.

• Parameters:

  • curve: Easing curve name string

• Example:

  stacked.setFadeCurve("Linear")

slideToPreviousWidget()

• Description:
  Animates transition to the previous widget in the stack.

• Behavior:

  • Decrements current index with animation
  • Wraps around to last widget if at first

• Example:

  stacked.slideToPreviousWidget()

slideToNextWidget()

• Description:
  Animates transition to the next widget in the stack.

• Behavior:

  • Increments current index with animation
  • Wraps around to first widget if at last

• Example:

  stacked.slideToNextWidget()

slideToWidgetIndex(index)

• Description:
  Animates transition to a specific widget index.

• Parameters:

  • index: Target widget index

• Example:

  stacked.slideToWidgetIndex(2)

slideToWidget(widget)

• Description:
  Animates transition to a specific widget.

• Parameters:

  • widget: Target widget object

• Example:

  stacked.slideToWidget(settings_page)

setCurrentWidget(widget)

• Description:
  Overridden method to use animations when switching widgets.

• Parameters:

  • widget: Target widget object

• Example:

  stacked.setCurrentWidget(profile_page)

---

Usage Example

Basic Setup

from qtpy.QtWidgets import QApplication, QWidget, QVBoxLayout, QLabel
from Custom_Widgets.QCustomQStackedWidget import QCustomQStackedWidget

app = QApplication([])

# Create stacked widget
stacked = QCustomQStackedWidget()

# Add pages
page1 = QLabel("Page 1 Content")
page2 = QLabel("Page 2 Content") 
page3 = QLabel("Page 3 Content")

stacked.addWidget(page1)
stacked.addWidget(page2)
stacked.addWidget(page3)

# Configure animations
stacked.slideTransition = True
stacked.fadeTransition = True
stacked.setTransitionSpeed(500)
stacked.setFadeSpeed(300)
stacked.setTransitionDirection(Qt.Horizontal)

stacked.show()
app.exec_()

Navigation Controls

from qtpy.QtWidgets import QPushButton, QHBoxLayout

class NavigationWindow(QWidget):
    def __init__(self):
        super().__init__()
        
        self.stack = QCustomQStackedWidget()
        self.setup_ui()
        self.configure_animations()
    
    def setup_ui(self):
        layout = QVBoxLayout(self)
        
        # Navigation buttons
        nav_layout = QHBoxLayout()
        self.prev_btn = QPushButton("Previous")
        self.next_btn = QPushButton("Next")
        self.page1_btn = QPushButton("Page 1")
        self.page2_btn = QPushButton("Page 2")
        
        nav_layout.addWidget(self.prev_btn)
        nav_layout.addWidget(self.next_btn)
        nav_layout.addWidget(self.page1_btn)
        nav_layout.addWidget(self.page2_btn)
        
        layout.addLayout(nav_layout)
        layout.addWidget(self.stack)
        
        # Add pages
        self.page1 = QLabel("Welcome to Page 1")
        self.page2 = QLabel("Welcome to Page 2")
        
        self.stack.addWidget(self.page1)
        self.stack.addWidget(self.page2)
        
        # Connect navigation
        self.prev_btn.clicked.connect(self.stack.slideToPreviousWidget)
        self.next_btn.clicked.connect(self.stack.slideToNextWidget)
        self.page1_btn.clicked.connect(lambda: self.stack.slideToWidget(self.page1))
        self.page2_btn.clicked.connect(lambda: self.stack.slideToWidget(self.page2))
    
    def configure_animations(self):
        self.stack.slideTransition = True
        self.stack.setTransitionSpeed(400)
        self.stack.setTransitionDirection(Qt.Horizontal)
        self.stack.setTransitionEasingCurve("OutCubic")

JSON Configuration

Create style.json:

{
  "QCustomQStackedWidget": [
    {
      "name": "mainStack",
      "transitionAnimation": {
        "fade": {
          "active": true,
          "duration": 300,
          "easingCurve": "Linear"
        },
        "slide": {
          "active": true,
          "duration": 500,
          "direction": "horizontal",
          "easingCurve": "OutBack"
        }
      },
      "navigation": {
        "nextPage": "nextBtn",
        "previousPage": "prevBtn",
        "navigationButtons": {
          "homeBtn": "homePage",
          "settingsBtn": "settingsPage"
        }
      }
    }
  ]
}

Apply JSON styling:

from Custom_Widgets import loadJsonStyle

# Apply JSON configuration
loadJsonStyle(self, self.ui)

Advanced Animation Configuration

# Complex animation setup
stacked = QCustomQStackedWidget()

# Enable both transitions
stacked.slideTransition = True
stacked.fadeTransition = True

# Configure timing
stacked.setTransitionSpeed(600)  # Slide duration
stacked.setFadeSpeed(400)        # Fade duration

# Configure easing curves
stacked.setTransitionEasingCurve("OutBack")
stacked.setFadeCurve("InOutCubic")

# Set direction
stacked.setTransitionDirection(Qt.Vertical)  # Up/down transitions

# Add navigation
next_btn.clicked.connect(stacked.slideToNextWidget)
prev_btn.clicked.connect(stacked.slideToPreviousWidget)

---

Animation Features

Supported Easing Curves

• "Linear"
• "InQuad", "OutQuad", "InOutQuad"
• "InCubic", "OutCubic", "InOutCubic"
• "InQuart", "OutQuart", "InOutQuart"
• "InQuint", "OutQuint", "InOutQuint"
• "InSine", "OutSine", "InOutSine"
• "InExpo", "OutExpo", "InOutExpo"
• "InCirc", "OutCirc", "InOutCirc"
• "InElastic", "OutElastic", "InOutElastic"
• "InBack", "OutBack", "InOutBack"
• "InBounce", "OutBounce", "InOutBounce"

Transition Directions

• Horizontal: Left/right sliding
• Vertical: Up/down sliding

Combined Effects

• Slide + Fade: Simultaneous sliding and fading
• Sequential: Configurable timing for complex effects
• Directional: Different directions for different navigation

---

Additional Notes

• Performance:
  Uses QParallelAnimationGroup for efficient simultaneous animations.

• Memory Management:
  Proper cleanup of animation objects to prevent memory leaks.

• Error Handling:
  Prevents animation conflicts with active transition checks.

• Designer Support:
  All properties available in Qt Designer property editor.

• Compatibility:
  Maintains full compatibility with standard QStackedWidget API.

---

The QCustomQStackedWidget is perfect for wizard interfaces, onboarding flows, settings panels, tabbed interfaces, and any application requiring smooth, animated transitions between different content pages.

API reference

Generated from the widget's live metaobject — do not edit by hand.

Properties

Property	Type	Default
frameShape	QFrame::Shape	—
frameShadow	QFrame::Shadow	—
lineWidth	int	—
midLineWidth	int	—
frameWidth	int	—
frameRect	QRect	—
currentIndex	int	—
count	int	—
fadeTransition	bool	—
slideTransition	bool	—
transitionDirection	Qt::Orientation	—
transitionTime	int	—
fadeTime	int	—
fadeDelay	int	—
fadeInTime	int	—
fadeOutTime	int	—
fadeInCurve	int	—
fadeOutCurve	int	—
transitionEasingCurve	int	—
fadeEasingCurve	int	—

Signals

Signal
transitionFinished()

Methods

Method	Description
addWidget(widget)	Add a widget to the stacked widget with proper opacity initialization.
fadeDelay(*args, **kwargs)	Get the delay between fade out and fade in animations in milliseconds.
fadeEasingCurve(*args, **kwargs)	Fade easing curve.
fadeInCurve(*args, **kwargs)	Fade in curve.
fadeInTime(*args, **kwargs)	Get the fade in animation time in milliseconds.
fadeOutCurve(*args, **kwargs)	Fade out curve.
fadeOutTime(*args, **kwargs)	Get the fade out animation time in milliseconds.
fadeTime(*args, **kwargs)	Get the total fade transition time in milliseconds.
fadeTransition(*args, **kwargs)	Get the fade transition state.
setCurrentIndex(index)	Set the current widget index with proper opacity handling.
setCurrentWidget(widget)	Set the current widget with animation if enabled.
setFadeCurve(aesingCurve)	Legacy method to set fade easing curve.
setFadeDelay(delay)	Set the delay between fade out and fade in animations.
setFadeInOutCurves(fadeInCurve, fadeOutCurve)	Set fade in and fade out easing curves separately.
setFadeInOutTimes(fadeInTime, fadeOutTime)	Set fade in and fade out times separately.
setFadeSpeed(speed)	Set the fade transition speed.
setFadeTransition(fadeState=True)	Enable or disable fade transitions (setter for the
setSlideTransition(slideState=True)	Enable or disable slide transitions (setter for the
setTransitionDirection(direction)	Set the transition direction.
setTransitionEasingCurve(aesingCurve)	Set the easing curve for slide animations.
setTransitionSpeed(speed)	Set the slide transition speed.
slideToNextWidget()	Transition to the next widget with animation.
slideToPreviousWidget()	Transition to the previous widget with animation.
slideToWidget(newWidget)	Transition to a specific widget with animation.
slideToWidgetIndex(index)	Transition to a specific widget index with animation.
slideTransition(*args, **kwargs)	Get the slide transition state.
transitionDirection(*args, **kwargs)	Slide transition direction. Exposed as Qt.Orientation so Qt
transitionEasingCurve(*args, **kwargs)	Transition easing curve.
transitionFinished(...)	Transition finished.
transitionTime(*args, **kwargs)	Get the slide transition time in milliseconds.