enable further customisation of the outlook of spot events

DESCRIPTION

@@ -1,6 +1,6 @@
 Package: ganttrify
 Title: Create beautiful Gantt charts with ggplot2
-Version: 0.0.0.9008
+Version: 0.0.0.9009
 Authors@R: 
     person(given = "Giorgio",
            family = "Comai (OBCT/CCI)",
@@ -11,7 +11,7 @@ Description: 'ganttrify' facilitates the creation of nice-looking Gantt charts,
 License: GPL-3
 Encoding: UTF-8
 LazyData: true
-RoxygenNote: 7.2.1
+RoxygenNote: 7.2.3
 Imports: 
     magrittr,
     tibble,

R/ganttrify.R

@@ -22,7 +22,15 @@
 #' @param colour_stripe Character, defaults to "lightgray". This is the stripe colour in the background used in alternate months.
 #' @param alpha_wp Numeric, defaults to 1. Controls transparency of the line used to represent WPs.
 #' @param alpha_activity Numeric, defaults to 1. Controls transparency of the line used to represent activities.
-#' @param line_end Character, defaults to "round". One of "round", "butt", "square". Controls line ends.
+#' @param line_end Character, defaults to NULL. If given, takes precedence over `line_end_wp` and `line_end_activity` and applies the value to both. One of "round", "butt", "square". Controls line ends.
+#' @param line_end_wp Character, defaults to "round". One of "round", "butt", "square". Controls line ends.
+#' @param line_end_activity Character, defaults to "butt". One of "round", "butt", "square". Controls line ends.
+#' @param spot_padding Unit, defaults to `ggplot2::unit(0.2, "lines")`. If you use spot events, this is the padding around the text. Smaller value are best for busy gantt charts; if you have lots of space or use larger font sizes you may want to increase this value.
+#' @param spot_fontface Defaults to "bold". Available values are "plain", "bold", "italic" and "bold.italic".
+#' @param spot_text_colour Defaults to "grey20", for a dark but not quite black text. 
+#' @param spot_size_text_relative Defaults to 1. This is combined with `size_text_relative`. 
+#' @param spot_fill Defaults to `ggplot2::alpha(c("white"), 1)`. This is the background fill colour of spot events. By default, it is set to solid white. If you want to add some transparency to enable visual continuity of the underlying lines, adjust the transparency value to your taste adapting the function used by default.
+#' @param spot_border Defaults to 0.25. Internally passed as `label.size` to `geom_label()`.  Set to 0 or NA to remove the border. 
 #' @param month_breaks Numeric, defaults to 1. It defines if labels for all months are shown or only once every x months. Useful for longer projects.
 #' @param show_vertical_lines Logical, defaults to TRUE. If set to FALSE, it hides the thin vertical lines corresponding to month numbers. Useful in particular for longer projects. 
 #' @param axis_text_align Character, defaults to "right". Defines alignment of text on the y-axis is left. Accepted values are "left", "right", "centre", or "center".
@@ -55,7 +63,15 @@ ganttrify <- function(project,
                       colour_stripe = "lightgray",
                       alpha_wp = 1,
                       alpha_activity = 1,
-                      line_end = "round",
+                      line_end = NULL,
+                      line_end_wp = "round",
+                      line_end_activity = "butt",
+                      spot_padding = ggplot2::unit(0.2, "lines"),
+                      spot_fill = ggplot2::alpha(c("white"),1),
+                      spot_text_colour = "gray20",
+                      spot_size_text_relative = 1,
+                      spot_fontface = "bold",
+                      spot_border = 0.25,
                       month_breaks = 1, 
                       show_vertical_lines = TRUE,
                       axis_text_align = "right") {
@@ -65,6 +81,11 @@ ganttrify <- function(project,
     colour_palette <- rep(colour_palette, length(unique(project$wp)))[1:length(unique(project$wp))]
   }
 
+  if (is.null(line_end)==FALSE) {
+    line_end_wp <- line_end
+    line_end_activity <- line_end
+  }
+
   if (label_wrap!=FALSE) {
     if (isTRUE(label_wrap)) {
       label_wrap <- 32
@@ -217,12 +238,12 @@ ganttrify <- function(project,
   gg_gantt <- gg_gantt +
     ### activities
     ggplot2::geom_segment(data = df_yearmon_fct,
-                          lineend = line_end,
+                          lineend = line_end_activity,
                           size = size_activity,
                           alpha = df_yearmon_fct$activity_alpha) +
     ### wp
     ggplot2::geom_segment(data = df_yearmon_fct,
-                          lineend = line_end,
+                          lineend = line_end_wp,
                           size = size_wp,
                           alpha = df_yearmon_fct$wp_alpha)
 
@@ -315,10 +336,13 @@ ganttrify <- function(project,
                             mapping = ggplot2::aes(x = spot_date,
                                                    y = activity,
                                                    label = spot_type),
-                            colour = "gray30",
-                            fontface = "bold",
+                            label.padding = spot_padding,
+                            label.size = spot_border,
+                            colour = spot_text_colour,
+                            fontface = spot_fontface,
                             family = font_family,
-                            size = 3*size_text_relative) 
+                            size = 3*size_text_relative*spot_size_text_relative,
+                            fill = spot_fill) 
     }
   } 
 

README.Rmd

@@ -44,7 +44,7 @@ More seriously, this has been a quick attempt at making decent-looking Gantt cha
 
 And yes, I will enable all the customisations you like, but first I actually need to submit this project.
 
-[Thanks to all who contributed suggestions via issues and pull request!]
+[Thanks to all who contributed suggestions via issues and pull requests!]
 
 ## Features
 
@@ -120,28 +120,57 @@ ganttrify(project = ganttrify::test_project,
           font_family = "Roboto Condensed")
 ```
 
+I felt that rounded line endings for the working packages, and "butt" ending for activities is the best combination of elegance and clarity. 
 
-I thought we all liked rounded lines and full opacity, but it's ok if you don't:
+Also, I like full opacity for the lines, but it's ok if you don't:
 
 ```{r gantt_butt_line_transparency}
 ganttrify(project = ganttrify::test_project,
           project_start_date = "2021-04",
           alpha_wp = 0.9,
           alpha_activity = 0.6,
-          line_end = "butt")
+          line_end_wp = "round", # alternative values: "butt" or "square"
+          line_end_activity = "round", # alternative values: "butt" or "square"
+          font_family = "Roboto Condensed")
 ```
+If you use spot events, then there's all sorts of opinions you can have about the color and transparency of spot events, as well as the size and padding around the text. Say, you want a larger box around the text, but a semi-transparent background? There you go!
 
+```{r spot_customisations}
+ganttrify(project = ganttrify::test_project,
+          spots = ganttrify::test_spots,
+          project_start_date = "2021-04",
+          font_family = "Roboto Condensed",
+          spot_size_text_relative = 1.5,
+          spot_fill = ggplot2::alpha(c("white"), 0.7),
+          spot_padding = ggplot2::unit(0.4, "lines")
+          ) 
+```
+Or perhaps you actually just want the label text, without any background, or perhaps change the text colour. Be mindful that the text may become hard to read on darker backgrounds, especially if reviewers then print your proposal, but... you have been warned:
+
+```{r spot_text}
+ganttrify(project = ganttrify::test_project,
+          spots = ganttrify::test_spots,
+          project_start_date = "2021-04",
+          font_family = "Roboto Condensed",
+          spot_text_colour = "grey10",
+          spot_fontface = "bold",
+          spot_fill = NA,
+          spot_border = NA
+          ) 
+```
 
 Some of us work on very long projects, and may need to declutter the chart to increase readability. So let's show the month number only once every three months, and hide the thin vertical lines included by default.
 
+
 ```{r gantt_36_months}
 test_36 <- ganttrify::test_project
 test_36[11,4] <- 36
 
 ganttrify(project = test_36,
           project_start_date = "2021-04", 
           month_breaks = 3,
-          show_vertical_lines = FALSE)
+          show_vertical_lines = FALSE,
+          font_family = "Roboto Condensed")
   
 ```
 
@@ -152,15 +181,17 @@ Does right-aligned text bother you?
 ganttrify(project = ganttrify::test_project,
           spots = ganttrify::test_spots,
           project_start_date = "2021-04",
-          axis_text_align = "left") 
+          axis_text_align = "left",
+          font_family = "Roboto Condensed") 
 ```
 
 ```{r gantt_centre_aligned}
 
 ganttrify(project = ganttrify::test_project,
           spots = ganttrify::test_spots,
           project_start_date = "2021-04",
-          axis_text_align = "centre") 
+          axis_text_align = "centre",
+          font_family = "Roboto Condensed") 
 ```
 
 Do you have *very* long names for your activities? The parameter `label_wrap` is there to help you.
