CardGridView.py PySideAbdhUI — Card Grid with Infinite Scroll & Selection

Creates a card wrapping the given widget. The widget is stored as self.widget for later access and replacement. The selection state is initialized to False, and setup_ui() is called to build the visual structure.

Emitted when the card receives a mouse press event. The signal carries a reference to the CardWidget instance itself (as a QWidget type), allowing the receiving slot to identify which card was clicked. The CardGridView connects this signal to its select_card() method to implement single-selection semantics.

Constructs the card's visual structure. A QGridLayout with 2px margins and 2px spacing is created. Two widgets are placed at position [0,0]:

1. background_layer: A QWidget with CSS class card that serves as the visual background. Its class changes to card-selected when selected.
2. widget: The user-provided widget, placed at the same grid position so it overlaps the background layer.

The mouse press event is redirected by assigning self.mousePressEvent = self._on_click, which means any default mousePressEvent behavior from QWidget is completely replaced. This ensures clicks anywhere on the card (including on the user widget) are captured.

Click handler that emits the clicked signal with self as the argument. This method is assigned to self.mousePressEvent in setup_ui(), replacing the default event handler. The event parameter (a QMouseEvent) is received but not used — the handler does not distinguish between left, right, or middle mouse button clicks.

Replaces the current user widget inside the card with a new one. The old widget is removed from the layout, detached from its parent (setParent(None) is implicit via deleteLater()), and scheduled for deletion. The new widget is stored as self.widget and added to the card's layout at the same position. The background layer remains untouched — only the user content is swapped.

Toggles the card's visual selection state. When toggled to selected, the background layer's CSS class changes from card to card-selected. When toggled to deselected, it reverts to card. After changing the property, the style system is forced to re-evaluate by manually unpolishing and re-polishing the background layer's style:

self.background_layer.style().unpolish(self.background_layer)
self.background_layer.style().polish(self.background_layer)

This unpolish/re-polish pattern is necessary because Qt's style sheet engine caches property-based selectors. Simply changing a property value does not automatically trigger a style re-evaluation — the engine must be explicitly told to re-apply the style sheet rules to the widget.

Initializes the grid view with a default 2-column layout. The constructor calls setup_ui() to build the visual structure, then initializes the internal state variables for card tracking, selection, and infinite-scroll management.

Internal State

Emitted when a card is selected (clicked). The signal carries the inner widget of the selected card (i.e., card.widget, not the CardWidget itself). This gives the receiver direct access to the user-defined content of the selected card, which is typically what application code needs to react to.

Emitted when a card is removed from the grid. The signal carries the inner widget of the removed card, allowing the receiver to perform cleanup or update other UI elements in response to the removal.

Emitted when the infinite-scroll system detects that more data should be loaded (either because the user scrolled near the bottom or the "Load More" button was clicked). The parent should connect to this signal, fetch additional data, and call add_card() for each new item. After adding, the parent should call hide_loading_indicator() to clear the loading state. If no more data is available, the parent should set has_more = False.

Constructs the complete visual structure of the grid view. The layout hierarchy is as follows:

1. Outer layout: A QVBoxLayout with zero margins fills the entire CardGridView widget.
2. Scroll area: A QScrollArea with setWidgetResizable(True) so the container stretches to fill the available width. Both horizontal and vertical scroll bars are set to ScrollBarAsNeeded.
3. Container widget: A plain QWidget with CSS class surface-background-layer that holds the grid layout. This provides the visual background for the card area.
4. Grid layout: A QGridLayout with 2px spacing and 3px margins where cards are placed.

Three auxiliary UI elements are created but initially hidden:

• loading_label: A QLabel with text "Loading more items..." styled in gray, centered, with 20px padding. Shown during infinite-scroll loading.
• load_more_button: A QPushButton with text "Load More" and a pointing hand cursor. Provides an optional manual trigger for loading more data. Note: the click connection is commented out in the source.
• empty_label: A QLabel with text "No results found." styled in 18px gray, centered, with 50px padding. Shown when the grid has no cards.

The scroll area's vertical scrollbar valueChanged signal is connected to on_scroll_changed() to implement infinite-scroll detection.

Adds a new card to the grid. The card is created by wrapping the provided widget in a CardWidget, which is then connected to the grid's selection handler (select_card). The grid position is calculated based on the current number of cards in the dictionary and the column count: row = count // columns, col = count % columns. The card is stored in the cards dictionary by its ID and added to the grid layout at the calculated position.

