From 7a0bda7bf4da3790bb043584bdeb3d83008ff730 Mon Sep 17 00:00:00 2001 From: bdeket Date: Fri, 11 Sep 2020 14:34:20 +0200 Subject: [PATCH 1/3] legend: update documentation --- plot-doc/plot/scribblings/contracts.scrbl | 8 ++++++++ plot-doc/plot/scribblings/params.scrbl | 2 +- plot-doc/plot/scribblings/plotting.scrbl | 18 ++++++++++++++++-- 3 files changed, 25 insertions(+), 3 deletions(-) diff --git a/plot-doc/plot/scribblings/contracts.scrbl b/plot-doc/plot/scribblings/contracts.scrbl index 231abb24..6ddeeb83 100644 --- a/plot-doc/plot/scribblings/contracts.scrbl +++ b/plot-doc/plot/scribblings/contracts.scrbl @@ -50,6 +50,14 @@ 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 #f anchor/c + (list/c (one-of/c 'inside 'outside) anchor/c))]{ +The contract for the @(racket plot-legend-anchor) parameter. + +This will place the legend inside or outside the plot-area, or not draw it at all in case of @racket[#f]. +A single @racket[anchor] will be interpreted the same as @racket[(list 'inside anchor)] +An @racket['auto] anchor will be interpreted as @racket['top-left].} + @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..6f7df49a 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?)]{ @@ -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?)]{ @@ -187,6 +187,20 @@ These procedures accept the same arguments as @(racket plot) and @(racket plot3d Use these if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot)-like functions with different backends. } +@deftogether[((defproc (legend-pict [renderer-tree (treeof (or/c renderer2d? nonrenderer?))] + [#:x-min x-min (or/c rational? #f) #f] [#:x-max x-max (or/c rational? #f) #f] + [#:y-min y-min (or/c rational? #f) #f] [#:y-max y-max (or/c rational? #f) #f]) + pict?) + (defproc (legend3d-pict [renderer-tree (treeof (or/c renderer3d? nonrenderer?))] + [#:x-min x-min (or/c rational? #f) #f] [#:x-max x-max (or/c rational? #f) #f] + [#:y-min y-min (or/c rational? #f) #f] [#:y-max y-max (or/c rational? #f) #f] + [#:z-min z-min (or/c rational? #f) #f] [#:z-max z-max (or/c rational? #f) #f]) + pict?) + (defproc (plot+legend-picts [ ] ...) (values pict? pict?)) + (defproc (plot+legend3d-picts [ ] ...) (values pict? pict?)))]{ +Plot the legend to a separate pict. The plot+legend form will not accept the @racket[#:legend-anchor] keyword. +} + @section{Pict-Plotting Work-a-Likes} @declare-exporting[plot/pict] From 64f726d181845b44a08455963846850f9f6d3b07 Mon Sep 17 00:00:00 2001 From: bdeket Date: Mon, 21 Sep 2020 20:30:54 +0200 Subject: [PATCH 2/3] legend: update doc for latest changes --- plot-doc/plot/scribblings/contracts.scrbl | 30 ++++++++++++++++++----- plot-doc/plot/scribblings/plotting.scrbl | 18 ++------------ 2 files changed, 26 insertions(+), 22 deletions(-) diff --git a/plot-doc/plot/scribblings/contracts.scrbl b/plot-doc/plot/scribblings/contracts.scrbl index 6ddeeb83..21331c23 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,13 +50,31 @@ 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 #f anchor/c - (list/c (one-of/c 'inside 'outside) anchor/c))]{ +@defthing[legend-anchor/c contract? #:value (or/c anchor/c + (one-of/c 'no-legend + '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))]{ The contract for the @(racket plot-legend-anchor) parameter. -This will place the legend inside or outside the plot-area, or not draw it at all in case of @racket[#f]. -A single @racket[anchor] will be interpreted the same as @racket[(list 'inside anchor)] -An @racket['auto] anchor will be interpreted as @racket['top-left].} +When the @racket[legend-anchor] is an @racket[anchor/c] this will place the legend inside the plot area. For @racket['auto] the legend will be drawn as if it was @racket['top-left]. + +If the @racket[legend-anchor] is @racket['no-legend], the legend will be omitted from the plot. + +For @racket['outside-top-left] to @racket['outside-bottom-right] the legend will be drawn outside the + plot-area. For 2D plots the alignment will be with the plot-area. For 3D plots the alignment is with + the overall width and height. The difference between @racket['outside-top-left] and + @racket['outside-left-top] is that the first will place the legend above the plot-area, with their + left sides aligned. Whereas the second is plotted on the left side of the plot-area with the top + border of the legend and the plot-area aligned. + +When the @racket[legend-anchor] is @racket['outside-global-top] the legend will be printed above the + plot-area, but centered on the complete width. Note that for 3D plots there is no difference between + this and @racket['outside-top] + +@history[#:added "7.9"]} @defthing[color/c contract? #:value (or/c (list/c real? real? real?) string? symbol? diff --git a/plot-doc/plot/scribblings/plotting.scrbl b/plot-doc/plot/scribblings/plotting.scrbl index 6f7df49a..dc98a9f5 100644 --- a/plot-doc/plot/scribblings/plotting.scrbl +++ b/plot-doc/plot/scribblings/plotting.scrbl @@ -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?))] @@ -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 [ ] ...) @@ -187,20 +187,6 @@ These procedures accept the same arguments as @(racket plot) and @(racket plot3d Use these if you need to continually update a plot on a @(racket canvas%), or to create other @(racket plot)-like functions with different backends. } -@deftogether[((defproc (legend-pict [renderer-tree (treeof (or/c renderer2d? nonrenderer?))] - [#:x-min x-min (or/c rational? #f) #f] [#:x-max x-max (or/c rational? #f) #f] - [#:y-min y-min (or/c rational? #f) #f] [#:y-max y-max (or/c rational? #f) #f]) - pict?) - (defproc (legend3d-pict [renderer-tree (treeof (or/c renderer3d? nonrenderer?))] - [#:x-min x-min (or/c rational? #f) #f] [#:x-max x-max (or/c rational? #f) #f] - [#:y-min y-min (or/c rational? #f) #f] [#:y-max y-max (or/c rational? #f) #f] - [#:z-min z-min (or/c rational? #f) #f] [#:z-max z-max (or/c rational? #f) #f]) - pict?) - (defproc (plot+legend-picts [ ] ...) (values pict? pict?)) - (defproc (plot+legend3d-picts [ ] ...) (values pict? pict?)))]{ -Plot the legend to a separate pict. The plot+legend form will not accept the @racket[#:legend-anchor] keyword. -} - @section{Pict-Plotting Work-a-Likes} @declare-exporting[plot/pict] From e1dabdf53a8052a91c6a2a39c64f44d41b09c776 Mon Sep 17 00:00:00 2001 From: bdeket Date: Tue, 22 Sep 2020 06:35:23 +0200 Subject: [PATCH 3/3] legend: doc review --- plot-doc/plot/scribblings/contracts.scrbl | 44 +++++++++++++---------- 1 file changed, 25 insertions(+), 19 deletions(-) diff --git a/plot-doc/plot/scribblings/contracts.scrbl b/plot-doc/plot/scribblings/contracts.scrbl index 21331c23..40f0f781 100644 --- a/plot-doc/plot/scribblings/contracts.scrbl +++ b/plot-doc/plot/scribblings/contracts.scrbl @@ -51,28 +51,34 @@ 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 'no-legend - 'outside-top-left 'outside-top 'outside-top-right + (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))]{ -The contract for the @(racket plot-legend-anchor) parameter. - -When the @racket[legend-anchor] is an @racket[anchor/c] this will place the legend inside the plot area. For @racket['auto] the legend will be drawn as if it was @racket['top-left]. - -If the @racket[legend-anchor] is @racket['no-legend], the legend will be omitted from the plot. - -For @racket['outside-top-left] to @racket['outside-bottom-right] the legend will be drawn outside the - plot-area. For 2D plots the alignment will be with the plot-area. For 3D plots the alignment is with - the overall width and height. The difference between @racket['outside-top-left] and - @racket['outside-left-top] is that the first will place the legend above the plot-area, with their - left sides aligned. Whereas the second is plotted on the left side of the plot-area with the top - border of the legend and the plot-area aligned. - -When the @racket[legend-anchor] is @racket['outside-global-top] the legend will be printed above the - plot-area, but centered on the complete width. Note that for 3D plots there is no difference between - this and @racket['outside-top] + '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"]}