add widescreen support

Author: mflatt

slideshow-doc/scribblings/slideshow/adjust-aspect.rkt

@@ -0,0 +1,20 @@
+#lang at-exp racket/base
+(require scribble/manual
+         (for-syntax racket/base))
+
+(provide declare-aspect-adjust
+         define-aspect-select)
+
+(define-syntax-rule (declare-aspect-adjust proc def)
+  (begin
+    (define-syntax-rule (define-it from-base)
+      (begin
+        (require (for-label (only-in slideshow/base [proc proc])))
+        (define from-base @racket[proc])))
+    (define-it from-base)
+    @defthing[proc procedure?]{
+         The same as @from-base frmo @racketmodname[slideshow/base], but with @racket[def] as the default
+         value of the @racket[#:aspect] argument.}))
+
+(define-syntax-rule (define-aspect-select id get-id def)
+  @defidform[id]{The same as @racket[(get-id def)].})

slideshow-doc/scribblings/slideshow/aspect.scrbl

@@ -0,0 +1,35 @@
+#lang scribble/doc
+@(require "ss.rkt")
+
+@title[#:tag "aspect"]{Fullscreen vs. Widescreen Aspect Ratio}
+
+Fullscreen (4:3) versus widescreen (16:9) aspect mode is a property of
+an individual slide that can be selected using the @racket[#:aspect]
+argument to @racket[slide]. The @racketmodname[slideshow/widescreen]
+language provides a variant of @racket[slide] that makes
+@racket['widescreen] the default value of @racket[#:aspect], while
+@racketmodname[slideshow/fullscreen] provides a variant of
+@racket[slide] that makes @racket['fullscreen] the default.
+
+When a slide's aspect is not specified, then it adopts an aspect that
+can be selected via the @DFlag{widescreen} or @DFlag{fullscreen} flag
+when Slideshow starts. (That selection can be made ``sticky'' as the
+default for future runs by using the @DFlag{save-aspect} flag.)
+Selecting an aspect also affects the values of @racket[client-w],
+@racket[client-h], @racket[full-page], and @racket[titleless-page]
+from @racketmodname[slideshow], but it does not affect the bindings
+from @racketmodname[slideshow/widescreen] or
+@racketmodname[slideshow/fullscreen]. Keep in mind that specifying
+@racket[#:aspect] for @racket[slide] does not affect the value of
+@racket[client-w], etc., for constructing the slide's content, but you
+can use @racket[get-client-w], etc., to obtain the aspect-specific
+metrics.
+
+Use the @racketmodname[slideshow] language for slides and libraries
+that are meant to adapt to a user's selected aspect, and use
+@racketmodname[slideshow/fullscreen] or
+@racketmodname[slideshow/widescreen] for slides and libraries that
+assume specific values for a slide's drawing area.
+
+@include-section["fullscreen.scrbl"]
+@include-section["widescreen.scrbl"]

slideshow-doc/scribblings/slideshow/fullscreen.scrbl

@@ -0,0 +1,28 @@
+#lang scribble/manual
+@(require (for-label slideshow/fullscreen/base)
+          "adjust-aspect.rkt")
+
+@title[#:tag "fullscreen"]{Fullscreen Slides}
+
+@declare-exporting[slideshow/fullscreen/base slideshow/fullscreen]
+
+@defmodulelang*/no-declare[(slideshow/fullscreen)]
+@defmodule*/no-declare[(slideshow/fullscreen/base)]
+
+The @racketmodname[slideshow/fullscreen/base] module is reprovided by
+the @racket[slideshow/fullscreen] language along with
+@racketmodname[racket] and @racketmodname[pict].
+
+@history[#:added "1.5"]
+
+@(declare-aspect-adjust slide 'fullscreen)
+@(declare-aspect-adjust para 'fullscreen)
+@(declare-aspect-adjust item 'fullscreen)
+@(declare-aspect-adjust subitem 'fullscreen)
+@(declare-aspect-adjust make-outline 'fullscreen)
+@(declare-aspect-adjust size-in-pixels 'fullscreen)
+
+@(define-aspect-select client-w get-client-w 'fullscreen)
+@(define-aspect-select client-h get-client-h 'fullscreen)
+@(define-aspect-select full-page full-page 'fullscreen)
+@(define-aspect-select titleless-page titleless-page 'fullscreen)

slideshow-doc/scribblings/slideshow/guide.scrbl

@@ -45,7 +45,7 @@ the presentation with a given content. For example, the ``Hello
 World'' presentation can be defined by the following module:
 
 @racketmod[
-slideshow
+slideshow (code:comment @#,t{or @racketmodname[slideshow/widescreen]})
 
 (slide
  #:title "How to Say Hello"
@@ -187,39 +187,44 @@ slideshow
 
 @; ------------------------------------------------------------------------
 
-@section[#:tag "display-size"]{Display Size and Fonts}
-
-Slideshow is configured for generating slides in @math{1024} by
-@math{768} pixel format. When the current display has a different
-size as Slideshow is started, the Slideshow display still
-occupies the entire screen, and pictures are scaled just before
-they are displayed. Thus, one picture unit reliably corresponds
-to a ``pixel'' that occupies @math{1/1024} by @math{1/768} of the
-screen.
-
-The @racket[text] form for generating text pictures takes into
-account any expected scaling for the display when measuring
-text. (All Slideshow text functions, such as @racket[t] and
-@racket[item] are built on @racket[text].) In particular, scaling
-the picture causes a different font size to be used for drawing
-the slide---rather than bitmap-scaling the original font---and
-changing the font size by a factor of @math{k} does not
-necessarily scale all text dimensions equally by a factor of
-@math{k}---because, for most devices, each character must have
-integer dimensions. Nevertheless, especially if you use the
-@racket[current-expected-text-scale] parameter, Slideshow is
-usually able to produce good results when the slide is scaled.
-
-More generally, different font sets on different platforms can
-change the way a slide is rendered. For example, the @racket[tt]
-font on one platform might be slightly wider than on another,
-causing different line breaks, and so on. Beware.
-
-Beware also of using bitmaps in slides when the presentation
-screen is not @math{1024} by @math{768}. In that case, consider
-using @racket[size-in-pixels] (with the caveat that the resulting
-picture will take up different amounts of the slide on different
-displays).
+@section[#:tag "display-size"]{Display Size and Font Selection}
+
+Slideshow is configured for generating slides in either @math{1024} by
+@math{768} for fullscreen (4:3) mode or @math{1360} by @math{766} for
+widescreen (16:9) mode. When the current display has a different size as
+Slideshow is started, the Slideshow display still occupies the entire
+screen, and pictures are scaled just before they are displayed. Thus,
+one picture unit reliably corresponds to a ``pixel'' that occupies
+@math{1/1024} by @math{1/768} of the screen or @math{1/1360} by
+@math{1/766} of the screen.
+
+Fullscreen versus widescreen mode is a property of an individual slide
+that can be selected using the @racket[#:aspect] argument to
+@racket[slide], but the default is to adapt to a mode that the user
+selects with @DFlag{widescreen} or @DFlag{fullscreen}. See
+@secref["aspect"] for more information.
+
+Beware that different font sets on different platforms can change the
+way a slide is rendered. For example, the @racket[tt] font on one
+platform might be slightly wider than on another, causing different
+line breaks, and so on. Beware also of using bitmaps in slides when
+the presentation screen's pixels do not exactly match the slide's
+drawing units. In that case, consider using @racket[size-in-pixels]
+(with the caveat that the resulting picture will take up different
+amounts of the slide on different displays).
+
+Finally, beware that the @racket[text] form for generating text
+pictures attempts to take into account any expected scaling for the
+display when measuring text. (All Slideshow text functions, such as
+@racket[t] and @racket[item] are built on @racket[text].) On some
+devices, scaling the picture potentially causes a different font size
+to be used for drawing the slide---rather than bitmap-scaling the
+original font---and changing the font size by a factor of @math{k}
+does not necessarily scale all text dimensions equally by a factor of
+@math{k}. Modern displays and drawing libraries make this scaling
+compensation a smaller effect than it used to be, but using
+@racket[current-expected-text-scale] parameter can sometimes improve
+text scaling.
 
 @; ------------------------------------------------------------------------
 

slideshow-doc/scribblings/slideshow/slides.scrbl

@@ -22,6 +22,7 @@
 
 @defproc[(slide [#:title title (or/c #f string? pict?) #f]
                 [#:name  name (or/c #f string?) title]
+                [#:aspect aspect aspect? #f]
                 [#:layout layout (or/c 'auto 'center 'top 'tall) 'auto]
                 [#:gap-size sep-gap-size real? (current-gap-size)]
                 [#:inset inset slide-inset? (make-slide-inset 0 0 0 0)]
@@ -69,7 +70,9 @@ after @racket[secs] seconds, and manual advancing skips this slide.
 
 If @racket[condense?] is true, then in condense mode (as specified by
 the @Flag{c} command-line flag), the slide is not created and
-registered.}
+registered.
+
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
 
 @defproc[(t [str string?]) pict?]{
@@ -106,7 +109,8 @@ The normal way to make serif text. Returns @racket[(text str 'roman
 
 Creates title text. Returns @racket[((current-titlet) str)].}
 
-@defproc[(para [#:width width real? (current-para-width)]
+@defproc[(para [#:aspect aspect aspect? #f]
+               [#:width width real? ((get-current-para-width #:aspect aspect))]
                [#:align align (or/c 'left 'center 'right) 'left]
                [#:fill? fill? any/c #t]
                [#:decode? decode? any/c #t]
@@ -144,10 +148,13 @@ The @racket[align] argument specifies how to align lines within the
 paragraph.
 
 See the spacing between lines is determined by the
-@racket[current-line-sep] parameter.}
+@racket[current-line-sep] parameter.
+
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
 
-@defproc[(item [#:width width real? (current-para-width)]
+@defproc[(item [#:aspect aspect aspect? #f]
+               [#:width width real? ((get-current-para-width #:aspect aspect))]
                [#:gap-size sep-gap-size real? (current-gap-size)]
                [#:bullet blt pict? (scale bullet (/ sep-gap-size gap-size))]
                [#:align align (or/c 'left 'center 'right) 'left]
@@ -161,10 +168,13 @@ Like @racket[para], but with @racket[blt] followed by @racket[(/
 sep-gap-size 2)] space appended horizontally to the resulting paragraph,
 aligned with the top line. The paragraph width of @racket[blt] plus
 @racket[(/ sep-gap-size 2)] is subtracted from the maximum width of the
-paragraph.}
+paragraph.
 
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
-@defproc[(subitem [#:width width real? (current-para-width)]
+
+@defproc[(subitem [#:aspect aspect aspect? #f]
+                  [#:width width real? ((get-current-para-width #:aspect aspect))]
                   [#:gap-size sep-gap-size real? (current-gap-size)]
                   [#:bullet blt pict? (scale o-bullet (/ sep-gap-size gap-size))]
                   [#:align align (or/c 'left 'center 'right) 'left]
@@ -177,7 +187,9 @@ paragraph.}
 Like @racket[item], but an additional @racket[(* 2 sep-gap-size)] is
 subtracted from the paragraph width and added as space to the left of
 the pict. Also, @racket[o-bullet] is the default bullet, instead of
-@racket[bullet].}
+@racket[bullet].
+
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
 
 @defproc[(clickback [pict pict?] [thunk (-> any)])
@@ -199,12 +211,17 @@ must be a procedure that is called when the window is removed (because
 the slide changes, for example).}
 
 
-@defproc[(size-in-pixels [pict pict?]) pict?]{
+@defproc[(size-in-pixels [pict pict?]
+                         [#:aspect aspect aspect? #f])
+         pict?]{
 
 Scales @racket[pict] so that it is displayed on the screen as
 @racket[(pict-width pict)] pixels wide and @racket[(pict-height pict)]
 pixels tall. The result is @racket[pict] when using a 1024 by 768
-display.}
+display with a fullscreen aspect or when using a 1360 by 766
+display with a widescreen aspect.
+
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
 
 @defproc[(pict->pre-render-pict [pict pict?]) pict?]{
@@ -220,7 +237,8 @@ to reduce drawing times for for large bitmaps or complex drawings.
                        [title (or/c string? pict?)]
                        [subitems (or/c #f null?
                                        (symbol? . -> . pict?))]
-                       ...)
+                       ...
+                       [#:aspect aspect aspect? #f])
           (symbol? . -> . void?)]{
 
 Returns a function that takes a symbol and generates an outline
@@ -245,7 +263,9 @@ trio of arguments defines a section for the outline:
        should be a function that takes a symbol (the same one passed
        to the outline maker) and produces a pict.}
 
-]}
+]
+
+@history[#:changed "1.5" @elem{Added the @racket[#:aspect] argument.}]}
 
 @defproc[(comment [text (or/c string? pict?)] ...)
          comment?]{
@@ -364,6 +384,20 @@ this function with @racket[#t] enables new slides to start a new slideshow.
 
 @section{Constants and Layout Variables}
 
+@defproc[(aspect? [v any/c]) boolean?]{
+
+Return @racket[#t] if @racket[v] is @racket['fullscreen],
+@racket['widescreen], or @racket[#f], otherwise returns @racket[#f].
+
+A symbolic @racket[v] selects a specific aspect, while @racket[#f] as
+an aspect corresponds to a user-selected aspect through the
+@DFlag{widescreen} or @DFlag{fullscreen} flag.
+
+See also @seclink["aspect"].
+
+@history[#:added "1.5"]}
+
+
 @defthing[gap-size 24]{
 
 A width commonly used for layout.}
@@ -399,32 +433,56 @@ It's implementation is:
                (blank 0 gap-size)))]
 }
 
+@deftogether[(
+@defidform[client-w]
+@defproc[(get-client-w [#:aspect aspect aspect? #f]) exact-nonnegative-integer?]
+)]{
 
-@defidform[client-w]{
+Produces the width of the display area, minus @racket[margin]s for a
+given @racket[aspect], where @racket[client-w] is equivalent to
+@racket[(get-client-w)]. The result changes if the margin is adjusted
+via @racket[set-margin!].
 
-Produces the width of the display area, minus @racket[margin]s. The
-result of the form changes if the margin is adjusted via
-@racket[set-margin!].}
+@history[#:changed "1.5" @elem{Added @racket[get-client-w].}]}
 
 
-@defidform[client-h]{
+@deftogether[(
+@defidform[client-h]
+@defproc[(get-client-h [#:aspect aspect aspect? #f]) exact-nonnegative-integer?]
+)]{
 
-Produces the height of the display area, minus @racket[margin]s, but
-including the title area). The result of the form changes if the
-margin is adjusted via @racket[set-margin!].}
+Produces the height of the display area, minus @racket[margin]s for a
+given @racket[aspect], where @racket[client-h] is equivalent to
+@racket[(get-client-h)]. The result changes if the margin is adjusted
+via @racket[set-margin!].
 
+@history[#:changed "1.5" @elem{Added @racket[get-client-h].}]}
 
-@defidform[full-page]{
+
+@deftogether[(
+@defidform[full-page]
+@defproc[(get-full-page [#:aspect aspect aspect? #f]) pict?]
+)]{
 
 Produces an empty pict that is the same size as the client area, which
-is like @racket[(blank client-w client-h)].}
+is like @racket[(blank client-w client-h)]. The @racket[full-page]
+form is equivalent to @racket[(get-full-page)].
+
+@history[#:changed "1.5" @elem{Added @racket[get-full-page].}]}
 
 
-@defidform[titleless-page]{
+@deftogether[(
+@defidform[titleless-page]
+@defproc[(get-titleless-page [#:aspect aspect aspect? #f]) pict?]
+)]{
 
 Produces an empty pict that is the same size as the client area minus
 the title area in @racket['top] layout mode, which is like
-@racket[(blank client-w (- client-h title-h (* 2 gap-size)))].}
+@racket[(blank client-w (- client-h title-h (* 2 gap-size)))]. The
+@racket[titleless-page] form is equivalent to
+@racket[(get-titleless-page)].
+
+@history[#:changed "1.5" @elem{Added @racket[get-titleless-page].}]}
 
 
 @defidform[margin]{
@@ -485,10 +543,18 @@ Parameter that controls the amount of space used between lines by
 @racket[para], @racket[item], and @racket[subitem].}
 
 
-@defparam[current-para-width n exact-nonnegative-integer?]{
+@deftogether[(
+@defparam[current-para-width n exact-nonnegative-integer?]
+@defproc[(get-current-para-width (#:aspect aspect aspect? #f))
+         (parameter/c exact-nonnegative-integer?)]
+)]{
 
 Parameter that controls the width of a pict created by
-@racket[para], @racket[item], and @racket[subitem].}
+@racket[para], @racket[item], and @racket[subitem]. The value
+of @racket[current-para-width] is the same as
+@racket[(get-current-para-width)].
+
+@history[#:changed "1.5" @elem{Added @racket[get-current-para-width].}]}
 
 
 @defparam[current-title-color color (or/c string? (is-a?/c color%))]{