File Coverage

lib/HTML/Object/DOM/Element/Track.pm
Criterion Covered Total %
statement 27 48 56.2
branch 0 10 0.0
condition 0 3 0.0
subroutine 9 17 52.9
pod 7 8 87.5
total 43 86 50.0


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## HTML Object - ~/lib/HTML/Object/DOM/Element/Track.pm
3             ## Version v0.2.0
4             ## Copyright(c) 2021 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2021/12/23
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::Element::Track;
15             BEGIN
16             {
17 1     1   1119 use strict;
  1         2  
  1         32  
18 1     1   5 use warnings;
  1         5  
  1         35  
19 1     1   5 use parent qw( HTML::Object::DOM::Element );
  1         3  
  1         10  
20 1     1   70 use vars qw( @EXPORT_OK %EXPORT_TAGS $VERSION );
  1         12  
  1         90  
21 1     1   7 use HTML::Object::DOM::Element::Shared qw( :track );
  1         2  
  1         143  
22             use constant {
23             # Indicates that the text track's cues have not been obtained.
24 1         174 NONE => 0,
25             # Indicates that the text track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track by the parser.
26             LOADING => 1,
27             # Indicates that the text track has been loaded with no fatal errors.
28             LOADED => 2,
29             # Indicates that the text track was enabled, but when the user agent attempted to obtain it, this failed in some way. Some or all of the cues are likely missing and will not be obtained.
30             ERROR => 3,
31 1     1   10 };
  1         2  
32 1     1   11 our @EXPORT_OK = qw( NONE LOADING LOADED ERROR );
33 1         5 our %EXPORT_TAGS = (
34             all => [qw( NONE LOADING LOADED ERROR )],
35             );
36 1         18 our $VERSION = 'v0.2.0';
37             };
38              
39 1     1   6 use strict;
  1         2  
  1         42  
40 1     1   7 use warnings;
  1         2  
  1         531  
