ffi: add bindings for the timeline focus mode and associated functions

Author: bnjbvr

bindings/matrix-sdk-ffi/src/room.rs

@@ -2,10 +2,11 @@ use std::sync::Arc;
 
 use anyhow::{Context, Result};
 use matrix_sdk::{
+    event_cache::paginator::PaginatorError,
     room::{power_levels::RoomPowerLevelChanges, Room as SdkRoom, RoomMemberRole},
     RoomMemberships, RoomState,
 };
-use matrix_sdk_ui::timeline::RoomExt;
+use matrix_sdk_ui::timeline::{PaginationError, RoomExt, TimelineFocus};
 use mime::Mime;
 use ruma::{
     api::client::room::report_content,
@@ -30,7 +31,7 @@ use crate::{
     room_info::RoomInfo,
     room_member::RoomMember,
     ruma::ImageInfo,
-    timeline::{EventTimelineItem, ReceiptType, Timeline},
+    timeline::{EventTimelineItem, FocusEventError, ReceiptType, Timeline},
     utils::u64_to_uint,
     TaskHandle,
 };
@@ -167,6 +168,48 @@ impl Room {
         }
     }
 
+    /// Returns a timeline focused on the given event.
+    ///
+    /// Note: this timeline is independent from that returned with
+    /// [`Self::timeline`], and as such it is not cached.
+    pub async fn timeline_focused_on_event(
+        &self,
+        event_id: String,
+        num_context_events: u16,
+        internal_id_prefix: Option<String>,
+    ) -> Result<Arc<Timeline>, FocusEventError> {
+        let parsed_event_id = EventId::parse(&event_id).map_err(|err| {
+            FocusEventError::InvalidEventId { event_id: event_id.clone(), err: err.to_string() }
+        })?;
+
+        let room = &self.inner;
+
+        let mut builder = matrix_sdk_ui::timeline::Timeline::builder(room);
+
+        if let Some(internal_id_prefix) = internal_id_prefix {
+            builder = builder.with_internal_id_prefix(internal_id_prefix);
+        }
+
+        let timeline = match builder
+            .with_focus(TimelineFocus::Event { target: parsed_event_id, num_context_events })
+            .build()
+            .await
+        {
+            Ok(t) => t,
+            Err(err) => {
+                if let matrix_sdk_ui::timeline::Error::PaginationError(
+                    PaginationError::Paginator(PaginatorError::EventNotFound(..)),
+                ) = err
+                {
+                    return Err(FocusEventError::EventNotFound { event_id: event_id.to_string() });
+                }
+                return Err(FocusEventError::Other { msg: err.to_string() });
+            }
+        };
+
+        Ok(Timeline::new(timeline))
+    }
+
     pub fn display_name(&self) -> Result<String, ClientError> {
         let r = self.inner.clone();
         RUNTIME.block_on(async move { Ok(r.display_name().await?.to_string()) })
@@ -237,7 +280,8 @@ impl Room {
             }
         }
 
-        // Otherwise, fallback to the classical path.
+        // Otherwise, create a synthetic [`EventTimelineItem`] using the classical
+        // [`Room`] path.
         let latest_event = match self.inner.latest_event() {
             Some(latest_event) => matrix_sdk_ui::timeline::EventTimelineItem::from_latest_event(
                 self.inner.client(),
@@ -249,6 +293,7 @@ impl Room {
             .map(Arc::new),
             None => None,
         };
+
         Ok(RoomInfo::new(&self.inner, avatar_url, latest_event).await?)
     }
 

bindings/matrix-sdk-ffi/src/timeline/mod.rs

@@ -22,7 +22,7 @@ use matrix_sdk::attachment::{
     AttachmentConfig, AttachmentInfo, BaseAudioInfo, BaseFileInfo, BaseImageInfo,
     BaseThumbnailInfo, BaseVideoInfo, Thumbnail,
 };
-use matrix_sdk_ui::timeline::{BackPaginationStatus, EventItemOrigin, Profile, TimelineDetails};
+use matrix_sdk_ui::timeline::{EventItemOrigin, PaginationStatus, Profile, TimelineDetails};
 use mime::Mime;
 use ruma::{
     events::{
@@ -162,7 +162,7 @@ impl Timeline {
 
     pub fn subscribe_to_back_pagination_status(
         &self,
-        listener: Box<dyn BackPaginationStatusListener>,
+        listener: Box<dyn PaginationStatusListener>,
     ) -> Result<Arc<TaskHandle>, ClientError> {
         let mut subscriber = self.inner.back_pagination_status();
 
@@ -176,11 +176,18 @@ impl Timeline {
         }))))
     }
 
-    /// Loads older messages into the timeline.
+    /// Paginate backwards, whether we are in focused mode or in live mode.
     ///
-    /// Raises an exception if there are no timeline listeners.
-    pub fn paginate_backwards(&self, opts: PaginationOptions) -> Result<(), ClientError> {
-        RUNTIME.block_on(async { Ok(self.inner.paginate_backwards(opts.into()).await?) })
+    /// Returns whether we hit the end of the timeline or not.
+    pub async fn paginate_backwards(&self, num_events: u16) -> Result<bool, ClientError> {
+        Ok(self.inner.paginate_backwards(num_events).await?)
+    }
+
+    /// Paginate forwards, when in focused mode.
+    ///
+    /// Returns whether we hit the end of the timeline or not.
+    pub async fn paginate_forwards(&self, num_events: u16) -> Result<bool, ClientError> {
+        Ok(self.inner.focused_paginate_forwards(num_events).await?)
     }
 
     pub fn send_read_receipt(
@@ -573,6 +580,18 @@ impl Timeline {
     }
 }
 
+#[derive(Debug, thiserror::Error, uniffi::Error)]
+pub enum FocusEventError {
+    #[error("the event id parameter {event_id} is incorrect: {err}")]
+    InvalidEventId { event_id: String, err: String },
+
+    #[error("the event {event_id} could not be found")]
+    EventNotFound { event_id: String },
+
+    #[error("error when trying to focus on an event: {msg}")]
+    Other { msg: String },
+}
+
 #[derive(uniffi::Record)]
 pub struct RoomTimelineListenerResult {
     pub items: Vec<Arc<TimelineItem>>,
@@ -585,8 +604,8 @@ pub trait TimelineListener: Sync + Send {
 }
 
 #[uniffi::export(callback_interface)]
-pub trait BackPaginationStatusListener: Sync + Send {
-    fn on_update(&self, status: BackPaginationStatus);
+pub trait PaginationStatusListener: Sync + Send {
+    fn on_update(&self, status: PaginationStatus);
 }
 
 #[derive(Clone, uniffi::Object)]