/ 
Adapter-Async-0.019
River stage two • 9 direct dependents • 14 total dependents
/ Adapter::Async::OrderedList

NAME

Adapter::Async::OrderedList - API for dealing with ordered lists

VERSION

version 0.018

DESCRIPTION

Accessing data

  • count - resolves with the number of items. If this isn't possible, an estimate may be acceptable.

    say "items: " . $adapter->count->get

  • get - accepts a list of indices

    $adapter->get(
 items   => [1,2,3],
 on_item => sub { ... }
)->on_done(sub { warn "all done, full list of items: @{$_[0]}" })

    The returned list of items are guaranteed not to be modified further, if you want to store the arrayref directly.

This means we have double-notify on get: a request for (1,2,3,4) needs to fire events for each of 1,2,3,4, and also return the list of all of them on completion (by resolving a Future).

Modification

  • clear - remove all data

  • splice - modify by adding/removing items at a given point

  • modify - changes a single entry

Helper methods provide the following:

  • insert - splice $idx, @data, 0

  • append - splice $idx + 1, @data, 0

Events

All events are shared over a common bus for each data source, in the usual fashion - adapters and views can subscribe to the ones they're interested in, and publish events at any time.

The adapter raises these:

  • item_changed - the given item has been modified. by default only applies to elements that were marked as visible.

  • splice - changes to the array which remove or add elements

  • move - an existing element moves to a new position (some adapters may not be able to differentiate between this and splice: if in doubt, use splice instead, don't report as a move unless it's guaranteed to be existing items)

    index, length, offset (+/-)

The view raises these:

  • visible - indicates visibility of one or more items. change events will start being sent for these items.

    visible => [1,2,3,4,5,6]

    Filters may result in a list with gaps:

    visible => [1,3,4,8,9,10]

    Note that "visible" means "the user is able to see this data", so they'd be a single page of data rather than the entire set when no filters are applied. Visibility changes often - scrolling will trigger a visible/hidden pair for example.

    Also note that ->get may be called on any element, regardless of visibility - prefetching is one common example here.

  • hidden - no longer visible.

    hidden => [1,2,4]

  • selected - this item is now part of an active selection. could be used to block deletes.

    selected => [1,4,5,6]

  • highlight - mouse over, cursor, etc.

    highlight => 1

    Some views won't raise this - if touch control is involved, for example

  • activate - some action has been performed.

    activate => [1]
activate => [1,2,5,6,7,8]

    Multi-activate will typically happen when items have been selected rather than just highlighted.

    The adapter itself doesn't do much with this.

METHODS

insert

Inserts data before the given position.

$adapter->insert(3, [...])

append

Appends data after the given position.

$adapter->append(3, [...])

push

Appends data to the end of the list.

unshift

Inserts data at the start of the list.

pop

Removes the last element from the list, will resolve with the value.

shift

Removes the first element from the list, will resolve with the value.

all

Returns all the items. Shortcut for calling "count" then "get".

INHERITED METHODS

Adapter::Async

bus, new

AUTHOR

Tom Molesworth <TEAM@cpan.org>

LICENSE

Copyright Tom Molesworth 2013-2015. Licensed under the same terms as Perl itself.