If a card with the same ID already exists, a ValueError is raised to prevent duplicate IDs from corrupting the dictionary.

Replaces the inner widget of an existing card with a new widget. The card's position in the grid and its selection state are preserved — only the user content is swapped. This is more efficient than removing and re-adding a card, which would require reorganizing the entire grid.

Retrieves the inner user widget of a card by its ID. This returns the widget that was passed to add_card(), not the CardWidget wrapper. Use this to access or modify the content of a specific card.

Returns a list of all inner user widgets in the grid, in dictionary insertion order (which, for Python 3.7+, is the order in which cards were added). This is useful for batch operations like iterating over all card contents.

Removes a card from the grid by its ID. The removal process involves several steps:

1. If the card is currently selected, selected_card is reset to None.
2. The card widget is removed from the grid layout and scheduled for deletion via deleteLater().
3. The card is removed from the cards dictionary.
4. All remaining cards are reorganized in the grid via _reorganize_cards() to fill the gap left by the removed card.
5. The card_removed signal is emitted with the removed card's inner widget.
6. UI helper elements (loading indicator, load more button, empty message) are hidden.

Implements single-selection semantics for the grid. When a card is clicked:

1. If another card was previously selected, its selection is toggled off (CSS class reverts to card).
2. The clicked card's selection is toggled on (CSS class changes to card-selected).
3. The selected_card reference is updated to the clicked card.
4. The card_selected signal is emitted with the card's inner widget.

This method is automatically connected to each CardWidget.clicked signal when the card is added via add_card(). It can also be called programmatically to select a specific card.

Connected to the vertical scrollbar's valueChanged signal. Checks two guard conditions: if has_more is False (all data loaded) or is_loading is True (request already in progress), the method returns immediately. Otherwise, it calculates whether the current scroll position is within load_threshold pixels of the maximum scroll position. If so, load_next_page() is called to trigger the next data load.

Handler for the "Load More" button click. Delegates to load_next_page(). Note that the connection to this handler is commented out in the source code, so this method currently has no effect unless manually connected.

Initiates the next data load cycle. Checks has_more and is_loading guards, then shows the loading indicator and emits the load_more_requested signal. The parent component should respond to this signal by fetching additional data, adding cards via add_card(), and then calling hide_loading_indicator() to clear the loading state.

show_loading_indicator() displays the "Loading more items..." label at the bottom of the grid. If the label has not yet been added to the layout (parent() is None), it is inserted at the next available row spanning all columns. The is_loading flag is set to True.

hide_loading_indicator() hides the label and resets is_loading to False, allowing subsequent scroll-triggered loads to proceed. This method must be called by the parent after data has been loaded and added to the grid.

show_load_more_button() displays the "Load More" button at the bottom of the grid. If the button has not yet been added to the layout, it is inserted at the next available row spanning all columns. This provides a manual fallback for loading more data when infinite scroll is not desired or not working.

hide_load_more_button() hides the button. Both methods simply toggle visibility without removing the widget from the layout.

show_empty_message() displays a centered empty-state message at the bottom of the grid. The message text is customizable via the message parameter, defaulting to "No results found." If the label has not yet been added to the layout, it is inserted at the next available row spanning all columns.

hide_empty_message() hides the empty state label.

Resets the grid view to its initial state for a new data set. This is typically called before starting a new search or refreshing the entire card list. The method performs the following steps:

1. Calls clear() to remove all cards and reset UI elements.
2. Sets has_more = True to re-enable infinite scroll.
3. Sets is_loading = False to clear any stuck loading state.
4. Scrolls the scrollbar back to the top (value = 0).

Removes all cards and auxiliary UI elements from the grid. The method iterates through all items in the grid layout, removes each widget from its parent, and schedules it for deletion via deleteLater(). The cards dictionary is not explicitly cleared here, but all widget references become invalid after deletion. The selected_card is reset to None, and all UI helper elements (loading indicator, load more button, empty message) are hidden.

Changes the number of columns in the grid and reorganizes all existing cards to fit the new layout. The column count must be at least 1; a ValueError is raised for invalid values. After updating self.columns, _reorganize_cards() is called to recalculate the grid positions of all cards.

Recalculates and reassigns grid positions for all cards based on their order in the cards dictionary and the current column count. Each card's position is calculated as row = index // columns, col = index % columns. The method calls addWidget() for each card, which automatically moves existing widgets to their new positions within the grid layout.

This method is called after a card is removed (to fill the gap) or after the column count is changed (to reflow the entire grid). The dictionary iteration order determines the visual order of cards in the grid.