41              
42             sub init
43             {
44 0     0 1   my $self = shift( @_ );
45 0           $self->{_init_strict_use_sub} = 1;
46 0 0         $self->SUPER::init( @_ ) || return( $self->pass_error );
47 0 0         $self->{tag} = 'track' if( !CORE::length( "$self->{tag}" ) );
48 0           return( $self );
49             }
50              
51             # Note: property default
52 0     0 1   sub default : lvalue { return( shift->_set_get_property( { attribute => 'default', is_boolean => 1 }, @_ ) ); }
53              
54             # Note: property kind
55 0     0 1   sub kind : lvalue { return( shift->_set_get_property( 'kind', @_ ) ); }
56              
57             # Note: property label
58 0     0 1   sub label : lvalue { return( shift->_set_get_property( 'label', @_ ) ); }
59              
60 0     0 0   sub oncuechange : lvalue { return( shift->on( 'cuechange', @_ ) ); }
61              
62             # Note: property readyState read-only
63 0     0 1   sub readyState : lvalue { return( shift->_set_get_number( 'readystate', @_ ) ); }
64              
65             # Note: property src is inherited
66              
67             # Note: property srclang
68 0     0 1   sub srclang : lvalue { return( shift->_set_get_property( 'srclang', @_ ) ); }
69              
70             # Note: property track read-only
71             sub track
72             {
73 0     0 1   my $self = shift( @_ );
74 0 0 0       return( $self->{track} ) if( defined( $self->{track} ) && ref( $self->{track} ) );
75 0 0         $self->_load_class( 'HTML::Object::DOM::TextTrack' ) || return( $self->pass_error );
76 0           my $kind = $self->kind;
77 0           my $label = $self->label;
78 0           my $lang = $self->srclang;
79 0           my $track = HTML::Object::DOM::TextTrack->new( $kind, $label, $lang,
80             {
81             id => $self->id,
82             debug => $self->debug,
83             });
84 0 0         return( $self->pass_error( HTML::Object::DOM::TextTrack->error ) ) if( !defined( $track ) );
85 0           $track->parent( $self );
86 0           return( $self->{track} = $track );
87             }
88              
89             1;
90             # NOTE: POD
91             __END__
92              
93             =encoding utf-8
94              
95             =head1 NAME
96              
97             HTML::Object::DOM::Element::Track - HTML Object DOM Track Class
98              
99             =head1 SYNOPSIS
100              
101             use HTML::Object::DOM::Element::Track;
102             my $track = HTML::Object::DOM::Element::Track->new ||
103             die( HTML::Object::DOM::Element::Track->error, "\n" );
104              
105             my $video = $doc->getElementsByTagName('video')->[0];
106             # or
107             my $video = $doc->createElement('video');
108             $video->controls = 1; # true
109             # Source 1
110             my $source1 = $doc->createElement('source');
111             $source1->src = 'https://example.org/some/where/videos/video.webm';
112             # Source 2
113             my $source2 = $doc->createElement('source');
114             $source2->src = 'https://example.org/some/where/videos/video.mp4';
115             # Track 1
116             my $track1 = $doc->createElement('track');
117             $track1->kind = 'subtitles';
118             $track1->src = 'subtitles-en.vtt';
119             $track1->label = 'English captions';
120             $track1->srclang = 'en';
121             $track1->type = 'text/vtt';
122             $track1->default = 1; # true
123             # Track 2
124             my $track2 = $doc->createElement('track');
125             $track2->kind = 'subtitles';
126             $track2->src = 'subtitles-fr.vtt';
127             $track2->label = 'Sous-titres Français';
128             $track2->srclang = 'fr';
129             $track2->type = 'text/vtt';
130             # Track 3
131             my $track3 = $doc->createElement('track');
132             $track3->kind = 'subtitles';
133             $track3->src = 'subtitles-ja.vtt';
134             $track3->label = '日本語字幕';
135             $track3->srclang = 'ja'";
136             $track3->type = 'text/vtt';
137             # Append everything
138             $video->appendChild( $source1 );
139             $video->appendChild( $source2 );
140             $video->appendChild( $track1 );
141             $video->appendChild( $track2 );
142             $video->appendChild( $track3 );
143             my $p = $doc->createElement('p');
144             $p->textContent = q{This browser does not support the video element.};
145             $video->appendChild( $p );
146              
147             <video controls="">
148             <source src="https://example.org/some/where/videos/video.webm" type="video/webm" />
149             <source src="https://example.org/some/where/videos/video.mp4" type="video/mp4" />
150             <track src="subtitles-en.vtt" label="English captions" kind="subtitles" srclang="en" default />
151             <track src="subtitles-fr.vtt" label="Sous-titres Français" kind="subtitles" srclang="fr" />
152             <track src="subtitles-ja.vtt" label="日本語字幕" kind="subtitles" srclang="ja" />
153             <p>This browser does not support the video element.</p>
154             </video>
155              
156             =head1 VERSION
157              
158             v0.2.0
159              
160             =head1 DESCRIPTION
161              
162             This interface represents an HTML C<<track>> element within the DOM. This element can be used as a child of either C<<audio>> or C<<video>> to specify a text track containing information such as closed captions or subtitles.
163              
164             =head1 INHERITANCE
165              
166             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +-----------------------------------+
167             | HTML::Object::Element | --> | HTML::Object::EventTarget | --> | HTML::Object::DOM::Node | --> | HTML::Object::DOM::Element | --> | HTML::Object::DOM::Element::Track |
168             +-----------------------+ +---------------------------+ +-------------------------+ +----------------------------+ +-----------------------------------+
169              
170             =head1 PROPERTIES
171              
172             Inherits properties from its parent L<HTML::Object::DOM::Element>
173              
174             =head2 default
175              
176             A boolean value reflecting the C<default> attribute, indicating that the track is to be enabled if the user's preferences do not indicate that another track would be more appropriate.
177              
178             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/default>
179              
180             =head2 kind
181              
182             Is a string that reflects the C<kind> HTML attribute, indicating how the text track is meant to be used. Possible values are: subtitles, captions, descriptions, chapters, or metadata.
183              
184             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/kind>
185              
186             =head2 label
187              
188             Is a string that reflects the C<label> HTML attribute, indicating a user-readable title for the track.
189              
190             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/label>
191              
192             =head2 readyState
193              
194             Returns an unsigned short that show the readiness state of the track. Below are the possible constant values.
195             You can export and use those constants by calling either of the following:
196              
197             use HTML::Object::DOM::Element::Track qw( :all );
198             # or
199             use HTML::Object::DOM qw( :track );
200              
201             See L</CONSTANTS> for the constants that can be exported and used.
202              
203             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/readyState>
204              
205             =head2 src
206              
207             Is a string that reflects the src HTML attribute, indicating the address of the text track data.
208              
209             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/src>
210              
211             =head2 srclang
212              
213             Is a string that reflects the srclang HTML attribute, indicating the language of the text track data.
214              
215             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/srclang>
216              
217             =head2 track
218              
219             Returns C<TextTrack> is the track element's text track data.
220              
221             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/track>
222              
223             =head1 METHODS
224              
225             Inherits methods from its parent L<HTML::Object::DOM::Element>
226              
227             =head1 EVENTS
228              
229             Event listeners for those events can also be found by prepending C<on> before the event type:
230              
231             For example, C<cuechange> event listeners can be set also with C<oncuechange> method:
232              
233             $e->oncuechange(sub{ # do something });
234             # or as an lvalue method
235             $e->oncuechange = sub{ # do something };
236              
237             =head2 cuechange
238              
239             Under perl, this event is not triggered obviously, but you can trigger it yourself.
240              
241             Under JavaScript, this is sent when the underlying L<TextTrack|HTML::Object::DOM::TextTrack> has changed the currently-presented cues. This event is always sent to the L<TextTrack|HTML::Object::DOM::TextTrack> but is also sent to the L<HTML::Object::DOM::Element::Track> if one is associated with the track.
242             You may also use the C<oncuechange> event handler to establish a handler for this event.
243              
244             Example:
245              
246             $track->addEventListener( cuechange => sub
247             {
248             my $cues = $track->activeCues; # array of current $cues
249             });
250              
251             $track->oncuechange = sub
252             {
253             my $cues = $track->activeCues; # array of current $cues
254             }
255              
256             Another example:
257              
258             my $textTrackElem = $doc->getElementById( 'texttrack' );
259              
260             $textTrackElem->addEventListener( cuechange => sub
261             {
262             my $cues = $event->target->track->activeCues;
263             });
264              
265             or
266              
267             $textTrackElem->oncuechange = sub
268             {
269             my $cues = $_->target->track->activeCues;
270             });
271              
272             See also L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement/cuechange_event>
273              
274             =head1 CONSTANTS
275              
276             The following constants can be exported and used, such as:
277              
278             use HTML::Object::DOM::Element::Track qw( :all );
279             # or directly from HTML::Object::DOM
280             use HTML::Object::DOM qw( :track );
281              
282             =over 4
283              
284             =item NONE (0)
285              
286             Indicates that the text track's cues have not been obtained.
287              
288             =item LOADING (1)
289              
290             Indicates that the text track is loading and there have been no fatal errors encountered so far. Further cues might still be added to the track by the parser.
291              
292             =item LOADED (2)
293              
294             Indicates that the text track has been loaded with no fatal errors.
295              
296             =item ERROR (3)
297              
298             Indicates that the text track was enabled, but when the user agent attempted to obtain it, this failed in some way. Some or all of the cues are likely missing and will not be obtained.
299              
300             =back
301              
302             =head1 AUTHOR
303              
304             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
305              
306             =head1 SEE ALSO
307              
308             L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement>, L<Mozilla documentation on track element|https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track>
309              
310             =head1 COPYRIGHT & LICENSE
311              
312             Copyright(c) 2021 DEGUEST Pte. Ltd.
313              
314             All rights reserved
315              
316             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
317              
318             =cut