diff --git a/plot-doc/plot/scribblings/contracts.scrbl b/plot-doc/plot/scribblings/contracts.scrbl index 231abb24..40f0f781 100644 --- a/plot-doc/plot/scribblings/contracts.scrbl +++ b/plot-doc/plot/scribblings/contracts.scrbl @@ -34,7 +34,7 @@ Identifies values that meet the contract @racket[elem-contract], lists of such v 'left 'center 'right 'bottom-left 'bottom 'bottom-right 'auto)]{ -The contract for @(racket anchor) arguments and parameters, such as @(racket plot-legend-anchor). +The contract for @(racket anchor) arguments and parameters. The @racket['auto] anchor will place labels so they are visible on the plot area. This anchor type is useful for @(racket point-label) and similar @@ -50,6 +50,38 @@ The @racket['auto] anchor is only valid for placement of text labels, for all other use cases, the @racket['auto] anchor is always the same as @racket['bottom-left].} +@defthing[legend-anchor/c contract? #:value (or/c anchor/c + (one-of/c 'outside-top-left 'outside-top 'outside-top-right + 'outside-left-top 'outside-left 'outside-left-bottom + 'outside-right-top 'outside-right 'outside-right-bottom + 'outside-bottom-left 'outside-bottom 'outside-bottom-right + 'outside-global-top + 'no-legend))]{ +The contract for the @racket[plot-legend-anchor] parameter and the +@racket[#:legend-anchor] parameters for the various plot procedures. + +When @racket[legend-anchor] is one of the symbols from @racket[anchor/c], the +legend will be placed inside the plot area. + +@racket[legend-anchor/c] values which start with "outside" will place the +legend outside the plot area, for 2D plots the legend will be aligned with the +plot area, while for 3D plots the legend will be relative to the overall +@racket[plot-width] and @racket[plot-height]. + +The @racket['outside-global-top] value will place the legend above the plot-area, +centered on the complete @racket[plot-width]. For 3D plots there is no +difference between this value and @racket['outside-top]. + +The value @racket['no-legend], will omit the legend from the plot, the legend +will also be omitted if none of the renderers have a @racket[#:label] +specified, regardless of the value used for @racket[#:legend-anchor]. + +The value @racket['auto], will place the legend in the top-left corner of the +plot area, this is not usefull for plot legends, this anchor value is used for +renderers such as @racket[point-label]. + +@history[#:added "7.9"]} + @defthing[color/c contract? #:value (or/c (list/c real? real? real?) string? symbol? (is-a?/c color%))]{ diff --git a/plot-doc/plot/scribblings/params.scrbl b/plot-doc/plot/scribblings/params.scrbl index 3d8bd147..af26481a 100644 --- a/plot-doc/plot/scribblings/params.scrbl +++ b/plot-doc/plot/scribblings/params.scrbl @@ -101,7 +101,7 @@ The font size (in drawing units), face, and family of the title, axis labels, ti The font size (in drawing units), face, and family to prefer for the legend text. If set to @racket[#f], then the corresponding @racket[plot-font-X] parameter is used. } -@deftogether[((defparam plot-legend-anchor anchor anchor/c #:value 'top-left) +@deftogether[((defparam plot-legend-anchor legend-anchor legend-anchor/c #:value 'top-left) (defparam plot-legend-box-alpha alpha (real-in 0 1) #:value 2/3))]{ The placement of the legend and the opacity of its background. } diff --git a/plot-doc/plot/scribblings/plotting.scrbl b/plot-doc/plot/scribblings/plotting.scrbl index cd95b841..dc98a9f5 100644 --- a/plot-doc/plot/scribblings/plotting.scrbl +++ b/plot-doc/plot/scribblings/plotting.scrbl @@ -28,7 +28,7 @@ Each 3D plotting procedure behaves the same way as its corresponding 2D procedur [#:title title (or/c string? pict? #f) (plot-title)] [#:x-label x-label (or/c string? pict? #f) (plot-x-label)] [#:y-label y-label (or/c string? pict? #f) (plot-y-label)] - [#:legend-anchor legend-anchor anchor/c (plot-legend-anchor)] + [#:legend-anchor legend-anchor legend-anchor/c (plot-legend-anchor)] [#:out-file out-file (or/c path-string? output-port? #f) #f] [#:out-kind out-kind plot-file-format/c 'auto] ) (or/c (is-a?/c snip%) void?)]{ @@ -61,7 +61,7 @@ Here, the renderer draws in [-1,1] × [-1,1], but the plot area is [-1.5,1.5] × Please set the @(racket plot-foreground) and @(racket plot-background) parameters instead of using these keyword arguments. The @(racket #:lncolor) keyword argument is also accepted for backward compatibility but deprecated. It does nothing. -@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label"] +@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor"] } @defproc[(plot3d [renderer-tree (treeof (or/c renderer3d? nonrenderer?))] @@ -76,7 +76,7 @@ The @(racket #:lncolor) keyword argument is also accepted for backward compatibi [#:x-label x-label (or/c string? pict? #f) (plot-x-label)] [#:y-label y-label (or/c string? pict? #f) (plot-y-label)] [#:z-label z-label (or/c string? pict? #f) (plot-z-label)] - [#:legend-anchor legend-anchor anchor/c (plot-legend-anchor)] + [#:legend-anchor legend-anchor legend-anchor/c (plot-legend-anchor)] [#:out-file out-file (or/c path-string? output-port? #f) #f] [#:out-kind out-kind plot-file-format/c 'auto] ) (or/c (is-a?/c snip%) void?)]{ @@ -94,7 +94,7 @@ The @(racket #:lncolor) keyword argument is also accepted for backward compatibi The @(racket #:az) and @(racket #:alt) keyword arguments are backward-compatible, deprecated aliases for @(racket #:angle) and @(racket #:altitude), respectively. -@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label, #:y-label and #:z-label"] +@history[#:changed "7.9" "Added support for pictures for #:title, #:x-label and #:y-label. And to plot the legend outside the plot-area with #:legend-anchor"] } @defproc[(plot-snip [ ] ...)