Class: EventTimelineSet

models/event-timeline-set~EventTimelineSet

new EventTimelineSet(roomnullable, opts)

Construct a set of EventTimeline objects, typically on behalf of a given room. A room may have multiple EventTimelineSets for different levels of filtering. The global notification list is also an EventTimelineSet, but lacks a room.

This is an ordered sequence of timelines, which may or may not be continuous. Each timeline lists a series of events, as well as tracking the room state at the start and the end of the timeline (if appropriate). It also tracks forward and backward pagination tokens, as well as containing links to the next timeline in the sequence.

There is one special timeline - the 'live' timeline, which represents the timeline to which events are being added in real-time as they are received from the /sync API. Note that you should not retain references to this timeline - even if it is the current timeline right now, it may not remain so if the server gives us a timeline gap in /sync.

In order that we can find events from their ids later, we also maintain a map from event_id to timeline and index.

Parameters:
Name Type Attributes Description
room Room <nullable>
the optional room for this timelineSet
opts Object hash of options inherited from Room. opts.timelineSupport gives whether timeline support is enabled opts.filter is the filter object, if any, for this timelineSet.
Source:

Methods

addEventsToTimeline(events, toStartOfTimeline, timeline, paginationTokenopt)

Add events to a timeline

Will fire "Room.timeline" for each event added.

Parameters:
Name Type Attributes Description
events Array.<MatrixEvent> A list of events to add.
toStartOfTimeline boolean True to add these events to the start (oldest) instead of the end (newest) of the timeline. If true, the oldest event will be the last element of 'events'.
timeline module:models/event-timeline~EventTimeline timeline to add events to.
paginationToken string <optional>
token for the next batch of events
Source:
Fires:
  • module:client~MatrixClient#event:"Room.timeline"

addEventToTimeline(event, timeline, toStartOfTimeline)

Add event to the given timeline, and emit Room.timeline. Assumes we have already checked we don't know about this event. Will fire "Room.timeline" for each event added.
Parameters:
Name Type Description
event MatrixEvent
timeline EventTimeline
toStartOfTimeline boolean
Source:
Fires:
  • module:client~MatrixClient#event:"Room.timeline"

addLiveEvent(event, duplicateStrategynullable)

Add an event to the end of this live timeline.
Parameters:
Name Type Attributes Description
event MatrixEvent Event to be added
duplicateStrategy string <nullable>
'ignore' or 'replace'
Source:

addTimeline() → {module:models/event-timeline~EventTimeline}

Add a new timeline to this timeline list
Source:
Returns:
newly-created timeline
Type
module:models/event-timeline~EventTimeline

compareEventOrdering(eventId1, eventId2) → (nullable) {number}

Determine where two events appear in the timeline relative to one another
Parameters:
Name Type Description
eventId1 string The id of the first event
eventId2 string The id of the second event
Source:
Returns:
a number less than zero if eventId1 precedes eventId2, and greater than zero if eventId1 succeeds eventId2. zero if they are the same event; null if we can't tell (either because we don't know about one of the events, or because they are in separate timelines which don't join up).
Type
number

eventIdToTimeline(eventId) → {module:models/event-timeline~EventTimeline}

Return the timeline (if any) this event is in.
Parameters:
Name Type Description
eventId String the eventId being sought
Source:
Returns:
timeline
Type
module:models/event-timeline~EventTimeline

findEventById(eventId) → (nullable) {module:models/event~MatrixEvent}

Get an event which is stored in our timelines
Parameters:
Name Type Description
eventId string event ID to look for
Source:
Returns:
the given event, or undefined if unknown
Type
module:models/event~MatrixEvent

getFilter() → (nullable) {Filter}

Get the filter object this timeline set is filtered on, if any
Source:
Returns:
the optional filter for this timelineSet
Type
Filter

getLiveTimeline() → {module:models/event-timeline~EventTimeline}

Get the live timeline for this room.
Source:
Returns:
live timeline
Type
module:models/event-timeline~EventTimeline

getPendingEvents() → {Array.<module:models/event.MatrixEvent>}

Get the list of pending sent events for this timelineSet's room, filtered by the timelineSet's filter if appropriate.
Source:
Throws:
If opts.pendingEventOrdering was not 'detached'
Returns:
A list of the sent events waiting for remote echo.
Type
Array.<module:models/event.MatrixEvent>

getTimelineForEvent(eventId) → (nullable) {module:models/event-timeline~EventTimeline}

Get the timeline which contains the given event, if any
Parameters:
Name Type Description
eventId string event ID to look for
Source:
Returns:
timeline containing the given event, or null if unknown
Type
module:models/event-timeline~EventTimeline

handleRemoteEcho(localEvent, oldEventId, newEventId)

Replaces event with ID oldEventId with one with newEventId, if oldEventId is recognised. Otherwise, add to the live timeline. Used to handle remote echos.
Parameters:
Name Type Description
localEvent MatrixEvent the new event to be added to the timeline
oldEventId String the ID of the original event
newEventId boolean the ID of the replacement event
Source:
Fires:
  • module:client~MatrixClient#event:"Room.timeline"

removeEvent(eventId) → (nullable) {MatrixEvent}

Removes a single event from this room.
Parameters:
Name Type Description
eventId String The id of the event to remove
Source:
Returns:
the removed event, or null if the event was not found in this room.
Type
MatrixEvent

replaceEventId(oldEventId, newEventId)

Track a new event as if it were in the same timeline as an old event, replacing it.
Parameters:
Name Type Description
oldEventId String event ID of the original event
newEventId String event ID of the replacement event
Source:

resetLiveTimeline(backPaginationTokenopt, flushnullable)

Reset the live timeline, and start a new one.

This is used when /sync returns a 'limited' timeline.

Parameters:
Name Type Attributes Description
backPaginationToken string <optional>
token for back-paginating the new timeline
flush bool <nullable>
Whether to flush the non-live timelines too.
Source:
Fires:
  • module:client~MatrixClient#event:"Room.timelineReset"

setFilter(filter)

Set the filter object this timeline set is filtered on (passed to the server when paginating via /messages).
Parameters:
Name Type Description
filter Filter the filter for this timelineSet
Source: