Struct matrix_sdk_ui::timeline::Timeline

pub struct Timeline { /* private fields */ }

A high-level view into a regular¹ room’s contents.

¹ This type is meant to be used in the context of rooms without a room_type, that is rooms that are primarily used to exchange text messages.

Implementations

impl Timeline

pub async fn paginate_backwards(&self, num_events: u16) -> Result<bool, Error>

Add more events to the start of the timeline.

Returns whether we hit the start of the timeline.

pub async fn focused_paginate_forwards( &self, num_events: u16 ) -> Result<bool, Error>

Assuming the timeline is focused on an event, starts a forwards pagination.

Returns whether we hit the end of the timeline.

pub async fn focused_paginate_backwards( &self, num_events: u16 ) -> Result<bool, Error>

Assuming the timeline is focused on an event, starts a backwards pagination.

Returns whether we hit the start of the timeline.

pub async fn live_paginate_backwards(&self, batch_size: u16) -> Result<bool>

Paginate backwards in live mode.

This can only be called when the timeline is in live mode, not focused on a specific event.

Returns whether we hit the start of the timeline.

pub fn back_pagination_status( &self ) -> (PaginatorState, impl Stream<Item = PaginatorState>)

Subscribe to the back-pagination status of the timeline.

Note: this may send multiple Paginating/Idle sequences during a single call to Self::paginate_backwards().

impl Timeline

pub fn builder(room: &Room) -> TimelineBuilder

Create a new TimelineBuilder for the given room.

pub fn room(&self) -> &Room

Returns the room for this timeline.

pub async fn clear(&self)

Clear all timeline items.

pub async fn retry_decryption<S: Into<String>>( &self, session_ids: impl IntoIterator<Item = S> )

Retry decryption of previously un-decryptable events given a list of session IDs whose keys have been imported.

Examples

let path = PathBuf::from("/home/example/e2e-keys.txt");
let result =
    client.encryption().import_room_keys(path, "secret-passphrase").await?;

// Given a timeline for a specific room_id
if let Some(keys_for_users) = result.keys.get(room_id) {
    let session_ids = keys_for_users.values().flatten();
    timeline.retry_decryption(session_ids).await;
}

pub async fn item_by_event_id( &self, event_id: &EventId ) -> Option<EventTimelineItem>

Get the current timeline item for the given event ID, if any.

It’s preferable to store the timeline items in the model for your UI, if possible, instead of just storing IDs and coming back to the timeline object to look up items.

pub async fn latest_event(&self) -> Option<EventTimelineItem>

Get the latest of the timeline’s event items.

pub async fn subscribe( &self ) -> (Vector<Arc<TimelineItem>>, impl Stream<Item = VectorDiff<Arc<TimelineItem>>>)

Get the current timeline items, and a stream of changes.

You can poll this stream to receive updates. See futures_util::StreamExt for a high-level API on top of Stream.

pub async fn subscribe_batched( &self ) -> (Vector<Arc<TimelineItem>>, impl Stream<Item = Vec<VectorDiff<Arc<TimelineItem>>>>)

Get the current timeline items, and a batched stream of changes.

In contrast to subscribe, this stream can yield multiple diffs at once. The batching is done such that no arbitrary delays are added.

pub async fn send(&self, content: AnyMessageLikeEventContent)

Send a message to the room, and add it to the timeline as a local echo.

For simplicity, this method doesn’t currently allow custom message types.

If the encryption feature is enabled, this method will transparently encrypt the room message if the room is encrypted.

If sending the message fails, the local echo item will change its send_state to EventSendState::SendingFailed.

Arguments

• content - The content of the message event.

pub async fn send_reply( &self, content: RoomMessageEventContentWithoutRelation, reply_item: &EventTimelineItem, forward_thread: ForwardThread ) -> Result<(), UnsupportedReplyItem>

Send a reply to the given event.

Currently it only supports events with an event ID and JSON being available (which can be removed by local redactions). This is subject to change. Please check EventTimelineItem::can_be_replied_to to decide whether to render a reply button.

The sender of reply_item will be added to the mentions of the reply if and only if reply_item has not been written by the sender.

Arguments

• content - The content of the reply

• reply_item - The event item you want to reply to

• forward_thread - Usually Yes, unless you explicitly want to the reply to show up in the main timeline even though the reply_item is part of a thread

pub async fn edit( &self, new_content: RoomMessageEventContentWithoutRelation, edit_item: &EventTimelineItem ) -> Result<(), UnsupportedEditItem>

Send an edit to the given event.

