Class MasonryGridView
A GridView that arranges items in a masonry layout pattern, similar to Pinterest's layout.
Inheritance
Implements
Inherited Members
Namespace: Unity.AppUI.UI
Assembly: Unity.AppUI.dll
Syntax
[UxmlElement]
public class MasonryGridView : BaseGridView, IEventHandler, IResolvedStyle, ITransform, ITransitionAnimations, IExperimentalFeatures, IVisualElementScheduler, IBindable, ISerializationCallbackReceiverRemarks
The MasonryGridView is a specialized grid layout component that arranges items in a vertical masonry pattern. Unlike traditional grid layouts where items must conform to a fixed grid, the masonry layout allows items of varying heights while maintaining aligned columns.
This layout is particularly useful for displaying content of varying heights, such as images, cards, or content blocks, in a visually appealing and space-efficient manner.
Key features include:
- Dynamic column arrangement
- Support for items with varying heights
- Efficient item recycling for optimal performance
- Built-in selection management
- Smooth scrolling with viewport item management
Examples
Basic setup of a MasonryGridView with custom items:
Creating and configuring a MasonryGridView
var masonryGrid = new MasonryGridView() {
columnCount = 3,
selectionType = SelectionType.Single,
pack = true
};
// Setup item source
masonryGrid.itemsSource = items;
// Define how items are created
masonryGrid.makeItem = () => new CustomItemElement();
// Define how items are bound
masonryGrid.bindItem = (element, index) => {
var item = (CustomItemElement)element;
item.SetData(itemsSource[index]);
};
Using MasonryGridView in UXML:
UXML definition of a MasonryGridView
<ui:UXML xmlns:ui="UnityEngine.UIElements">
<ui:MasonryGridView
column-count="3"
selection-type="Multiple"
pack="true"
style="height: 100%;" />
</ui:UXML>Handling selection changes:
Setting up selection event handlers
masonryGrid.selectionChanged += (selectedItems) => {
foreach (var item in selectedItems) {
Debug.Log($"Selected item: {item}");
}
};
masonryGrid.itemsChosen += (chosenItems) => {
// Handle double-click or Enter key on selected items
foreach (var item in chosenItems) {
Debug.Log($"Chosen item: ");
}
};
Constructors
MasonryGridView()
Constructs a new MasonryGridView.
Declaration
public MasonryGridView()Fields
columnContainerUssClassName
The column container USS class name of a MasonryGridView.
Declaration
public static readonly string columnContainerUssClassNameField Value
| Type | Description |
|---|---|
| string |
columnUssClassName
The columns USS class name of a MasonryGridView.
Declaration
public static readonly string columnUssClassNameField Value
| Type | Description |
|---|---|
| string |
masonryGridViewUssClassName
The USS class name of a MasonryGridView.
Declaration
public static readonly string masonryGridViewUssClassNameField Value
| Type | Description |
|---|---|
| string |
Properties
pack
Whether to pack the items (the grid will try to take the minimum space possible by distributing the items in the columns).
Declaration
[CreateProperty]
[UxmlAttribute]
public bool pack { get; set; }Property Value
| Type | Description |
|---|---|
| bool |
Methods
ApplySelectedState()
Set the selected visual state on items.
Declaration
protected override void ApplySelectedState()Overrides
GetIndexByWorldPosition(Vector2)
Returns the index of the item at the given position.
Declaration
public override int GetIndexByWorldPosition(Vector2 worldPosition)Parameters
| Type | Name | Description |
|---|---|---|
| Vector2 | worldPosition | The position of the item in the world-space. |
Returns
| Type | Description |
|---|---|
| int | The index of the item at the given position. |
Overrides
Remarks
The position is relative to the top left corner of the grid. No check is made to see if the index is valid.
GetVisualElementInternal(int)
Implement this method to return the VisualElement at the specified index.
Declaration
protected override VisualElement GetVisualElementInternal(int index)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | The index of the VisualElement to return. |
Returns
| Type | Description |
|---|---|
| VisualElement | The VisualElement at the specified index. |
Overrides
OnContainerHeightChanged(float)
Callback called when the ScrollView container height changes.
Declaration
protected override void OnContainerHeightChanged(float height)Parameters
| Type | Name | Description |
|---|---|---|
| float | height | The new height of the container. |
Overrides
OnCustomStyleResolved(CustomStyleResolvedEvent)
Method to implement to handle the custom style resolved event.
Declaration
protected override void OnCustomStyleResolved(CustomStyleResolvedEvent e)Parameters
| Type | Name | Description |
|---|---|---|
| CustomStyleResolvedEvent | e | The custom style resolved event. |
Overrides
OnScroll(float)
Callback called when the scroll value changes.
Declaration
protected override void OnScroll(float offset)Parameters
| Type | Name | Description |
|---|---|---|
| float | offset | The new scroll offset. |
Overrides
Remarks
You can also call this method one frame your Refresh() implementation to ensure the visual state of the grid is updated correctly.
Refresh()
Clears the GridView, recreates all visible visual elements, and rebinds all items.
Declaration
public override void Refresh()Overrides
Remarks
Call this method whenever the data source changes.
ScrollToItem(int)
Scrolls to a specific item index and makes it visible.
Declaration
public override void ScrollToItem(int index)Parameters
| Type | Name | Description |
|---|---|---|
| int | index | Item index to scroll to. Specify -1 to make the last item visible. |