Commit | Line | Data |
896b04ee |
1 | =pod |
2 | |
3 | =head1 NAME |
4 | |
5 | SDL::Event - a SDL perl extension |
6 | |
7 | =head1 SYNOPSIS |
8 | |
9 | use SDL::Event; |
10 | my $event = new SDL::Event; # create a new event |
11 | $event->pump(); # pump all events from SDL Event Queue |
12 | $event->poll(); # Get the top one from the queue |
13 | while ($event->wait()) { |
14 | my $type = $event->type(); # get event type |
15 | # ... handle event |
16 | exit if $type == SDL_QUIT; |
17 | } |
18 | |
19 | =head1 DESCRIPTION |
20 | |
21 | C<SDL::Event> offers an object-oriented approach to SDL events. By creating |
22 | an instance of SDL::Event via new() you can wait for events, and then determine |
23 | the type of the event and take an appropriate action. |
24 | |
25 | =head1 EXAMPLE |
26 | |
27 | Here is an example of a simple event handler loop routine. |
28 | See also L<SDL::App::loop>. |
29 | |
30 | sub loop { |
31 | my ($self,$href) = @_; |
32 | my $event = new SDL::Event; |
33 | while ( $event->wait() ) { |
34 | # ... insert here your event handling like: |
35 | if ( ref($$href{$event->type()}) eq "CODE" ) { |
36 | &{$$href{$event->type()}}($event); |
37 | $self->sync(); |
38 | } |
39 | } |
40 | } |
41 | |
42 | =head1 METHODS |
43 | |
44 | =head2 new() |
45 | |
46 | Create a new event object.It returns a SDL::Event. |
47 | |
472bc0a1 |
48 | =head2 type(event) |
896b04ee |
49 | |
472bc0a1 |
50 | Returns the type of the SDL::Event given as first parameter, see list of exported symbols for which are |
896b04ee |
51 | available. |
52 | |
53 | =head2 pump() |
54 | |
55 | SDL::Events::pump gathers all the pending input information from devices and places |
56 | it on the event queue. |
57 | Without calls to pump no events would ever be placed on the queue. |
58 | Often the need for calls to pump is hidden from the user |
59 | since C</SDL::Events::poll> and C<SDL::Events::wait_event implicitly call pump. |
60 | However, if you are not polling or waiting for events (e.g. you are filtering them), |
61 | then you must call pump force an event queue update. |
62 | pump doesn't return any value and doesn't take any parameters. |
63 | |
64 | Note: You can only call this function in the thread that set the video mode. |
65 | |
66 | |
67 | =head2 poll(event) |
68 | |
69 | Polls for currently pending events. |
70 | If event is not undef, the next event is removed from the queue and returned as a C< SDL::Event>. |
71 | As this function implicitly calls C<SDL::Events::pump>, you can only call this function in the thread that set the video mode. |
72 | it take a SDL::Event as first parameter. |
73 | |
74 | =head2 wait(event) |
75 | |
76 | Waits indefinitely for the next available event, returning undef if there was an error while waiting for events, |
77 | a L< SDL::Event> otherwise. |
78 | If event is not NULL, the next event is removed. |
79 | As this function implicitly calls L<SDL::Events::pump>, you can only call this function in the thread that set the video mode. |
80 | WaitEvent take a SDL::Event as first parameter. |
81 | |
82 | =head2 set( type, state ) |
83 | |
84 | Set the state for all events of the given event's type |
85 | |
86 | =head2 set_unicode( toggle ) |
87 | |
88 | Toggle unicode on the event. |
89 | |
90 | =head2 set_key_repeat( delay, interval) |
91 | |
92 | Sets the delay and intervall of the key repeat rate (e.g. when a user |
93 | holds down a key on the keyboard). |
94 | |
95 | =head2 active_gain(event) |
96 | |
97 | active_gain return the active gain from the SDL::Event given as first parameter. |
98 | |
99 | =head2 active_state(event) |
100 | |
101 | active_state return the active state from the SDL::Event given as first parameter. |
102 | |
103 | =head2 key_state(event) |
104 | |
105 | key_state return the active key state from the SDL::Event given as first parameter. |
106 | |
107 | |
108 | =head2 key_sym(key) |
109 | |
110 | key_sym return the key pressed/released information from the SDL::Event given as first parameter. |
111 | |
112 | =head2 get_key_name(key) |
113 | |
114 | get_key_name get the name of an SDL virtual keysym. |
115 | it returns the key name. |
116 | |
117 | =head2 key_mod(event) |
118 | |
119 | key_mod return the mod keys pressed information from the SDL::Event given as first parameter. |
120 | |
121 | =head2 key_unicode(event) |
122 | |
123 | key_unicode return the unicode translated keys pressed/released information from the SDL::Event given as first parameter. |
124 | |
125 | =head2 key_scancode(event) * to move in SDL::Game::Keyboard |
126 | |
127 | key_scancode return the hardware specific keyboard scan code from the SDL::Event given as first parameter. |
128 | |
129 | =head2 motion_state(event) * to move in SDL::Game::Mouse |
130 | |
131 | motion_state return the state of the mouse button from the SDL::Event given as first parameter. |
132 | |
133 | =head2 motion_x(event) * to move in SDL::Game::Mouse |
134 | |
135 | Returns the motion of the mouse in X direction as an absolute value. |
136 | It take a SDL::Event as first parameter. |
137 | |
138 | =head2 motion_y(event) * to move in SDL::Game::Mouse |
139 | |
140 | Returns the motion of the mouse in Y direction as an absolute value. |
141 | It take a SDL::Event as first parameter. |
142 | |
143 | =head2 motion_xrel(event) * to move in SDL::Game::Mouse |
144 | |
145 | Returns the motion of the mouse in X direction as a relative value. |
146 | It take a SDL::Event as first parameter. |
147 | |
148 | =head2 motion_yrel(event) * to move in SDL::Game::Mouse |
149 | |
150 | Returns the motion of the mouse in Y direction as a relative value. |
151 | It take a SDL::Event as first parameter. |
152 | |
153 | =head2 button_state(event) * to move in SDL::Game::Mouse |
154 | |
155 | Returns the state of the mouse buttons. |
156 | It take a SDL::Event as first parameter. |
157 | |
158 | =head2 button_x(event) * to move in SDL::Game::Mouse |
159 | |
160 | Return the X position of the mouse at keypress.it take a SDL::Event as first parameter. |
161 | |
162 | =head2 button_y(event) * to move in SDL::Game::Mouse |
163 | |
164 | Return the Y position of the mouse at keypress.it take a SDL::Event as first parameter. |
165 | |
166 | =head2 button(event) * to move in SDL::Game::Mouse |
167 | |
168 | Return the mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT, SDL_BUTTON_WHEELUP, SDL_BUTTON_WHEELDOWN) |
169 | |
170 | =head1 AUTHOR |
171 | |
172 | David J. Goehrig |
173 | Documentation by Tels <http://bloodgate.com/> |
174 | |
175 | =head1 SEE ALSO |
176 | |
177 | L<perl> L<SDL::App> |
178 | |
179 | =cut |