updated docs and path to my repo

[sdlgit/SDL-Site.git] / pages / SDL-App.html-inc

<div class="pod">
<!-- INDEX START -->
<h3 id="TOP">Index</h3>

<ul><li><a href="#NAME">NAME</a></li>
<li><a href="#CATEGORY">CATEGORY</a></li>
<li><a href="#SYNOPSIS">SYNOPSIS</a></li>
<li><a href="#DESCRIPTION">DESCRIPTION</a></li>
<li><a href="#METHODS">METHODS</a>
<ul><li><a href="#new">new</a></li>
<li><a href="#title">title</a></li>
<li><a href="#delay">delay</a></li>
<li><a href="#ticks">ticks</a></li>
<li><a href="#error">error</a></li>
<li><a href="#resize">resize</a></li>
<li><a href="#fullscreen">fullscreen</a></li>
<li><a href="#iconify">iconify</a></li>
<li><a href="#grab_input">grab_input</a></li>
<li><a href="#loop">loop</a></li>
<li><a href="#sync">sync</a></li>
<li><a href="#attribute_attr_value">attribute ( attr, [value] )</a></li>
</ul>
</li>
<li><a href="#AUTHOR">AUTHOR</a></li>
<li><a href="#SEE_ALSO">SEE ALSO</a>
</li>
</ul><hr />
<!-- INDEX END -->

<h1 id="NAME">NAME</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="NAME_CONTENT">
<p>SDL::App - a SDL perl extension</p>

</div>
<h1 id="CATEGORY">CATEGORY</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="CATEGORY_CONTENT">
<p>Extension</p>

</div>
<h1 id="SYNOPSIS">SYNOPSIS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SYNOPSIS_CONTENT">
<pre>    use SDL;
    use SDL::App; 
    use SDL::Event;
    use SDL::Events; 

    my $app = SDL::App-&gt;new( 
        -title  =&gt; 'Application Title',
        -width  =&gt; 640,
        -height =&gt; 480,
        -depth  =&gt; 32
    ); 

</pre>
<p>This is the manual way of doing things	</p>
<pre>    my $event = SDL::Event-&gt;new; # create a new event 

    SDL::Events::pump_events();

    while ( SDL::Events::poll_event($event) ) { 
        my $type = $event-&gt;type(); # get event type 
        print $type; 
        exit if $type == SDL_QUIT; 
    }

</pre>
<p>An alternative to the manual Event processing is the <a href="/SDL-App.html#loop">SDL::App::loop</a> .</p>

</div>
<h1 id="DESCRIPTION">DESCRIPTION</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="DESCRIPTION_CONTENT">
<p><a href="SDL-App.html">SDL::App</a> controls the root window of the of your SDL based application.
It extends the <a href="SDL-Surface.html">SDL::Surface</a> class, and provides an interface to the window
manager oriented functions.</p>

</div>
<h1 id="METHODS">METHODS</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="METHODS_CONTENT">

</div>
<h2 id="new">new</h2>
<div id="new_CONTENT">
<p><code>SDL::App::new</code> initializes the SDL, creates a new screen,
and initializes some of the window manager properties.
<code>SDL::App::new</code> takes a series of named parameters:</p>
<ul>
		<li>-title	</li>
		<li>-icon_title	</li>
		<li>-icon	</li>
		<li>-width	</li>
		<li>-height	</li>
		<li>-depth	</li>
		<li>-flags	</li>
		<li>-resizeable</li>
</ul>


</div>
<h2 id="title">title</h2>
<div id="title_CONTENT">
<p><code>SDL::App::title</code> takes 0, 1, or 2  arguments.  It returns the current
application window title.  If one parameter is passed, both the window
title and icon title will be set to its value.  If two parameters are
passed the window title will be set to the first, and the icon title
to the second.</p>

</div>
<h2 id="delay">delay</h2>
<div id="delay_CONTENT">
<p><code>SDL::App::delay</code> takes 1 argument, and will sleep the application for
that many ms.</p>

</div>
<h2 id="ticks">ticks</h2>
<div id="ticks_CONTENT">
<p><code>SDL::App::ticks</code> returns the number of ms since the application began.</p>

</div>
<h2 id="error">error</h2>
<div id="error_CONTENT">
<p><code>SDL::App::error</code> returns the last error message set by the SDL.</p>

</div>
<h2 id="resize">resize</h2>
<div id="resize_CONTENT">
<p><code>SDL::App::resize</code> takes a new height and width of the application
if the application was originally created with the -resizable option.</p>

</div>
<h2 id="fullscreen">fullscreen</h2>
<div id="fullscreen_CONTENT">
<p><code>SDL::App::fullscreen</code> toggles the application in and out of fullscreen mode.</p>

</div>
<h2 id="iconify">iconify</h2>
<div id="iconify_CONTENT">
<p><code>SDL::App::iconify</code> iconifies the applicaiton window.</p>

</div>
<h2 id="grab_input">grab_input</h2>
<div id="grab_input_CONTENT">
<p><code>SDL::App::grab_input</code> can be used to change the input focus behavior of
the application.  It takes one argument, which should be one of the following:</p>
<dl>
	<dt>*
SDL_GRAB_QUERY</dt>
	<dt>*
SDL_GRAB_ON</dt>
	<dt>*
SDL_GRAB_OFF</dt>
</dl>

</div>
<h2 id="loop">loop</h2>
<div id="loop_CONTENT">
<p><code>SDL::App::loop</code> is a simple event loop method which takes a reference to a hash
of event handler subroutines.  The keys of the hash must be SDL event types such
as SDL_QUIT(), SDL_KEYDOWN(), and the like.  The event method recieves as its parameter 
the event object used in the loop.</p>
<p>Example:</p>
<pre>    my $app = SDL::App-&gt;new(
        -title  =&gt; &quot;test.app&quot;, 
        -width  =&gt; 800, 
        -height =&gt; 600, 
        -depth  =&gt; 32
    );

    my %actions = (
        SDL_QUIT()    =&gt; sub { exit(0); },
        SDL_KEYDOWN() =&gt; sub { print &quot;Key Pressed&quot; },
    );

    $app-&gt;loop( \%actions );

</pre>

</div>
<h2 id="sync">sync</h2>
<div id="sync_CONTENT">
<p><code>SDL::App::sync</code> encapsulates the various methods of syncronizing the screen with the
current video buffer.  <code>SDL::App::sync</code> will do a fullscreen update, using the double buffer
or OpenGL buffer if applicable.  This is prefered to calling flip on the application window.</p>

</div>
<h2 id="attribute_attr_value">attribute ( attr, [value] )</h2>
<div id="attribute_attr_value_CONTENT">
<p><code>SDL::App::attribute</code> allows one to set and get GL attributes.  By passing a value
in addition to the attribute selector, the value will be set.  <code>SDL:::App::attribute</code>
always returns the current value of the given attribute, or croaks on failure.</p>

</div>
<h1 id="AUTHOR">AUTHOR</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="AUTHOR_CONTENT">
<p>David J. Goehrig
Kartik Thakore</p>

</div>
<h1 id="SEE_ALSO">SEE ALSO</h1><p><a href="#TOP" class="toplink">Top</a></p>
<div id="SEE_ALSO_CONTENT">
<p><a href="http://search.cpan.org/perldoc?perl">perl</a> <a href="SDL-Surface.html">SDL::Surface</a> <a href="SDL-Event.html">SDL::Event</a>  <a href="SDL-OpenGL.html">SDL::OpenGL</a></p>

</div>
</div>