Glossary

This is a glossary of terms and concepts used within RecyclerView and SuperSLiM. Reading this document can be considered a good introduction to understanding SuperSLiM, how it is implemented, and how it interacts with RecyclerView.

General

Change animation

The recycler view's animation for changes in the data set. The initial conditions are set by the pre-layout pass, and the final state of each view change animation is given by the real-layout pass.

Pre-layout

RecyclerView.State.isPreLayout() == true
The role of the pre-layout pass is to set up the initial conditions of the change animation. The pre-layout pass lays-out regular on-screen views, on-screen disappearing views, and off-screen appearing views.

Real-layout*

RecyclerView.State.isPreLayout() == false
The second layout pass which gives the final position of views after any animations have run. The real-layout pass lays-out regular on-screen views, on-screen appearing views, and off-screen disappearing views.

Added views*

Added views are available for laying out in the real-layout pass.

Removed views

Removed views are returned from the scrap list in the pre-layout pass to help with correctly laying out the initial position of views affected by the change animation, especially appearing views. Removed views should not be added to the child list, they are only a positional aid.

Disappearing view

A view that is on-screen before being animated off-screen.
A disappearing view is laid out on-screen in the pre-layout pass, and is laid out off-screen in the real-layout.
In the post-layout pass the recycler view must be told the view is disappearing by calling addDisappearingView() on the layout manager.
Disappearing views are a result of either; the view being moved, or views being added before it, thus pushing it off-screen.

Appearing view

A view that is off-screen before being animated onto the screen.
An appearing view is laid out off-screen in the pre-layout pass, and is laid out on-screen in the real-layout.
An appearing view can be discovered by detecting views that will be removed after pre-layout, laying them out, but not accounting for the removed views in determining the visual limit of the layout pass; i.e., for a linear layout removed views count for zero height when being laid out, this is to the effect that 100 pixels of removed views results in at least 100 pixels of space being available for appearing views.

Scrap views

Views attached to the recycler view which are marked for removal or reuse.
When layout starts SuperSLiM removes and scraps all child views of the recycler view. When SLMs get views they may be reused from the scrap list or populated from the adapter. Scrap views are automatically removed from the scrap list when they are added back to the recycler view.
Scrap views remaining after the regular post-layout pass are views that were on-screen in the pre-layout pass. These scrap views are now either removed and should be ignored, or are disappearing views and are to be laid out off-screen.

Item decorator

Item decorators can inset child views and add extra content without complicating layout passes. Handling decorators correctly requires using helper methods with the child view as an argument rather than interacting with the child view directly.

Item changes

Changes to the data set are notified to the recycler view through a listener interface. The changes are propagated through to the layout manager by calls to onItemsAdded(), onItemsUpdated(), onItemsChanged(), onItemsMoved(), and onItemsRemoved(). The affected position and ranges are passed in these calls. If the change is outside of the currently laid out area the calls are made before the pre-layout pass.

Scroll event

A call to one to the scroll methods scrollVerticallyBy() or scrollHorizontallyBy(). Scroll distance is given in pixels and the result indicates overscroll.

Anchor position

Logically, the current position that the user has scrolled to. For touch scrolling, this is the adapter position of the view that is logically and visually closest to the reference edge. Alternatively, for focus based scrolling, which is assistive or keyboard driven, this is the position of the focused view.
The anchor position is updated after each scroll or focus event, or is directly modified by calls to scroll to or smooth scroll to a position.
The current position is retained through configuration changes and used to re-layout the content with that position as an anchor.

Anchor position offset

The distance from the reference edge that the view indicated by the anchor position is located. Use of this value allows for the logical recreation of the scrolled view after configuration changes.
This offset is updated each time the anchor position is updated.

Over scroll

When a layout pass displays less content than should have been. The visual effect is where the scrolled content is displayed with its bottom edge not aligned with the bottom padding edge or view edge, but further up the view instead. This is caused when items from the anchor position to the last item are laid out, but there is still space below the content and there are items before the anchor position. The solution is to detect this situation after a layout pass, adjust all the laid out views down to the correct position, and then fill in the revealed space.

SuperSLiM

Scroll layout

Scrolling in SuperSLiM is handled by moving all content on the screen and then laying out revealed content on the leading edge as a special scroll layout pass.

Scroll pre-trim

Before the scroll trim is performed, a scroll pre-trim pass is made on sections intersecting the trailing edge. Any special positioning of views after the scroll event can be made here. The base SectionLayoutManager implementation uses this to correctly reposition stickied headers on the up edge.

Scroll trim

After a scroll layout, any content wholly outside the trailing edge is trimmed.

Trim notification

When a view is trimmed due to a scroll, a notification is passed down the section hierarchy so that section layout managers can update any cached data about a section.

Section coordinate space

Each section has its own virtual space. Values in this space are transformed up the section graph to the root coordinate space used by the layout manager and the recycler view.

Config transformation

The layout manager is configured by the locale and user set values. A config transformation is applied to coordinates coming into and out of the recycler view. In this manner, it is easy to support different layout directions without custom logic in each section layout manager implementation.

Start edge

The 'left edge' of the layout managed area. For a RTL locale, this is actually the right edge.

End edge

The 'right edge' of the layout managed area. For a RTL locale, this is actually the left edge.

Reverse layout

Layout is typically performed from top left to bottom right, translated for locale differences. When reversed, the layout is performed from the bottom right to the top right.

Orientation

The orientation can be horizontal or vertical.

Stack from end

Views are laid out from the bottom to the top. The bottom edge is the reference edge for determining current position. Headers still appear at the top of the section.

Headers at end

Headers are positioned after the section content. This makes for a reversal of the sticky logic. Instead of sticking to the logical top of the section, they will stick to the logical bottom of the section.
Handled inside BaseSectionLayoutManager.

Configuration transformer

A function that transforms one coordinate system into another; i.e., turning the LTR, TTB coordinate system used by section layout managers, into the coordinate system used by a RTL recycler view - a configuration derived from the users locale.

Semi-real coordinate

A coordinate that has been transformed into a virtual coordinate by a configuration transformation, but is also not nested within another virtual coordinate space. In this manner the top edge of this space can be called the semi-real top, though it could actually be the left edge of a horizontally scrolling recycler view.