File Coverage

lib/HTML/Object/DOM/TextTrackList.pm
Criterion Covered Total %
statement 22 48 45.8
branch 0 6 0.0
condition 0 9 0.0
subroutine 8 19 42.1
pod 7 7 100.0
total 37 89 41.5


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/TextTrackList.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/26
7             ## Modified 2022/09/18
8             ## All rights reserved
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTML::Object::DOM::TextTrackList;
15             BEGIN
16             {
17 1     1   998 use strict;
  1         2  
  1         29  
18 1     1   12 use warnings;
  1         3  
  1         28  
19 1     1   6 use parent qw( HTML::Object::DOM::List );
  1         2  
  1         5  
20 1     1   90 use vars qw( $VERSION );
  1         10  
  1         49  
21 1     1   9 use Scalar::Util ();
  1         3  
  1         36  
22 1     1   19 our $VERSION = 'v0.2.0';
23             };
24              
25 1     1   6 use strict;
  1         2  
  1         32  
26 1     1   10 use warnings;
  1         7  
  1         582  
27              
28             sub addEventListener { return( shift->SUPER::addEventListener({
29 0     0 1   addtrack => {
30             add => { property => 'children', type => 'add', event => 'addtrack' },
31             },
32             change => {
33             add => { property => 'selected', type => 'add', event => 'change' },
34             remove => { property => 'selected', type => 'remove', event => 'change' },
35             },
36             removetrack => {
37             remove => { property => 'children', type => 'remove', event => 'removetrack' },
38             },
39             }, @_ ) ); }
40              
41 0     0 1   sub children { return( shift->reset(@_)->_set_get_object_array_object({
42             field => 'children',
43             callbacks =>
44             {
45             add => '_on_children_add',
46             remove => '_on_children_remove',
47             }
48             }, 'HTML::Object::Element', @_ ) ); }
49              
50 0     0 1   sub forEach { return( shift->children->foreach( @_ ) ); }
51              
52             sub getTrackById
53             {
54 0     0 1   my $self = shift( @_ );
55 0           my $id = shift( @_ );
56 0 0 0       return if( !defined( $id ) || !CORE::length( "$id" ) );
57 0           foreach my $e ( @$self )
58             {
59 0 0 0       if( Scalar::Util::blessed( $e ) &&
60             $e->isa( 'HTML::Object::DOM::Element::Track' ) )
61             {
62 0           my $e_id = $e->attr( 'id' );
63 0 0 0       return( $e ) if( defined( $e_id ) && $id eq $e_id );
64             }
65             }
66 0           return;
67             }
68              
69             # Note: property length is inherited
70              
71 0     0 1   sub onaddtrack : lvalue { return( shift->on( 'addtrack', @_ ) ); }
72              
73 0     0 1   sub onchange : lvalue { return( shift->on( 'change', @_ ) ); }
74              
75 0     0 1   sub onremovetrack : lvalue { return( shift->on( 'removetrack', @_ ) ); }
76              
77             sub _on_children_add
78             {
79 0     0     my $self = shift( @_ );
80 0           my( $pos, $ref ) = @_;
81 0           my $track = $ref->[0];
82             $self->_trigger_event_for( addtrack => {
83             class => 'HTML::Object::DOM::TrackEvent',
84             callback => sub
85             {
86 0     0     my $event = shift( @_ );
87 0           $event->track( $track );
88             }
89 0           });
90             }
91              
92             sub _on_children_remove
93             {
94 0     0     my $self = shift( @_ );
95 0           my( $pos, $ref ) = @_;
96 0           my $track = $ref->[0];
97             $self->_trigger_event_for( addtrack => {
98             class => 'HTML::Object::DOM::TrackEvent',
99             callback => sub
100             {
101 0     0     my $event = shift( @_ );
102 0           $event->track( $track );
103             }
104 0           });
105             }
106              
107             1;
108             # NOTE: POD
109             __END__
110              
111             =encoding utf-8
112              
113             =head1 NAME
114              
115             HTML::Object::DOM::TextTrackList - HTML Object DOM Track List Class
116              
117             =head1 SYNOPSIS
118              
119             use HTML::Object::DOM::TextTrackList;
120             my $list = HTML::Object::DOM::TextTrackList->new ||
121             die( HTML::Object::DOM::TextTrackList->error, "\n" );
122              
123             Getting a video element's text track list:
124              
125             my $textTracks = $doc->querySelector( 'video' )->textTracks;
126              
127             Monitoring track count changes:
128              
129             $textTracks->onaddtrack = \&updateTrackCount;
130             $textTracks->onremovetrack = \&updateTrackCount;
131              
132             sub updateTrackCount
133             {
134             my $event = shift( @_ );
135             my $trackCount = $textTracks->length;
136             drawTrackCountIndicator( $trackCount );
137             }
138              
139             =head1 VERSION
140              
141             v0.2.0
142              
143             =head1 DESCRIPTION
144              
145             The C<TextTrackList> interface is used to represent a list of the text tracks defined by the C<<track>> element, with each track represented by a separate textTrack object in the list. It inherits from L<HTML::Object::EventTarget>
146              
147             =head1 INHERITANCE
148              
149             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------------+
150             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::List | --> | HTML::Object::DOM::TextTrackList |
151             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------------+
152              
153             =head1 PROPERTIES
154              
155             Inherits properties from its parent L<HTML::Object::DOM::List>
156              
157             =head2 length
158              
159             The number of tracks in the list.
160              
161             Example:
162              
163             my $media = $doc->querySelector( 'video, audio' );
164             my $numTextTracks = 0;
165              
166             if( $media->textTracks )
167             {
168             $numTextTracks = $media->textTracks->length;
169             }
170              
171             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/length>
172              
173             =head1 METHODS
174              
175             Inherits methods from its parent L<HTML::Object::DOM::List>
176              
177             =head2 addEventListener
178              
179             Set a new event listener for the provided event type. See L<HTML::Object::EventTarget>
180              
181             =head2 children
182              
183             Set or get an L<array object|Module::Generic::Array> of elements.
184              
185             =head2 forEach
186              
187             Provided with a callback code reference and this will call it for each child element.
188              
189             See L<Module::Generic::Array/foreach>
190              
191             =head2 getTrackById
192              
193             Returns the L<TextTrack|HTML::Object::DOM::TextTrack> found within the C<TextTrackList> whose id matches the specified string. If no match is found, C<undef> is returned.
194              
195             Example:
196              
197             my $theTrack = $TextTrackList->getTrackById( $id );
198              
199             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/getTrackById>
200              
201             =head1 EVENTS
202              
203             =head2 addtrack
204              
205             Fired when a new text track has been added to the media element.
206             Also available via the onaddtrack property.
207              
208             Example:
209              
210             my $mediaElement = $doc->querySelector( 'video, audio' );
211              
212             $mediaElement->textTracks->addEventListener( addtrack => sub
213             {
214             my $event = shift( @_ );
215             say( "Text track: ", $event->track->label, " added" );
216             });
217              
218             my $mediaElement = $doc->querySelector( 'video, audio' );
219              
220             $mediaElement->textTracks->onaddtrack = sub
221             {
222             my $event = shift( @_ );
223             say( "Text track: ", $event->track->label, " added" );
224             };
225              
226             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/addtrack_event>
227              
228             =head2 change
229              
230             Fired when a text track has been made active or inactive.
231             Also available via the onchange property.
232              
233             Example:
234              
235             my $mediaElement = $doc->querySelectorAll( 'video, audio' )->[0];
236             $mediaElement->textTracks->addEventListener( change => sub
237             {
238             my $event = shift( @_ );
239             say( "'", $event->type, "' event fired" );
240             });
241              
242             my $mediaElement = $doc->querySelector( 'video, audio' );
243             $mediaElement->textTracks->onchange = sub
244             {
245             say( "'", $event->type, "' event fired" );
246             };
247              
248             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/change_event>
249              
250             =head2 removetrack
251              
252             Fired when a new text track has been removed from the media element.
253             Also available via the onremovetrack property.
254              
255             Example:
256              
257             my $mediaElement = $doc->querySelector( 'video, audio' );
258              
259             $mediaElement->textTracks->addEventListener( removetrack => sub
260             {
261             my $event = shift( @_ );
262             say( "Text track: ", $event->track->label, " removed" );
263             });
264              
265             my $mediaElement = $doc->querySelector( 'video, audio' );
266              
267             $mediaElement->textTracks->onremovetrack = sub
268             {
269             my $event = shift( @_ );
270             say( "Text track: ", $event->track->label, " removed" );
271             };
272              
273             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/removeTrack_event>
274              
275             =head1 EVENT HANDLERS
276              
277             =head2 onaddtrack
278              
279             An event handler to be called when the C<addtrack> event is fired, indicating that a new text track has been added to the media element.
280              
281             Example:
282              
283             $doc->querySelector( 'video' )->textTracks->onaddtrack = sub
284             {
285             my $event = shift( @_ );
286             addToTrackList( $event->track );
287             };
288              
289             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/onaddtrack>
290              
291             =head2 onchange
292              
293             An event handler to be called when the change event occurs.
294              
295             Example:
296              
297             my $trackList = $doc->querySelector( 'video, audio' )->textTracks;
298              
299             $trackList->onchange = sub
300             {
301             my $event = shift( @_ );
302             #.... do something
303             };
304              
305             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/onchange>
306              
307             =head2 onremovetrack
308              
309             An event handler to call when the removetrack event is sent, indicating that a text track has been removed from the media element.
310              
311             Example:
312              
313             $doc->querySelectorAll( 'video, audio' )->[0].textTracks->onremovetrack = sub
314             {
315             my $event = shift( @_ );
316             myTrackCount = $doc->querySelectorAll( 'video, audio' )->[0]->textTracks->length;
317             };
318              
319             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList/onremovetrack>
320              
321             =head1 AUTHOR
322              
323             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
324              
325             =head1 SEE ALSO
326              
327             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/TextTrackList>
328              
329             =head1 COPYRIGHT & LICENSE
330              
331             Copyright(c) 2021 DEGUEST Pte. Ltd.
332              
333             All rights reserved
334              
335             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
336              
337             =cut