Currently only supports m.room.message events whose event ID is known. Please check EventTimelineItem::can_be_edited before calling this.

Arguments

• new_content - The content of the reply

• edit_item - The event item you want to edit

pub async fn edit_poll( &self, fallback_text: impl Into<String>, poll: UnstablePollStartContentBlock, edit_item: &EventTimelineItem ) -> Result<(), UnsupportedEditItem>

pub async fn toggle_reaction( &self, annotation: &Annotation ) -> Result<(), Error>

Toggle a reaction on an event

Adds or redacts a reaction based on the state of the reaction at the time it is called.

When redacting an event, the redaction reason is not sent.

Ensures that only one reaction is sent at a time to avoid race conditions and spamming the homeserver with requests.

pub fn send_attachment( &self, path: impl Into<PathBuf>, mime_type: Mime, config: AttachmentConfig ) -> SendAttachment<'_>

Sends an attachment to the room. It does not currently support local echoes

If the encryption feature is enabled, this method will transparently encrypt the room message if the room is encrypted.

Arguments

• path - The path of the file to be sent

• mime_type - The attachment’s mime type

• config - An attachment configuration object containing details about the attachment

like a thumbnail, its size, duration etc.

pub async fn retry_send(&self, txn_id: &TransactionId) -> Result<(), Error>

Retry sending a message that previously failed to send.

Arguments

• txn_id - The transaction ID of a local echo timeline item that has a send_state() of SendState::FailedToSend { .. }

pub async fn cancel_send(&self, txn_id: &TransactionId) -> bool

Discard a local echo for a message that failed to send.

Returns whether the local echo with the given transaction ID was found.

Argument

• txn_id - The transaction ID of a local echo timeline item that has a send_state() of SendState::FailedToSend { .. }. Note: A send state of SendState::NotYetSent might be supported in the future as well, but there can be no guarantee for that actually stopping the event from reaching the server.

pub async fn fetch_details_for_event( &self, event_id: &EventId ) -> Result<(), Error>

Fetch unavailable details about the event with the given ID.

This method only works for IDs of remote EventTimelineItems, to prevent losing details when a local echo is replaced by its remote echo.

This method tries to make all the requests it can. If an error is encountered for a given request, it is forwarded with the TimelineDetails::Error variant.

Arguments

• event_id - The event ID of the event to fetch details for.

Errors

Returns an error if the identifier doesn’t match any event with a remote echo in the timeline, or if the event is removed from the timeline before all requests are handled.

pub async fn fetch_members(&self)

Fetch all member events for the room this timeline is displaying.

If the full member list is not known, sender profiles are currently likely not going to be available. This will be fixed in the future.

If fetching the members fails, any affected timeline items will have the sender_profile set to TimelineDetails::Error.

pub async fn latest_user_read_receipt( &self, user_id: &UserId ) -> Option<(OwnedEventId, Receipt)>

Get the latest read receipt for the given user.

Contrary to Room::load_user_receipt() that only keeps track of read receipts received from the homeserver, this keeps also track of implicit read receipts in this timeline, i.e. when a room member sends an event.

pub async fn latest_user_read_receipt_timeline_event_id( &self, user_id: &UserId ) -> Option<OwnedEventId>

Get the ID of the timeline event with the latest read receipt for the given user.

In contrary to Self::latest_user_read_receipt(), this allows to know the position of the read receipt in the timeline even if the event it applies to is not visible in the timeline, unless the event is unknown by this timeline.

pub async fn send_single_receipt( &self, receipt_type: ReceiptType, thread: ReceiptThread, event_id: OwnedEventId ) -> Result<bool>

Send the given receipt.

This uses Room::send_single_receipt internally, but checks first if the receipt points to an event in this timeline that is more recent than the current ones, to avoid unnecessary requests.

Returns a boolean indicating if it sent the request or not.

pub async fn send_multiple_receipts(&self, receipts: Receipts) -> Result<()>

Send the given receipts.

This uses Room::send_multiple_receipts internally, but checks first if the receipts point to events in this timeline that are more recent than the current ones, to avoid unnecessary requests.

pub async fn mark_as_read(&self, receipt_type: ReceiptType) -> Result<bool>

Mark the room as read by sending an unthreaded read receipt on the latest event, be it visible or not.

This works even if the latest event belongs to a thread, as a threaded reply also belongs to the unthreaded timeline. No threaded receipt will be sent here (see also #3123).

Returns a boolean indicating if we sent the request or not.

Trait Implementations

impl Debug for Timeline

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.