Outline of an owl uiloos

ViewChannel<T, R>

CLASS

A ViewChannel is a class which represents an area on the screen which contains visual elements (views) which are visible for a certain amount of time, or until when the user performs a certain action.

The ViewChannel can be used to implement multiple types of components:

  1. A notification side bar in which the user sees notifications of the application for a limited amount of time.
  2. A flash message area which contain messages that tell the user an action was successful or not. They disappear after a certain amount of time, or when the user clicks on them.
  3. A modal: a window / frame which appears when the user must perform a specific action. The modal closes when the user either performs the action, or when the user cancels the action.
  4. A confirmation dialog: a small window / frame which appears asking the user if they are sure they want to perform a certain action.

The general idea is that often areas on the screen exists which contain contain a specific type of visual element. These elements are often presented (triggered) from code at a distance from the area they are displayed in. This is why ViewChannel is considered a "channel", it is a way of transporting views.

This way you can have one part of the code consume the channel, and use it to simply display the views, and many places (in code) where you put views on the channel.

The idea of the ViewChannel is that you instantiate one for each type of View you want to support, for example: you might have a flash message and a modal ViewChannel instance. Then you use these instances to send "views" to the channel.

The ViewChannel also has a concept of "priority". Sometimes one view has more priority than another view. The ViewChannel will make sure that the views are sorted by priority. The higher the priority the earlier in the views array the view is placed. This makes the ViewChannel a priority queue like data structure.

Since 1.0.0

Constructor

Creates an ViewChannel based on the ViewChannelConfig config.

You can also optionally provide an subscriber so you can get informed of the changes happening to the ViewChannel.

Since 1.0.0

Signature

constructor(
config : ViewChannelConfig ,
subscriber : ViewChannelSubscriber<T,R>
): ViewChannel<T,R>

Parameters

config: ViewChannelConfig

The initial configuration of the ViewChannel.

subscriber: ViewChannelSubscriber<T,R>

An optional subscriber which responds to changes in the ViewChannel.

Properties

  • history

    ViewChannelEvent<T,R> []

    Contains the history of the changes in the views array.

    Tracks 8 types of changes:

    1. INITIALIZED: fired when ViewChannel is initialized.
    2. PRESENTED: fired when ViewChannel presented a ViewChannelView.
    3. DISMISSED: fired when ViewChannel dismissed a ViewChannelView.
    4. DISMISSED_ALL: fired when ViewChannel dismisses all ViewChannelView's.
    5. AUTO_DISMISS_PLAYING: fired when ViewChannelView started to play after a stop or pause.
    6. AUTO_DISMISS_PAUSED: fired when a ViewChannelView auto dismiss was paused.
    7. AUTO_DISMISS_STOPPED: fired when a ViewChannelView auto dismiss was stopped.
    8. DATA_CHANGED: fired when a ViewChannelView data is changed.

    Goes only as far back as configured in the Config property keepHistoryFor, to prevent an infinitely growing history. Note that by default no history is kept, as keepHistoryFor is zero by default.

    The last item in the history is the current active item. The further to the left the further in the past you go.

    This means that a history at index 0 is further in the past than an item at index 1.

    Since 1.0.0

  • views

    ViewChannelView<T,R> []

    The ViewChannelView instances which the ViewChannel holds.

    Since 1.0.0

