Module room_list_service

RoomListService API.

The RoomListService is a UI API dedicated to present a list of Matrix rooms to the user. The syncing is handled by SlidingSync. The idea is to expose a simple API to handle most of the client app use cases, like: Showing and updating a list of rooms, filtering a list of rooms, handling particular updates of a range of rooms (the ones the client app is showing to the view, i.e. the rooms present in the viewport) etc.

As such, the RoomListService works as an opinionated state machine. The states are defined by State. Actions are attached to the each state transition.

The API is purposely small. Sliding Sync is versatile. RoomListService is one specific usage of Sliding Sync.

Basic principle

RoomListService works with 1 Sliding Sync List:

• all_rooms (referred by the constant ALL_ROOMS_LIST_NAME) is the only list. Its goal is to load all the user’ rooms. It starts with a SlidingSyncMode::Selective sync-mode with a small range (i.e. a small set of rooms) to load the first rooms quickly, and then updates to a SlidingSyncMode::Growing sync-mode to load the remaining rooms “in the background”: it will sync the existing rooms and will fetch new rooms, by a certain batch size.

This behavior has proven to be empirically satisfying to provide a fast and fluid user experience for a Matrix client.

RoomListService::all_rooms provides a way to get a RoomList for all the rooms. From that, calling RoomList::entries_with_dynamic_adapters provides a way to get a stream of rooms. This stream is sorted, can be filtered, and the filter can be changed over time.

RoomListService::state provides a way to get a stream of the state machine’s state, which can be pretty helpful for the client app.

Modules

• filters
  A collection of room filters.
• sorters
  A collection of room sorters.

Structs

• Room
  A room in the room list.
• RoomList
  A RoomList represents a list of rooms, from a RoomListService.
• RoomListDynamicEntriesController
  Controller for the RoomList dynamic entries.
• RoomListService
  The RoomListService type. See the module’s documentation to learn more.
• StateMachine
  The state machine used to transition between the States.

Enums

• Error
  RoomList’s errors.
• RoomListLoadingState
  The loading state of a RoomList.
• State
  The state of the super::RoomList.
• SyncIndicator
  An hint whether a sync spinner/loader/toaster should be prompted to the user, indicating that the RoomListService is syncing.

Constants

• ALL_ROOMS_DEFAULT_GROWING_BATCH_SIZE
  Default batch_size for the growing sync-mode of the ALL_ROOMS_LIST_NAME list.
• ALL_ROOMS_DEFAULT_SELECTIVE_RANGE
  Default batch_size for the selective sync-mode of the ALL_ROOMS_LIST_NAME list.
• ALL_ROOMS_LIST_NAME