Module matrix_sdk_ui::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. Apart from that, one can apply Inputs on the state machine, like notifying that the client app viewport of the room list has changed (if the user of the client app has scrolled in the room list for example) etc.

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

Basic principle

RoomListService works with 2 Sliding Sync List:

• all_rooms (referred by the constant ALL_ROOMS_LIST_NAME) is the main 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.
• visible_rooms (referred by the constant VISIBLE_ROOMS_LIST_NAME) is the “reactive” list. Its goal is to react to the client app user actions. If the user scrolls in the room list, the visible_rooms will be configured to sync for the particular range of rooms the user is actually seeing (the rooms in the current viewport). visible_rooms has a different configuration than all_rooms as it loads more timeline events: it means that the room will already have a “history”, a timeline, ready to be presented when the user enters the room.

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 provides a way to get a stream of room list entry. This stream 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.

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.

Enums

• Error
  RoomList’s errors.
• Input
  An input for the RoomList’ state machine.
• InputResult
  An Input Ok result: whether it’s been applied, or ignored.
• RoomListEntry
  Represent a room entry in the SlidingSyncList.
• RoomListLoadingState
  The loading state of a RoomList.
• State
  The state of the super::RoomList’ state machine.
• 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
• VISIBLE_ROOMS_DEFAULT_RANGE
  Default range for the VISIBLE_ROOMS_LIST_NAME list.
• VISIBLE_ROOMS_DEFAULT_TIMELINE_LIMIT
  Default timeline for the VISIBLE_ROOMS_LIST_NAME list.
• VISIBLE_ROOMS_LIST_NAME

Type Aliases

• BoxedFilterFn
  Type alias for a boxed filter function.