Methods

  • changeData

    Changes the data of the given ViewChannelView, and informs the subscribers of the change.

    Note: if you provide the exact same data it will still set the data and inform the subscribers, even though nothing has actually changed.

    This way, when data is an object or an array, you can mutate the object / array directly, and pass in the same data object to the changeData, without having to create copies.

    Since 1.6.0

    Signature

    changeData(
    view : ViewChannelView<T,R> ,
    data : T
    ): void

    Parameters

    view: ViewChannelView<T,R>

    The ViewChannelView to change the data for

    data: T

    The new data for the ViewChannelView

    Throws

    ViewChannelNotFoundError item must be in the views array based on === equality

  • changeDataByIndex

    Changes the data of the given ViewChannelView, and informs the subscribers of the change.

    Note: if you provide the exact same data it will still set the data and inform the subscribers, even though nothing has actually changed.

    This way, when data is an object or an array, you can mutate the object / array directly, and pass in the same data object to the changeData, without having to create copies.

    Since 1.6.0

    Signature

    changeDataByIndex(
    index : number ,
    data : T
    ): void

    Parameters

    index: number

    The index of the ViewChannelView to change the data for.

    data: T

    The new data for the ViewChannelView

    Throws

    ViewChannelIndexOutOfBoundsError index cannot be out of bounds

  • dismiss

    Dismisses the ViewChannelView with the given result.

    The result (R) is the value with which the promise of the ViewChannelView will be resolved. For example when making a confirmation dialog, you could set the result to "CONFIRM" when the user presses the confirm button, and set the result to "CANCEL" when the user either presses the cancel button, or clicks outside of the dialog.

    Note: if the ViewChannelView isPresented is false the removal is ignored.

    Note: if the ViewChannelView does not exist in the views array it will throw an error.

    Since 1.0.0

    Signature

    dismiss(
    view : ViewChannelView<T,R> ,
    result : R
    ): void

    Parameters

    view: ViewChannelView<T,R>

    The ViewChannelView to dismiss

    result: R

    The value to resolve the promise of the ViewChannelView with.

    Throws

    ViewChannelNotFoundError item must be in the views array based on === equality

  • dismissAll

    Dismisses all ViewChannelViews within this ViewChannel with the given result.

    The result (R) is the value with which the promise of all the ViewChannelView will be resolved with . For example when making a notifications bar, you could set the result to "CLEARED" when the user presses the a "clear all" button.

    Note: when there are no ViewChannelViews displayed (in the views array) calling dismissAll will result in nothing happening.

    Since 1.0.0

    Signature

    dismissAll(
    result : R
    ): void

    Parameters

    result: R

    The value to resolve the promises of all the ViewChannelViews within the ViewChannel.

  • dismissByIndex

    Dismisses the ViewChannelView which resides at the index of the views array, with the given result.

    The result (R) is the value with which the promise of the ViewChannelView will be resolved. For example when making a confirmation dialog, you could set the result to "CONFIRM" when the user presses the confirm button, and set the result to "CANCEL" when the user either presses the cancel button, or clicks outside of the dialog.

    If the index does not exist an error will be thrown.

    Since 1.0.0

    Signature

    dismissByIndex(
    index : number ,
    result : R
    ): void

    Parameters

    index: number

    The index of the ViewChannelView to dismiss

    result: R

    The value to resolve the promise of the ViewChannelView with.

    Throws

    ViewChannelIndexOutOfBoundsError index cannot be out of bounds

  • initialize

    Initializes the ViewChannel based on the config provided.

    This effectively resets the ViewChannel when called, including the history.

    Since 1.0.0

    Signature

    initialize(
    config : ViewChannelConfig
    ): void

    Parameters

    config: ViewChannelConfig

    The new configuration which will override the old one

  • present

    Takes the provided ViewChannelViewConfig turns it into a ViewChannelView, and places the ViewChannelView into the views array based on the priority given.

    Since 1.0.0

    Signature

    present(
    viewConfig : ViewChannelViewConfig<T,R>
    ): ViewChannelView<T,R>

    Parameters

    viewConfig: ViewChannelViewConfig<T,R>

    The configuration for the view which is presented and returned.

    Returns

    The view which was presented

    Throws

    ViewChannelAutoDismissDurationError autoDismiss duration must be a positive number when defined

  • subscribe

    Subscribe to changes of the ViewChannel. The function you provide will get called whenever changes occur in the ViewChannel.

    Returns an unsubscribe function which when called will unsubscribe from the ViewChannel.

    Since 1.0.0

    Signature

    subscribe(
    subscriber : ViewChannelSubscriber<T,R>
    ): UnsubscribeFunction

    Parameters

    subscriber: ViewChannelSubscriber<T,R>

    The subscriber which responds to changes in the ViewChannel.

    Returns

    A function which when called will unsubscribe from the ViewChannel.

  • unsubscribe

    Unsubscribe the subscriber so it no longer receives changes / updates of the state changes of the ViewChannel.

    Since 1.0.0

    Signature

    unsubscribe(
    subscriber : ViewChannelSubscriber<T,R>
    ): void

    Parameters

    subscriber: ViewChannelSubscriber<T,R>

    The subscriber which you want to unsubscribe.

  • unsubscribeAll

    Unsubscribes all subscribers at once, all subscribers will no longer receives changes / updates of the state changes of the ViewChannel.

    Since 1.5.0

    Signature

    unsubscribeAll(): void