Update of /project/pal/cvsroot/pal/documentation In directory clnet:/tmp/cvs-serv9747

Modified Files: pal-manual.lyx Added Files: pal-manual.pdf Log Message: Updated the manual

--- /project/pal/cvsroot/pal/documentation/pal-manual.lyx 2007/10/18 16:41:02 1.1 +++ /project/pal/cvsroot/pal/documentation/pal-manual.lyx 2007/10/18 19:29:56 1.2 @@ -269,77 +269,1391 @@ \end_layout

\begin_layout Subsection -OPEN-PAL +Introduction \end_layout

\begin_layout Subsection -CLOSE-PAL +Functions +\end_layout + +\begin_layout Description +OPEN-PAL (&key +\shape italic +width height fps title fullscreenp paths +\shape default +) +\end_layout + +\begin_layout Standard +Opens and initialises PAL window. +\end_layout + +\begin_layout Description + +\shape italic +width +\shape default +, width of the screen. +\end_layout + +\begin_layout Description + +\shape italic +height +\shape default +, height of the screen. + If width and height are 0 then the default desktop dimensions are used. +\end_layout + +\begin_layout Description + +\shape italic +fps +\shape default +, maximum number of times per second that the screen is updated. +\end_layout + +\begin_layout Description + +\shape italic +title +\shape default +, title of the screen. +\end_layout + +\begin_layout Description + +\shape italic +fullscreenp +\shape default +, open in windowed or fullscreen mode. +\end_layout + +\begin_layout Description + +\shape italic +paths +\shape default +, pathname or list of pathnames that the load-* functions use to find resources. + Initially holds *default-pathname-defauls* and PAL installation directory. +\end_layout + +\begin_layout Description +CLOSE-PAL () +\end_layout + +\begin_layout Standard +Closes PAL screen and frees all loaded resources. +\end_layout + +\begin_layout Description +WITH-PAL (&key +\shape italic +width height fps title fullscreenp paths +\shape default + &body +\shape italic +body +\shape default +) +\end_layout + +\begin_layout Standard +Opens PAL, executes +\shape italic +body +\shape default + and finally closes PAL. + Arguments are same as with OPEN-PAL. +\end_layout + +\begin_layout Description +FREE-RESOURCE ( +\shape italic +resource +\shape default +) +\end_layout + +\begin_layout Standard +Frees the +\shape italic +resource +\shape default + (image, font, sample or music). +\end_layout + +\begin_layout Description +FREE-ALL-RESOURCES () +\end_layout + +\begin_layout Standard +Frees all allocated resources. +\end_layout + +\begin_layout Description +WITH-RESOURCE ( +\shape italic +var init-form +\shape default +) &body +\shape italic +body +\end_layout + +\begin_layout Standard +Binds +\shape italic +var +\shape default + to the result of +\shape italic +init-form +\shape default + and executes +\shape italic +body +\shape default +. + Finally calls FREE-RESOURCE on +\shape italic +var. +\end_layout + +\begin_layout Description +GET-SCREEN-WIDTH () => +\shape italic +number +\end_layout + +\begin_layout Description +GET-SCREEN-HEIGHT () => +\shape italic +number +\end_layout + +\begin_layout Standard +Returns the dimensions of PAL screen. +\end_layout + +\begin_layout Standard + +\newpage + +\end_layout + +\begin_layout Section +Event handling +\end_layout + +\begin_layout Subsection +Introduction +\end_layout + +\begin_layout Standard +There are two ways to handle events in PAL; the callback based HANDLE-EVENTS + or EVENT-LOOP that call given functions when an event happens, or directly + polling for key and mouse state with TEST-KEYS, KEY-PRESSED-P and GET-MOUSE-POS. +\end_layout + +\begin_layout Standard +NOTE: Even if you don't need to use the callback approach it is still necessary + to call HANDLE-EVENTS on regular intervals, especially on Windows. + Running an EVENT-LOOP does this automatically for you and is the preferred + way to handle events. +\end_layout + +\begin_layout Subsection +Functions +\end_layout + +\begin_layout Description +HANDLE-EVENTS (&key +\shape italic +key-up-fn key-down-fn mouse-motion-fn quit-fn +\shape default +) +\end_layout + +\begin_layout Standard +Get next event, if any, and call appropriate handler function. +\end_layout + +\begin_layout Description + +\shape italic +key-up-fn +\shape default +, called with the released key-sym. + For key-syms see chapter 3.3 +\end_layout + +\begin_layout Description + +\shape italic +key-down-fn +\shape default +, called with the pressed key-sym. + When +\shape italic +key-down-fn +\shape default + is not defined pressing Esc-key causes a quit event. +\end_layout + +\begin_layout Description + +\shape italic +mouse-motion-fn +\shape default +, called with x and y mouse coordinates. +\end_layout + +\begin_layout Description + +\shape italic +quit-fn +\shape default +, called without any arguments when user presses the windows close button. + Also called when Esc key is pressed, unless +\shape italic +key-down-fn +\shape default + is defined. +\end_layout + +\begin_layout Description +UPDATE-SCREEN () +\end_layout + +\begin_layout Standard +Updates the PAL screen. + No output is visible until UPDATE-SCREEN is called. + +\end_layout + +\begin_layout Description +EVENT-LOOP ((&key +\shape italic +key-up-fn key-down-fn mouse-motion-fn quit-fn +\shape default +) &body +\shape italic +body +\shape default +) +\end_layout + +\begin_layout Standard +Repeatedly calls +\shape italic +body +\shape default + between HANDLE-EVENT and UPDATE-SCREEN. + Arguments are the same as with HANDLE-EVENTS. + Returns when (return-from event-loop) is called, or, if quit-fn is not + given when quit event is generated. +\end_layout + +\begin_layout Description +GET-MOUSE-POS () => +\shape italic +vector +\shape default + +\end_layout + +\begin_layout Description +GET-MOUSE-X () => +\shape italic +number +\end_layout + +\begin_layout Description +GET-MOUSE-Y () => +\shape italic +number +\end_layout + +\begin_layout Standard +Returns the current position of mouse pointer. +\end_layout + +\begin_layout Description +SET-MOUSE-POS ( +\shape italic +vector +\shape default +) +\end_layout + +\begin_layout Standard +Sets the position of mouse pointer. +\end_layout + +\begin_layout Description +KEY-PRESSED-P ( +\shape italic +keysym +\shape default +) => +\shape italic +bool +\end_layout + +\begin_layout Standard +Test if the key +\shape italic +keysym +\shape default + is currently pressed down. + For keysyms see chapter 3.3 +\end_layout + +\begin_layout Description +TEST-KEYS (( +\shape italic +key +\shape default + | ( +\shape italic +keys +\shape default +) +\shape italic +form +\shape default +)) +\end_layout + +\begin_layout Standard +Tests if any of the given keys are currently pressed. + Evaluates +\shape italic +all +\shape default + matching forms. +\end_layout + +\begin_layout Standard +Example: +\end_layout + +\begin_layout Quotation +(test-keys +\end_layout + +\begin_layout Quotation +\InsetSpace ~ +\InsetSpace ~ +(:key-left (move-left sprite)) +\end_layout + +\begin_layout Quotation +\InsetSpace ~ +\InsetSpace ~ +(:key-right (move-right sprite)) +\end_layout + +\begin_layout Quotation +\InsetSpace ~ +\InsetSpace ~ +((:key-ctrl :key-mouse-1) (shoot sprite)) +\end_layout +

[1038 lines skipped]

--- /project/pal/cvsroot/pal/documentation/pal-manual.pdf 2007/10/18 19:29:56 NONE +++ /project/pal/cvsroot/pal/documentation/pal-manual.pdf 2007/10/18 19:29:56 1.1

[6855 lines skipped]