lib/docs/App.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 SDL::App - a SDL perl extension
   6
   7 =head1 SYNOPSIS
   8
   9         use SDL;
  10         use SDL::Event;
  11         use SDL::App;
  12
  13         my $app = new SDL::App (
  14         -title => 'Application Title',
  15         -width => 640,
  16         -height => 480,
  17         -depth => 32 );
  18
  19 This is the manual way of doing things
  20
  21         my $event = new SDL::Event;             # create a new event
  22
  23         $event->pump();
  24         $event->poll();
  25
  26         while ($event->wait()) {
  27           my $type = $event->type();      # get event type
  28           print $type;
  29           exit if $type == SDL_QUIT;
  30           }
  31 An alternative to the manual Event processing is the L<SDL::App::loop> .
  32
  33 =head1 DESCRIPTION
  34
  35 L<SDL::App> controls the root window of the of your SDL based application.
  36 It extends the L<SDL::Surface> class, and provides an interface to the window
  37 manager oriented functions.
  38
  39 =head1 METHODS
  40
  41 =head2 new
  42
  43 C<SDL::App::new> initializes the SDL, creates a new screen,
  44 and initializes some of the window manager properties.
  45 C<SDL::App::new> takes a series of named parameters:
  46
  47 =over 4
  48
  49 =item *
  50
  51 -title
  52
  53 =item *
  54
  55 -icon_title
  56
  57 =item *
  58
  59 -icon
  60
  61 =item *
  62
  63 -width
  64
  65 =item *
  66
  67 -height
  68
  69 =item *
  70
  71 -depth
  72
  73 =item *
  74
  75 -flags
  76
  77 =item *
  78
  79 -resizeable
  80
  81 =back
  82
  83 =head2 title
  84
  85 C<SDL::App::title> takes 0, 1, or 2  arguments.  It returns the current
  86 application window title.  If one parameter is passed, both the window
  87 title and icon title will be set to its value.  If two parameters are
  88 passed the window title will be set to the first, and the icon title
  89 to the second.
  90
  91 =head2 delay
  92
  93 C<SDL::App::delay> takes 1 argument, and will sleep the application for
  94 that many ms.
  95
  96 =head2 ticks
  97
  98 C<SDL::App::ticks> returns the number of ms since the application began.
  99
 100 =head2 error
 101
 102 C<SDL::App::error> returns the last error message set by the SDL.
 103
 104 =head2 resize
 105
 106 C<SDL::App::resize> takes a new height and width of the application
 107 if the application was originally created with the -resizable option.
 108
 109 =head2 fullscreen
 110
 111 C<SDL::App::fullscreen> toggles the application in and out of fullscreen mode.
 112
 113 =head2 iconify
 114
 115 C<SDL::App::iconify> iconifies the applicaiton window.
 116
 117 =head2 grab_input
 118
 119 C<SDL::App::grab_input> can be used to change the input focus behavior of
 120 the application.  It takes one argument, which should be one of the following:
 121
 122 =over 4
 123
 124 =item *
 125 SDL_GRAB_QUERY
 126
 127 =item *
 128 SDL_GRAB_ON
 129
 130 =item *
 131 SDL_GRAB_OFF
 132
 133 =back
 134
 135 =head2 loop
 136
 137 C<SDL::App::loop> is a simple event loop method which takes a reference to a hash
 138 of event handler subroutines.  The keys of the hash must be SDL event types such
 139 as SDL_QUIT(), SDL_KEYDOWN(), and the like.  The event method recieves as its parameter
 140 the event object used in the loop.
 141
 142   Example:
 143
 144         my $app = new SDL::App  -title => "test.app",
 145                                 -width => 800,
 146                                 -height => 600,
 147                                 -depth => 32;
 148
 149         my %actions = (
 150                 SDL_QUIT() => sub { exit(0); },
 151                 SDL_KEYDOWN() => sub { print "Key Pressed" },
 152         );
 153
 154         $app->loop(\%actions);
 155
 156 =head2 sync
 157
 158 C<SDL::App::sync> encapsulates the various methods of syncronizing the screen with the
 159 current video buffer.  C<SDL::App::sync> will do a fullscreen update, using the double buffer
 160 or OpenGL buffer if applicable.  This is prefered to calling flip on the application window.
 161
 162 =head2 attribute ( attr, [value] )
 163
 164 C<SDL::App::attribute> allows one to set and get GL attributes.  By passing a value
 165 in addition to the attribute selector, the value will be set.  C<SDL:::App::attribute>
 166 always returns the current value of the given attribute, or croaks on failure.
 167
 168 =head1 AUTHOR
 169
 170 David J. Goehrig
 171 Kartik Thakore
 172
 173 =head1 SEE ALSO
 174
 175 L<perl> L<SDL::Surface> L<SDL::Event>  L<SDL::OpenGL>
 176
 177 =cut