doc.txt

> CdrSwift (Commander Swift) <

> CdrSwift (Commander Swift) <
==============================

This addition to slideshow was made to take advantage of functional reactivity;
for more details on Functional Reactive programming, signals, and event sources,
consult the documentation for the FrTime language. See TexPict and Slideshow
documentation for their standard features, and referece on the pict-structure
style.

To make a slideshow with these modifications, please make a module whose
language is 
(planet "slideshow.ss" ("dignatof" "cdrswift.plt" [Maj] [Min]))
where [Maj] is the major version number, and [Min] is the minor version
number (i.e. for version 1.2, use the language:
(planet "slideshow.ss" ("dignatof" "cdrswift.plt" 1 2)) )

The most significant difference between the old slideshow.ss language and the
new one is that mzscheme is no longer exported. In its place is the FrTime
language. The new version of slideshow acts as it used to wherever signals are
not used, as FrTime defaults to mzscheme evaluation when no behaviors or event
streams are used. In addition, a supplementary library has been provided to take
advantage of the new liberties granted with FrTime. These are outlined below:


> (set-dc-for-text-size) -> void
This sets dc-for-text-size to a bitmap dc; due to current problems with
parameters in FrTime, this is necessary for setting the dc-for-text-size.

> (make-reactive expr ...) -> stx (macro)
This macro is intended to be applied to a top level element of the slide's
content, where there is content that is meant to be reactive. In expr ...,
the identifiers slide-time, mouse-x, and mouse-y are available, as well as the
parameters current-slide/time, current-slide/mouse-x, and current-slide/mouse-y.
slide-time and current-slide/time are bound to a behavior of milliseconds which
reflects the amount of time that has passed since that slide appeared on the
screen, and goes to 0 when the slide is not on the screen. mouse-x and
current-slide/mouse-x reflects the x-position of the mouse when the slide is on
the screen, undefined otherwise. The same is true for mouse-y. For example, the
following evaluates to a slide that has a title "title" and has some text which
is the number of millieconds that have passed since the slide appeared on the
screen, and the text "milliseconds passed ...": 
(slide/title "title" (make-reactive (t (format "~a" (current-slide/time))))
		     (t "milliseconds passed ..."))
Also, this macro introduces the identifier key-events and the associated
parameter current-slide/key-events which is an event stream that emits an event
whenever a key is pressed or released (the event is in the form received in
on-subwindow-char). This stream only represents those pressed while their slide
is on the page.

		   


> (repeat/0->1 duration) -> number
This evaluates to a behavior that repeatedly goes through the numbers between 0
and 1 over the course of 'duration' milliseconds. For example, 
(slide (make-reactive (disk (* 100 (add1 (repeat/0->1 1000))))))
will make a slide there there is a filled circle whose diameter grows from 100
to 200 every second, before starting over agian.


> (wave wave-duration) -> number
This evaluates to a behavior that goes from 0 to 1 and back to 0 smoothly every
'wave-duration' milliseconds:
(slide (make-reactive (disk (* 100 (add1 (wave 1000))))))
This will make a slide that has a filled circle whose diameter grows from 100 to
200 over the course of 500 milliseconds, then shrink back to 100 over the
following 500 milliseconds, and then repeats.


> (transition/delay start-val wait end-val) -> pict
This evaluates to a behavior whose value is start-val, until 'wait' milliseconds
have passed, when it becomes end-val:
(slide (make-reactive (transition/delay (disk 100) 1324 (disk 200))))
evalueates to a slide that has a disk with a diameter of 100 for the first 1324
milliseconds, then becomes a disk of diameter 200.


> (transition/thunk start-val wait end-thunk) -> pict
Like transition/delay, but the end-thunk only gets evaluated after 'wait'
milliseconds have passed.


> (transition/new-time start-val wait end-thunk) -> pict
Like transition/thunk, except the perceived time that has passed is reset when
the end-thunk is evaluated. To contrast:
(slide (make-reactive (transition/thunk (disk 100)
					1000
					(lambda () 
					 (disk (* 100 
					       (add1 (wave 2000))))))))
will produce a slide with a disk of diameter 100 that becomes a disk of diameter
200 after a second, and which will then smoothly transition back and forth
between 200 and 100 diameter, but
(slide (make-reactive (transition/new-time (disk 100)
						1000
						(lambda () 
						 (disk (* 100 
						 (add1 (wave 2000))))))))
will make a slide with a disk of diameter 100 that become a disk of diameter
that changes from 100 to 200 after a second. In general, when composing these
transitions, transition/delay and transition/new-time will be the easiest to
reason about and use.


> (transition/trigger-thunk start-thunk trigger end-thunk) -> pict
This creates a behavior that will have the value of evaluating the start-thunk
while trigger is true, and re-evaluating it whenever trigger becomes true, and
will have the value of evaluating end-thunk while trigger is false, and
re-evaluating it whenever trigger becomes false.

> (make-stager rewind-char advance-char) This takes two characters, and
returns a behavior of number. The number is incremented whenever the key
corresponding to advance-char is pressed, and is decremented (though not below
zero) whenever rewind-char is pressed. This can be used to get 'next and 'alts
like functionality with content inside make-reactive.
(slide/title "Staged Slide"
               (make-reactive
                (let ([stage (make-stager #\w #\e)])
                  (if (>= stage 1)
                      (colorize
                       (disk (* 100 (add1 (wave 2000))))
                       (if (>= stage 2)
                           "lightsteelblue"
                           "black"))
                      (blank)))))
Will produce a slide, which has a disk, which appears, disappears, and changes
color depending on how many times the w and e keys have been pressed.


When making a procedure that will evaluate to a reactive pict, it is recommended
that the following form is used:
(define (fn-name arg ...)
  (let ([slide-time (current-slide/time)]
   	[mouse-x (current-slide/mouse-x)] ...)
	body ...))
for convenience and clarity of meaning. In general, using the current-slide/*
parameters will be the best way of going about writing reactive content
generators for slideshow. Using make-reactive in such a procedure is dangerous,
and may lead to unexpected behavior; restrict usage of make-reactive to
the top level of body elements of a slide:
(slide/title "title" 
		(t "hello-world!")
		(make-reactive (fn-name arg ...))
		(make-reactive (disk (* 100 (add1 (wave 2000)))))
		(t "end of slide"))
			
Currently, only slide/title supports behaviors as the title of a slide.
			
					
Most of the files in the slideshow library have been altered in small ways
(changing paths in requires, etc), viewer.ss being the main exception. All of
the changes and additions made occur between the comments:
;;; ADDED CODE
...
;;; END ADDED CODE
and often these comments will have supplementary information on the reasons for
the change, and their purpose.


Currently there is little support for clickable regions on the same page as
reactive content, and none for time-varying changes in the structure of 'next
'alt vonly/vnext constructed slides (i.e., you can use this library to include
a time-varying image as part of a slide that is displayed via the rules of
'next, but you cannot control how 'next creates slides in a time-varying manner:
(slide (make-reactive (disk (* 100 (add1 (wave 2000)))))
	'next
	(make-reactive (disk (* 200 (add1 (wave 2000))))))
is fine, but
(slide (disk 100)
	(make-reactive (if (even? (current-slide/time))
			'next
			'alts))
	(disk 200))
is not.)

If clickable regions are placed on a slide with reactive content, the region
that responds to the click will not change with time even if the image it was
placed around moves. If a time-varying image is used in a clickback, the slide
will produce errors at runtime.
	

Questions & Comments: dignatof [at] cs [dot] brown [dot] edu