/lib/pods/SDLx/App.pod

http://github.com/PerlGameDev/SDL · Unknown · 192 lines · 119 code · 73 blank · 0 comment · 0 complexity · 56dc7c9938629955324bbe8f66abdb97 MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDLx::App - a SDL perl extension
  4. =head1 CATEGORY
  5. Extension
  6. =head1 SYNOPSIS
  7. use SDL;
  8. use SDLx::App;
  9. use SDL::Event;
  10. use SDL::Events;
  11. my $app = SDLx::App->new(
  12. title => 'Application Title',
  13. width => 640,
  14. height => 480,
  15. depth => 32
  16. );
  17. This is the manual way of doing things
  18. my $event = SDL::Event->new; # create a new event
  19. SDL::Events::pump_events();
  20. while ( SDL::Events::poll_event($event) ) {
  21. my $type = $event->type(); # get event type
  22. print $type;
  23. exit if $type == SDL_QUIT;
  24. }
  25. An alternative to the manual Event processing is through the L<SDLx::Controller> module. L<SDLx::App> is a Controller so see the CALLBACKS section below.
  26. =head1 DESCRIPTION
  27. L<SDLx::App> controls the root window of the of your SDL based application.
  28. It extends the L<SDL::Surface> class, and provides an interface to the window
  29. manager oriented functions.
  30. =head1 METHODS
  31. =head2 new
  32. C<SDLx::App::new> initializes the SDL, creates a new screen,
  33. and initializes some of the window manager properties.
  34. C<SDLx::App::new> takes a series of named parameters:
  35. =over 4
  36. =item * title
  37. the window title. Defaults to the file name. Shorter alias: 't'
  38. =item * icon_title
  39. the icon title. Defaults to file name. Shortcut: 'it'
  40. =item * icon
  41. the icon itself. Defaults to none. Shortcut: 'i'
  42. =item * width
  43. Window width, in pixels. Defaults to 800. Shortcut: 'w'
  44. =item * height
  45. Window height, in pixels. Defaults to 600. Shortcut: 'h'
  46. =item * depth
  47. Screen depth. Defaults to 16. Shortcut: 'd'.
  48. =item * flags
  49. Any flags you want to pass to L<SDL::Video> upon initialization. Defaults to SDL_ANYFORMAT. Flags should be I<or'ed> together if you're passing more than one (flags => FOO|BAR). Shortcut: 'f'.
  50. =item * resizeable
  51. Set this to a true value to make the window resizeable by the user. Default is off.
  52. =item * exit_on_quit
  53. Set this to a true value to make the app exit if a SDL_QUIT event is triggered. Shortcut: 'eoq'.
  54. =back
  55. =head1 METHODS
  56. =head2 title()
  57. =head2 title( $new_title )
  58. =head2 title( $window_title, $icon_title )
  59. C<SDLx::App::title> takes 0, 1, or 2 arguments. If no parameter is given,
  60. it returns the current application window title. If one parameter is
  61. passed, both the window title and icon title will be set to its value.
  62. If two parameters are passed the window title will be set to the first,
  63. and the icon title to the second.
  64. =head2 delay( $ms )
  65. C<SDLx::App::delay> takes 1 argument, and will sleep the application for
  66. that many ms.
  67. =head2 ticks
  68. C<SDLx::App::ticks> returns the number of ms since the application began.
  69. =head2 error
  70. C<SDLx::App::error> returns the last error message set by the SDL.
  71. =head2 resize( $width, $height )
  72. C<SDLx::App::resize> takes a new width and height of the application. Only
  73. works if the application was originally created with the resizable option.
  74. =head2 fullscreen
  75. C<SDLx::App::fullscreen> toggles the application in and out of fullscreen mode.
  76. =head2 iconify
  77. C<SDLx::App::iconify> iconifies the application window.
  78. =head2 grab_input( $CONSTANT )
  79. C<SDLx::App::grab_input> can be used to change the input focus behavior of
  80. the application. It takes one argument, which should be one of the following:
  81. =over 4
  82. =item * SDL_GRAB_QUERY
  83. =item * SDL_GRAB_ON
  84. =item * SDL_GRAB_OFF
  85. =back
  86. =head2 sync
  87. C<SDLx::App::sync> encapsulates the various methods of synchronizing the screen with the
  88. current video buffer. C<SDLx::App::sync> will do a fullscreen update, using the double buffer
  89. or OpenGL buffer if applicable. This is preferred to calling flip on the application window.
  90. =head2 attribute( $attr )
  91. =head2 attribute( $attr, $value )
  92. C<SDLx::App::attribute> allows one to get and set GL attributes. By passing a value
  93. in addition to the attribute selector, the value will be set. C<SDL:::App::attribute>
  94. always returns the current value of the given attribute, or Carp::confess on failure.
  95. =head1 CALLBACKS
  96. C<SDLx::App> is a C<SDLx::Controller>. Use the event, show and handlers to run the app.
  97. use SDL;
  98. use SDLx::App;
  99. use SDL::Event; #Where ever the event call back is processed
  100. my $app = SDLx::App->new( width => 200, height => 200);
  101. $app->add_event_handler( sub{
  102. my ($event, $app) = @_;
  103. return $_[0]->type == SDL_QUIT ? 0 : 1;
  104. });
  105. $app->add_show_handler( sub{
  106. my ($delta, $app) = @_;
  107. $app->update;
  108. } );
  109. $app->add_move_handler( sub{
  110. my ($step, $app, $t) = @_;
  111. #calc your physics here
  112. } );
  113. $app->run();
  114. see L<SDLx::Controller> for more details.
  115. =head1 AUTHORS
  116. See L<SDL/AUTHORS>.
  117. =head1 SEE ALSO
  118. L<perl> L<SDL::Surface> L<SDL::Event> L<SDL::OpenGL>
  119. =cut