Section layout managers
To simplify implementation the Slm should be stateless itself, instead tracking state through values passed at each call. This will also make testing far easier.
Section layout managers (Slms) implement the SectionLayoutManager interface. The role of the Slm is to layout a section, and fill or trim the ends of a scrolling section. The Slm interacts with the recycler view through the LayoutHelper, this helper maintains a virtual coordinate space which abstracts the various configurations offered by SuperSLiM. In other words, the Slm only deals with a vertically scrolling space. The origin of the virtual space is adjusted per the actual op being called on the Slm. The layout state of a section lives separate from the section state, and is passed as the third parameter to each call.
As Slms are stateless static classes and are unknown to SuperSLiM, calling into the Slm is through an implementation of SectionState offered by the total Slm package. The SectionState is instantiated indirectly when creating sections. SuperSLiM does this through a factory, an implementation of the SectionConfig interface, passed into the adapter as an optional parameter of createSection.
createSection(id, header, slmConfig)This design separates the concerns of data, state, and configuration. It also makes extending SuperSLiM with third party Slms extremely easy and robust. It doesn't force a second interface for Slms to be added to SuperSLiM either, as in previous versions.
It is important to note that scrolling is a composite activity, and is not performed as a direct action by the Slm. Scrolling is performed in stages by SuperSLiM, with fill and trim operations performed as appropriate on the sections which intersect the leading and trailing edges of the displayed area.
Layout always starts with the section anchor, the head position. The default value is -1, which means that it should be interpreted as 0 for any layout pass; interpretation differs for the trim and fill operations. The layout helper informs the Slm as to the constraints of the view, things like the width, height and other variables. The Slm uses the helper to query section items, and to add them to the recycler view. The section state functions as an analogue for the section. The layout state setups up the initial conditions of the layout, such as the head position. When the layout is finished, the layout state is used to record the new state. Head position should be unchanged, but tail position, number of views, and other state properties will have changed.
Padding can be set on every section with the root section taking its padding from the recycler view. Padding is handled inside the layout helper as an offset to the layout origin. However, there are two complications. 1) Cold layout passes must fill the padded area. 2) fillTop must ensure it fills the padded area in addition to dy.
The cold layout is when there is no prior layout state; optionally there can be a requested position. To achieve this the layout helper inserts a fillTop call immediately after each layout. This does not happen on layoutContent, only the top level call. The fillTop call must be careful to honour appearing and disappearing animations.
Ths is for extending the displayed area above a section. It must attempt to fill requested vertical distance, dy, and possibly a padded area. If dy cannot be filled it is because there is no more content to fill the area. Also passed as parameters are the section data and current layout state.
It is important to note that the origin is not necessarily the top of the section. Top records the present top of the section. It must be updated after each fill. Top is always a value between between 0 and padding. This interacts with overdraw, which is the area before top into which has been 'drawn'. As an example; for LinearSlm the real top of the section is 0 - top - overdraw, while the displayed top is 0 - top. There is second relationship between overdraw and top; overdraw > 0 if and only if top = padding.
There are three possible scenarios for the fill op:
-
The section does not need to fill any more content, however, it might have overdraw. The overdraw is returned as filled area for each successive fill op until the overdraw has been fully consumed.
-
The section is mid-content and must lay out more content to fill the area. This may also have overdraw from previous layout passes or fill ops. The overdraw should be consumed until there is a need to layout more content to fill. When the content is laid out it may extend beyond dy, the extra distance is overdraw.
-
The section is not yet present, and so it is logically at the bottom of the content. The fill op should correctly interpret the default values of the layout state in this manner. The layout should then begin the fill op from the end of the content. Otherwise this is no different from case 2.
The side effects of the fill op are two fold. Views representing content are indirectly attached to the recycler view through the layout helper. Also, the layout state is updated to reflect the actions taken. The properties should be updated with each fill op; headPosition, numViews, top, and overdraw. For this op, tailPosition should be untouched, except for case 3, where it should be set to the last item in the section.
This is the reverse of fill top. There are three different scenarios in to which the op enters.
- The end of content has already been reached.
- The section is mid-content.
- The section is not yet present, and fills from the beginning of the content.
Each of these situations interacts with overdraw in the same manner as fill top. The only significant difference is the opposite direction of filling, and the reversed roles of headPosition and tailPosition. Refer to fill top for greater detail.
The top edge of the section is to be trimmed. Any items that are wholly before the 0 edge should be considered for removal. The only items that should remain are those that are partly after 0, or are after the new head item. The overdraw value should be adjusted, the extact interpretation of this overdraw value is up to the Slm, and additional state specific to the Slm can be recorded into layout state. Num views, and head position should be updated, as well as any other affected state properties.
Functionally the same as trim top, except it is trimming the bottom. Num views, and tail position should be updated, as well as any other affected properties.
