# This is the additional functionality available with the podzilla integration.
# 
#  NOTE: This file will be integrated into the proper README file.
# 	 This file is a placeholder for notes until that integraton is done
#



#################### ####################
# event callbacks from the pz2 engine

(setq t 0 x 0)				# for use below. ;)

# requesting function names
(setq pz2:Startup fname)		# called before windows are set up
(setq pz2:PreFlight fname) 		# called after windows are set up
(setq pz2:Shutdown fname) 		# called when the user exits to pz2

(setq pz2:Timer fname) 			# called if a timer is enabled

(setq pz2:Left fname)			# CCW rotation
(setq pz2:Right fname) 			# CW rotation
(setq pz2:Action fname) 		# center button pressed
(setq pz2:Play fname) 			# play button pressed
(setq pz2:Prev fname) 			# Previous |<< button pressed
(setq pz2:Next fname) 			# Next >>| button pressed
(setq pz2:Draw fname)			# redraw the screen


#################### ####################
# graphics routines

# for graphics functions, 0,0 is top left
#  (DrawPen	     red green blue mono )
			# "mono" is the color to use on monochrome ipods
			# it should be one of:  BLACK DKGRAY GRAY WHITE
#  (DrawPen2	     red green blue mono )	# used for gradient

#  (DrawPixel        x y )
#  (DrawLine         x1 y1 x2 y2 )
#  (DrawAALine       x1 y1 x2 y2 )
#  (DrawRect         x1 y1 x2 y2 )
#  (DrawFillRect     x1 y1 x2 y2 )
#  (DrawVGradient    x1 y1 x2 y2 )
#  (DrawHGradient    x1 y1 x2 y2 )
#  (DrawEllipse      x y w h )
#  (DrawAAEllipse    x y w h )
#  (DrawFillEllipse  x y w h )
#  (DrawVectorText   x y w h text )
#  (DrawVectorTextCentered   x y w h text )
#  (DrawClear        )

# unimplemented:
#  (DrawText         x y text )
#  (DrawPoly         x1 y1 x2 y2 ... )
#  (DrawFillPoly     x1 y1 x2 y2 ... )


#################### ####################
# misc routines

# (RandomOf a b c d)		# returns a random element in the list

# (Rand max)			# returns random number from 0 to max

# (RangeClip v min max)		# clips V to [min, max]
# (RangeWrap v min max)		# wraps V to [min, max] 
				# if bigger than max it goes to min etc


#################### ####################
# variables:

# Name			Read/Write	Description

# pz2:Frames 		Read		number of frames drawn since we started
# pz2:Ticks		Read		number of timer ticks have happened
# pz2:Width		Read		screen width
# pz2:Height		Read		screen height
# pz2:DirtyScreen	Write		Tells PZ to redraw the screen
# pz2:HeaderText	Write 		OnStartup - changes the podzilla header
# pz2:TimerMSec		Write		OnStartup - sets up the timer interval
# pz2:Persistent	Write		OnStartup - makes the widget not clear


# for future compatibility, this needs to be near the top of the file.
# NOTE: in the initial version, this is ignored.
(require  'pz2:0.8)

# if you want a timer, set this in the OnInit callback
(setq pz2:TimerMsec 1000)

# to change the header
(setq pz2:HeaderText "My Cool Thing")

# fullscreen option (do not call or set to 0 if you want a header
(setq pz2:FullScreen 1)

# to trigger a redraw, set this to 1 (in an event callback)
(setq pz2:DirtyScreen 1)

# to not clear the widget between OnDraw polls, set this to '1'
# otherwise, it gets cleared with whatever the 'bg' color is.
(setq pz2:Persistent 1)


# HINTS:
# to center something on the screen, use (/ Width 2) and (/ Height 2) 


#################### ####################
# future addtions:

# text routine to join text into a single item
# 	(DrawText ...  This Is A Test

# colors should be definable in variables
#	(setq red (255 0 0 WHITE) black (0 0 0 BLACK)))
#	(setq green (0 255 0 GRAY))

# getting data out of appearance/settings of podzilla itself from lisp
# 	(SetSetting "key" "value" )
#	(GetSetting "key" )
#	(GetApColor "key" )

# for loops
# 	(For (init) (conditional) (endofloop) (code) (return))

# defined/undefined checks of variables
#	(defvar *x*)
#	(undefvar *x*)
#	(defined x) 	returns T if it's defined somehow, NIL if not

# RandomOf should take a list as well
#	(RandomOf (list a b c d))

# FullScreen, DirtyScreen should be boolean T/NIL rather than Integer 1/0

# other things that might be defined:
#	ColorScreen
#	MonoScreen
#	Gen1 Gen2 Gen3 Gen4 Gen5 GenMini1 GenMini2 GenMini GenPhoto GenColor

# retrieval of system things
#  	(GetDateList)
#	returns a list of 7 items: hour, min, sec, day, month, monthint, year


################################################################################
Future TODO:

########## Bugfix:
(list	should not evaluate
(defun	should allow for multiple body elements

########## Bugfix:
>> (setf x 4)
4
>> x
4
>> (x)
NIL
>> '(x)
NIL


########## load
Recursively load the specified file, and evaluate it.

(load "filepath")
 - returns "T" if successfully loaded


########## expansion

convert the function list to be a registerable thing, to make it more 
easily expandable.  ie: register callbacks for c handlers, rather than a 
static array of function pointers.

