/ 
TiVo-HME-1.0
River stage zero No dependents
/ TiVo::HME::Application

NAME

TiVo::HME::Application - Perl implementation of TiVo's HME protocol See http://tivohme.sourceforge.net/

SYNOPSIS

use TiVo::HME::Application;
our @ISA(TiVo::HME::Application);

sub init {
  my($self, $context) = @_;

  $self->get_root_view->visible(1);
  my $mpg =  $T_RESOURCE->image_file('examples/myloop.jpg');
  $self->get_root_view->set_resource($mpg,
      $T_CONST->HALIGN_CENTER | $T_CONST->VALIGN_CENTER);
  }

  sub handle_event {
      my($self, $resource, $key_action, $key_code, $key_rawcode) = @_;
      print "You pressed the $key_code key on the remote!\n";
  }

DESCRIPTION

Perl on your TiVo in 11 Steps!!

Step 1: Go to http://tivohme.sourceforge.net
Step 2: Go to Step 1
Step 3: Go to Step 2 (seriously)
Step 4: Congratulations on making it here!
Step 5: Really, go to http://tivohme.sourceforge.net, download the
    SDK, read the PDF files (don't worry about the protocol PDF,
    that's what this is for).
Step 6: Learn about Views & Resources
Step 7: Learn about the Application cycle (init then event loop)
Step 8: Learn about Events
Step 9: Learn how the Perl stuff differs from the Java stuff
    (mainly only in naming)
Step 10: View & understand the perl examples - especially how they
    related to the Java examples (they do the same thing!).
Step 11: Use your imagination to create a kick-arse Perl-based HME app!!

Start the Server

First you must start up the HTTP daemon - your TiVo (or Simulator) wants 
to connect to us at port 7288 if you're curious.
The 'start.pl' script start ups the Server & waits for a connection from
a TiVo or simulator.
When one comes it, the URL is pulled off & is taked for the name of
the app.
SO after starting the server, in the Simulator you type in:
http://localhost/myapp & hit return.
The Perl HME stuff will now try to find a module named 'myapp.pm'.
Obviously myapp.pm needs to be in @INC - so your start script should
'use lib qw(...)' to point to where your TiVo HME app lives.

Write your App

Your TiVo HME app should subclass TiVo::HME::Application.

use TiVo::HME::Application;
our @ISA = qw(TiVo::HME::Application);

The entry point to your app is the 'init' function call.  Hopefully
by now it's starting to sound similar to mod_perl.
You get a reference to $self & $context as the parameters.
We'll talk about contexts laters as you most likely don't need
anything from that object.
In $self you stash thing that you want to persist beyond the init
call.  Mostly that'll be Views, Resources, & Application state.

Views

Views are containers for Resources.  A View has exactly 1 parent view and
any number of childen views.
Views have stuff like bounds, scale, translation, and transparency.
They can be visible or not, they can be painted on or not.
And they can have exactly 1 Resource.

Creating a new View

my $view = TiVo::HME::View->new(
    x => MIN_X_VALUE,
    y => MIN_Y_VALUE,
    width => MAX_WIDTH,
    height => MAX_HEIGHT,
    visible => [ 0 | 1 ],
    [ parent => $parent_view ]
);

x, y, width, height are the bounding rectangle of the view.  
Anything drawn outside of that box will be clipped.
If you do not specify the parent it will be set to the root view.
There are accessor methods for each of the view's properties.

You MUST 'add' the View after you create it!!

$view->add;

The Root View

There is 1 Root view whose bounds are the entire screen (640x480).
This view is INVISIBLE by default.  Mostly like you will want to
make it visible as soon as your done adding resources if not sooner:

$T_VIEW->root_view->visible(1);

Manipulating Views

See the sourceforge page for details about what this stuff means.

Adding the View

$view->add;

Set the View's Resource

$view->set_resource(<resource>, [ flags ]);
<resource> is the resource - see below
[ flags ] if present is OR'ed together flags from CONST.pm
    see HALIGN_LEFT -> IMAGE_BESTFIT
    set to HALIGN_LEFT by default

Visible

$self->visible([ 0 | 1], [animation]);

Bounds

$self->bounds(x, y, width, heigth, [animation]);

Scale

$self->scale(scale_x, scale_y, [animation]);
scale_x & scale_y are floats

Translate

$self->translate(t_x, t_y, [animation]);
Translate origin

Transparency

$self->transparency(transparency, [animation]);
0 = opaque
1 = transparent

Painting

$self->painting([ 0 | 1], [animation]);
Set painting

Remove

$self->remove([animation]);
Remove view

Resources

There are 9 Resources:

    Image
    Sound
    Font
    True Type Font
    Color
    Text
    Stream
    Animation

See http://tivohme.sourceforge.net for details about what these
    are & how they are used.

Image Resource

my $img = $T_RESOURCE->image_file(<filename>);
Can be a PNG, JPEG, or MPEG file (for setting video backgrounds)

Sound Resource

my $sound = $T_RESOURCE->sound_file(<filename>);
Has to be a 8-bit PCM file

Font Resource

my $font = $T_RESOURCE->font(<name>, <point size>, <style>);
Where <name> is 'system' or 'default'
<point size> is a float (have no idea why)
<style> is $T_CONST->FONT_PLAIN
            $T_CONST->FONT_BOLD
            $T_CONST->FONT_ITALIC
            $T_CONST->FONT_BOLDITALIC

TTF Resource

my $ttf_font = $T_RESOURCE->ttf_file(<filename>);
Pass a TTF file

Color Resource

my $color = $T_RESOURCE->color(<red>, <green>, <blue>, <alpha>
All values are 0-255
Alpha = 255 = opaque
Alpha = 0 = transparent

Text Resource

my $text = $T_RESOURCE->text(<font>, <color>, <string>);
Where <font> is a font or TTF resource,
color is a color resource & string is yer string

Stream Resource

my $stream = $T_RESOURCE->stream(<url>, <content-type>, <play>);
<url> points to a streamable resource
<content-type> is the content type hint
<play> = 1 = play
<play> = 0 = pause

Manipulating Resources

Again see the sourceforge page for what these mean

Make active

$resource->active([ 0 | 1 ]);
Make a resource active or not

Set position

$resource->set_position(<int>);

Sets the position at which the resource is played back. Resources which are playing are immediately repositioned. Resources which are not yet started will begin playing at this position.

Set speed

$resource->set_speed([ 0 .. 1 ]);

Close

$resource->close;

Remove

$resource->remove;

Send Event

Only key events are supported (HME limitation not mine)
$resource->send_event(<target>, <animation>, <data>);
<target> currently can only be 1
<animation> is an animation resource
<data> is see 'make_key_event'

Make Key Event

$self->make_key_event(<target>, <action>, <code>, <rawcode>);
<target> can only be 1
<action> is $T_CONST->KEY_PRESS
            $T_CONST->KEY_REPEAT
            $T_CONST->KEY_RELEASE
<code> is a key code - look in CONST.pm for all of 'em
<rawcode> is whatever the heck you want it to be

Default resources

All of the default resources (sounds) are available in the
    @TiVo::HME::DEFAULT_RESOURCES array indexed by the
    constants ID_BONK_SOUND etc... - see CONST.pm

Examples

SEE AND UNDERSTAND THE EXAMPLES!!!!!

EXPORT

Exporting is Bad. Bad. Bad. Bad. And Yet this modules exports 3 symbols. That's how important they are. You will use them many times in your app & will thank me someday. Really.

$T_RESOURCE is a handle to 'TiVo::HME::Resource' $T_VIEW is a handle to 'TiVo::HME::View' $T_CONST is a handle to 'TiVo::HME::CONST'

You really don't want to be writing:

my $r = TiVo::HME::Resource->color(222. 32, 20, 0xff);

when you can just write

my $r = $T_RESOURCE->color(222. 32, 20, 0xff);

Or for constants:

my $bonk = TiVo::HME::CONST->ID_BONK_SOUND;

vs.

my $bonk = $T_CONST->ID_BONK_SOUND;

Isn't that worth Exporting??

SEE ALSO

http://tivohme.sourceforge.net

AUTHOR

Mark Ethan Trostler, <mark@zzo.com>

COPYRIGHT AND LICENSE

Copyright 2005 by Mark Ethan Trostler

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.