Skip to content

⏱️ Timeline

Wallpaper Manager Internal Flows

1. Adding a New Wallpaper

Entry Point

setWallpaperAtTimelineIndex(
    type,           // ContentTypes::InstalledType
    absolutePath,   // Wallpaper file path
    previewImage,   // Preview image path
    file,          // Main file name
    title,         // Display title
    monitorIndex,  // Vector of monitor indices
    timelineIndex, // Timeline section index
    identifier,    // Section identifier
    saveToProfiles // Whether to persist changes
)

Internal Flow

  1. Validation Phase
  2. Check path validity
  3. Validate timeline index and identifier

  4. Verify monitor indices

  5. Timeline Section Management

  6. Locate target timeline section
  7. Validate section exists and can accept wallpaper

  8. Check for existing wallpapers on target monitors

  9. Wallpaper State Handling

  10. If timeline section is active: 
    for (auto& activeWallpaper : activeTimeline->activeWallpaperList) {
    if (activeWallpaper->monitors() == wallpaperData.monitors()) {
        if (isSameWallpaperRuntime(activeWallpaper->type(), wallpaperData.type())) {
            // Replace content in existing wallpaper
            activeWallpaper->replace(wallpaperData);
        } else {
            // Remove and restart with new type
            await removeWallpaper(wallpaperData.monitors().first());
            await startWallpaper(wallpaperData);
        }
    }
}

  11. If timeline section is inactive:

    • Store wallpaper data for later activation

  12. UI Updates

  13. Update monitor list model
  14. Refresh timeline visualization

  15. Trigger UI updates for affected monitors

  16. Persistence

  17. If saveToProfiles is true:
    • Update profiles configuration
    • Write changes to disk
    • Emit save confirmation

2. Removing a Wallpaper

Entry Point

removeWallpaperAt(
    timelineIndex,      // Timeline section index
    sectionIdentifier,  // Section identifier
    monitorIndex        // Target monitor
)

Internal Flow

  1. Section Location 

    auto section = wallpaperSection(timelineIndex, sectionIdentifier);
if (!section) {
    return false;
}

  2. Active Wallpaper Handling

  3. If section is active:

    • Stop wallpaper process
    • Wait for SDK disconnection
    • Clean up resources
    • Update active wallpaper list

  4. Data Cleanup

  5. Remove wallpaper data from section
  6. Update monitor assignments

  7. Clean up any orphaned references

  8. State Synchronization

  9. Update monitor model data
  10. Refresh timeline section data
  11. Trigger UI updates

3. Timeline Modification

Entry Point

moveTimelineAt(
    index,             // Timeline index
    identifier,        // Section identifier
    relativePosition,  // New position (0-1)
    positionTimeString // Time string (HH:MM:SS)
)

Internal Flow

  1. Time Validation 

    const QTime newPositionTime = QTime::fromString(positionTimeString, "hh:mm:ss");
if (!newPositionTime.isValid()) {
    return false;
}

  2. Timeline Updates

  3. Update section end time
  4. Update relative position

  5. Adjust adjacent section times

  6. Section Validation

  7. Ensure continuous coverage
  8. Verify no overlaps

  9. Check time constraints 

    validateTimelineSections();

  10. Active Wallpaper Management

  11. Check if change affects active section
  12. Handle wallpaper state transitions

  13. Update active wallpaper timings

  14. State Persistence

  15. Update timeline model
  16. Save timeline configuration
  17. Emit timeline update events

Important Considerations

Error Handling

  • All operations should handle failures gracefully
  • Maintain system state consistency
  • Provide meaningful error messages
  • Roll back partial changes on failure

Async Operations

  • Use QCoro tasks for async operations
  • Properly await completion of all async tasks
  • Handle cancellation and timeouts
  • Maintain state during async transitions

State Management

  • Track current timeline section state
  • Monitor wallpaper process health
  • Handle SDK connection lifecycle
  • Manage resource cleanup

Timeline Integrity

  • Maintain continuous coverage (00:00:00 to 23:59:59)
  • Prevent overlapping sections
  • Validate all time boundaries
  • Ensure proper section ordering