@@ -177,8 +208,7 @@ tibble::tribble(~wp, ~activity, ~start_date, ~end_date,
 ```
 
 
-
-Finally, keep in mind that ganttrify outputs `ggplot` objects. Some theming options may not behave exactly as you expect, but for example adding title, subtitle, and captions can be done as you would normally do with any `ggplot` graphs. 
+Finally, keep in mind that ganttrify outputs `ggplot` objects. Some theming options may not behave exactly as you expect, but for example adding title, subtitle, and captions can be done as you would normally do with any `ggplot2` graph. 
 
 ```{r gantt_with_text}
 ganttrify(project = ganttrify::test_project,

README.md

@@ -56,7 +56,7 @@ And yes, I will enable all the customisations you like, but first I
 actually need to submit this project.
 
 \[Thanks to all who contributed suggestions via issues and pull
-request!\]
+requests!\]
 
 ## Features
 
@@ -163,18 +163,57 @@ ganttrify(project = ganttrify::test_project,
 
 <img src="man/figures/README-gantt_no_wp-1.png" width="100%" />
 
-I thought we all liked rounded lines and full opacity, but it’s ok if
-you don’t:
+I felt that rounded line endings for the working packages, and “butt”
+ending for activities is the best combination of elegance and clarity.
+
+Also, I like full opacity for the lines, but it’s ok if you don’t:
 
 ``` r
 ganttrify(project = ganttrify::test_project,
           project_start_date = "2021-04",
           alpha_wp = 0.9,
           alpha_activity = 0.6,
-          line_end = "butt")
+          line_end_wp = "round", # alternative values: "butt" or "square"
+          line_end_activity = "round", # alternative values: "butt" or "square"
+          font_family = "Roboto Condensed")
 ```
 
 <img src="man/figures/README-gantt_butt_line_transparency-1.png" width="100%" />
+If you use spot events, then there’s all sorts of opinions you can have
+about the color and transparency of spot events, as well as the size and
+padding around the text. Say, you want a larger box around the text, but
+a semi-transparent background? There you go!
+
+``` r
+ganttrify(project = ganttrify::test_project,
+          spots = ganttrify::test_spots,
+          project_start_date = "2021-04",
+          font_family = "Roboto Condensed",
+          spot_size_text_relative = 1.5,
+          spot_fill = ggplot2::alpha(c("white"), 0.7),
+          spot_padding = ggplot2::unit(0.4, "lines")
+          ) 
+```
+
+<img src="man/figures/README-spot_customisations-1.png" width="100%" />
+Or perhaps you actually just want the label text, without any
+background, or perhaps change the text colour. Be mindful that the text
+may become hard to read on darker backgrounds, especially if reviewers
+then print your proposal, but… you have been warned:
+
+``` r
+ganttrify(project = ganttrify::test_project,
+          spots = ganttrify::test_spots,
+          project_start_date = "2021-04",
+          font_family = "Roboto Condensed",
+          spot_text_colour = "grey10",
+          spot_fontface = "bold",
+          spot_fill = NA,
+          spot_border = NA
+          ) 
+```
+
+<img src="man/figures/README-spot_text-1.png" width="100%" />
 
 Some of us work on very long projects, and may need to declutter the
 chart to increase readability. So let’s show the month number only once
@@ -188,7 +227,8 @@ test_36[11,4] <- 36
 ganttrify(project = test_36,
           project_start_date = "2021-04", 
           month_breaks = 3,
-          show_vertical_lines = FALSE)
+          show_vertical_lines = FALSE,
+          font_family = "Roboto Condensed")
 ```
 
 <img src="man/figures/README-gantt_36_months-1.png" width="100%" />
@@ -200,7 +240,8 @@ Does right-aligned text bother you?
 ganttrify(project = ganttrify::test_project,
           spots = ganttrify::test_spots,
           project_start_date = "2021-04",
-          axis_text_align = "left") 
+          axis_text_align = "left",
+          font_family = "Roboto Condensed") 
 ```
 
 <img src="man/figures/README-gantt_left_aligned-1.png" width="100%" />
@@ -210,7 +251,8 @@ ganttrify(project = ganttrify::test_project,
 ganttrify(project = ganttrify::test_project,
           spots = ganttrify::test_spots,
           project_start_date = "2021-04",
-          axis_text_align = "centre") 
+          axis_text_align = "centre",
+          font_family = "Roboto Condensed") 
 ```
 
 <img src="man/figures/README-gantt_centre_aligned-1.png" width="100%" />
@@ -234,7 +276,7 @@ tibble::tribble(~wp, ~activity, ~start_date, ~end_date,
 Finally, keep in mind that ganttrify outputs `ggplot` objects. Some
 theming options may not behave exactly as you expect, but for example
 adding title, subtitle, and captions can be done as you would normally
-do with any `ggplot` graphs.
+do with any `ggplot2` graph.
 
 ``` r
 ganttrify(project = ganttrify::test_project,
@@ -358,11 +400,11 @@ At this stage, the package has strong expectations about the input
 format, and does not provide meaningful error messages. If you see
 unexpected results, please consider that:
 
--   no cell in the activity column must be empty
--   an activity cannot be called the same as a wp
--   activities in different wp should have different names (or at least
-    add a space at the end or something so that they look different to
-    the computer).
+- no cell in the activity column must be empty
+- an activity cannot be called the same as a wp
+- activities in different wp should have different names (or at least
+  add a space at the end or something so that they look different to the
+  computer).
 
 Some of this limitations should be dealt with in a future update.