From c7653d87347f59d171ac08255959e7df4dc84afb Mon Sep 17 00:00:00 2001 From: Dean Attali Date: Tue, 26 Sep 2017 22:16:48 -0400 Subject: [PATCH] update vignette and readme --- R/colourInput.R | 4 +- README.md | 138 ++++++++++++++++++++----------------- man/colourInput.Rd | 4 +- man/colourWidget.Rd | 2 +- man/updateColourInput.Rd | 2 +- vignettes/colourpicker.Rmd | 55 +++++++-------- 6 files changed, 110 insertions(+), 95 deletions(-) diff --git a/R/colourInput.R b/R/colourInput.R index e57d145..c76a1df 100644 --- a/R/colourInput.R +++ b/R/colourInput.R @@ -12,7 +12,7 @@ #' (only when an R colour exists for the selected colour). #' #' When \code{allowTransparent = TRUE}, the user can type into the input field -#' any RGBA value, HSLA value, or 8-digit HEX with alpha code. You can also use +#' any RGBA value, HSLA value, or 8-digit HEX with alpha channel You can also use #' any of these values as the \code{value} argument as the initial value of the #' input. #' @@ -29,7 +29,7 @@ #' applicable when \code{palette == "limited"}. The \code{limited} palette #' uses a default list of 40 colours if \code{allowedCols} is not defined. #' @param allowTransparent If \code{TRUE}, enables a slider to choose an alpha -#' pacity (transparency) value for the colour. When a colour with an opacity is +#' (transparency) value for the colour. When a colour with opacity is #' chosen, the return value is an 8-digit HEX code. #' @param returnName If \code{TRUE}, then return the name of an R colour instead #' of a HEX value when possible. diff --git a/README.md b/README.md index ae82c60..dbfe8f2 100644 --- a/README.md +++ b/README.md @@ -13,9 +13,13 @@ version](http://www.r-pkg.org/badges/version/colourpicker)](https://cran.r-proje `colourpicker` gives you a colour picker widget that can be used in different contexts in R. +![colour input image](inst/img/colourinputnew.PNG) + The most common uses of `colourpicker` are to use the `colourInput()` -function to create a colour input, or to use the `plotHelper()` -function/RStudio Addin to easily select colours to use in a plot. +function to create a [colour input in +Shiny](http://daattali.com/shiny/colourInput/), or to use the +`plotHelper()` function/RStudio Addin to easily [select colours for a +plot](inst/img/plothelper-demo.gif). Table of contents ================= @@ -33,18 +37,22 @@ Table of contents

Demos

+ As mentioned above, the most useful functions are `colourInput()` and `plotHelper()`. - [Click here](http://daattali.com/shiny/colourInput/) to view a live interactive demo the colour input. -- The GIF below shows what the Plot Colour Helper looks like. +- The GIF below shows what the Plot Colour Helper looks like (the GIF + is from an old version that did not support opacity/transparency for + colours, which is now supported). ![Plot Colour Helper demo](inst/img/plothelper-demo.gif)

Installation

+ `colourpicker` is available through both CRAN and GitHub: To install the stable CRAN version: @@ -59,6 +67,7 @@ To install the latest development version from GitHub:

Colour input for Shiny apps (or R markdown): `colourInput()`

+ You can use `colourInput()` to include a colour picker input in Shiny apps (or in R markdown documents). It works just like any other native Shiny input, here is an example: @@ -82,10 +91,11 @@ Shiny input, here is an example:

Select colours to use in your plot: `plotHelper()`

+ If you've ever had to spend a long time perfecting the colour scheme of a plot, you'd find the Plot Colour Helper handy. It's an RStudio addin that lets you interactively choose colours for your plot while updating -your plot in real-time so you can see the colour changes immediately. +your plot in real-time, so you can see the colour changes immediately. To use this tool, either highlight code for a plot and select the addin through the RStudio *Addins* menu, or call the `plotHelper()` function. @@ -96,6 +106,7 @@ The colours selected will be available as a variable named `CPCOLS`.

Select colours to use in your R code: `colourPicker()`

+ `colourpicker` also provides a more generic RStudio addin that can be used to select colours and save them as a variable in R. You can either access this tool using the *Addins* menu or with `colourPicker()`. You @@ -129,31 +140,71 @@ example the value of `input$col` would be `#FF0000` (\#FF0000 is the HEX value of the colour red). The default value at initialization is white (\#FFFFFF). -### Allowing "transparent" +### Retrieving the colour names + +If you use the `returnName = TRUE` parameter, then the return value will +be a colour name instead of a HEX value, when possible. For example, if +the chosen colour is red, the return value will be `red` instead of +`#FF0000`. For any colour that does not have a standard name, its HEX +value will be returned. -Since most functions in R that accept colours can also accept the value -"transparent", `colourInput` has an option to allow selecting the -"transparent" colour. By default, only real colours can be selected, so -you need to use the `allowTransparent = TRUE` parameter. When this -feature is turned on, a checkbox appears inside the input box. +### Allowing transparent colours -If the user checks the checkbox for "transparent", then the colour input -is grayed out and the returned value of the input is `transparent`. This -is the only case when the value returned from a `colourInput` is not a -HEX value. When the checkbox is unchecked, the value of the input will -be the last selected colour prior to selecting "transparent". +A simple colour input allow you to choose any opaque colour. If you use +the `allowTransparent = TRUE` parameter, the input will display an +additional slider that lets you choose a transparency (alpha) value. +Using this slider allows you to select semi-transparent colours, of even +the fully transparent colour, which is sometimes useful. -By default, the text of the checkbox reads "Transparent", but you can -change that with the `transparentText` parameter. For example, it might -be more clear to a user to use the word "None" instead of "Transparent". -Note that even if you change the checkbox text, the return value will -still be `transparent` since that's the actual colour name in R. +When using transparent colours, the return value will be an 8-digit HEX +code instead of 6 digits (the last 2 digits are the transparency value). +For example, if you select a 50% transparent red, the return value would +be `#FF000080`. Most R plotting functions can accept colours in this +format. -This is what a colour input with transparency enabled looks like +### Limited colour selection -![allowTransparent demo](inst/img/allowTransparent.png) +If you want to only allow the user to select a colour from a specific +list of colours, rather than any possible colour, you can use the +`palette = "limited"` parameter. By default, the limited palette will +contain 40 common colours, but you can supply your own list of colours +using the `allowedCols` parameter. Here is an image of the default +`limited` colour palette. + +![colourInput demo](inst/img/limited-palette.png) -### How the chosen colour is shown inside the input +### Flexible colour specification + +Specifying a colour to the colour input is very flexible to allow for +easier use. When providing a colour as the `value` parameter of the +input, there are a few ways to specify a colour: + +- Using a name of an R colour, such as `red`, `gold`, `blue3`, or any + other name that R supports (for a full list of R colours, type + `colours()`) +- Using a 6-character HEX value, either with or without the leading + `#`. For example, initializing a `colourInput` with any of the + following values will all result in the colour red: `ff0000`, + `FF0000`, `#ff0000`. If transparency is allowed, you can use an + 8-character HEX value. +- Using a 3-character HEX value, either with or without the leading + `#`. These values will be converted to full HEX values by + automatically doubling every character. For example, all the + following values would result in the same colour: `1ac`, `#1Ac`, + `11aacc`. If transparency is allowed, you can use a 4-character HEX + value. +- Using RGB specification, such as `rgb(0, 0, 255)`. If transparency + is allowed, you can use an `rgba()` specification. +- Using HSL specification, such as `hsl(240, 100, 50)`. If + transparency is allowed, you can use an `hsla()` specification. + +**Protip:** You can also type in any of these values directly into the +input box to select that colour, instead of selecting it from the colour +palette with your mouse. For example, you can click on the colour input +and literally type the word "blue", and the colour blue will get +selected. + +### How the chosen colour is shown inside the input box By default, the colour input's background will match the selected colour and the text inside the input field will be the colour's HEX value. If @@ -177,43 +228,6 @@ can start with a basic colour input such as updateColourInput(session, "col", label = "COLOUR:", value = "orange", showColour = "background", allowTransparent = TRUE, transparentText = "None") -### Limited colour selection - -This feature is available in `shinyjs` v0.0.8.0, which is currently only -on GitHub and not on CRAN. - -If you want to only allow the user to select a colour from a specific -list of colours, rather than any possible HEX colour, you can use the -`palette = "limited"` parameter. By default, the limited palette will -contain 40 common colours, but you can supply your own list of colours -using the `allowedCols` parameter. Here is an image of the default -limited colour palette. - -![colourInput demo](inst/img/limited-palette.png) - -### Flexible colour specification - -Specifying a colour to the colour input is made very flexible to allow -for easier use. When giving a colour as the `value` parameter of either -`colourInput` or `updateColourInput`, there are a few ways to specify a -colour: - -- Using a name of an R colour, such as `red`, `gold`, `blue3`, or any - other name that R supports (for a full list of R colours, type - `colours()`) -- If transparency is allowed in the `colourInput`, the value - `transparent` (lowercase) can be used. This will update the UI to - check the checkbox. -- Using a 6-character HEX value, either with or without the leading - `#`. For example, initializing a `colourInput` with any of the - following values will all result in the colour red: `ff0000`, - `FF0000`, `#ff0000`. -- Using a 3-character HEX value, either with or without the leading - `#`. These values will be converted to full HEX values by - automatically doubling every character. For example, all the - following values would result in the same colour: `1ac`, `#1Ac`, - `11aacc`. - ### Works on any device If you're worried that maybe someone viewing your Shiny app on a phone @@ -235,8 +249,8 @@ addin. This means that it can be invoked in one of two ways: - Highlight code for a plot and select the addin through the *Addins* menu, or -- Call the `plotHelper(code)` function with plot code as the - first parameter. +- Call the `plotHelper(code)` function with plot code as the first + parameter. There is a small difference between the two: invoking the addin via `plotHelper()` will merely return the final colour list as a vector, diff --git a/man/colourInput.Rd b/man/colourInput.Rd index e9e550c..551741e 100644 --- a/man/colourInput.Rd +++ b/man/colourInput.Rd @@ -28,7 +28,7 @@ applicable when \code{palette == "limited"}. The \code{limited} palette uses a default list of 40 colours if \code{allowedCols} is not defined.} \item{allowTransparent}{If \code{TRUE}, enables a slider to choose an alpha -pacity (transparency) value for the colour. When a colour with an opacity is +(transparency) value for the colour. When a colour with opacity is chosen, the return value is an 8-digit HEX code.} \item{returnName}{If \code{TRUE}, then return the name of an R colour instead @@ -48,7 +48,7 @@ The return value is a HEX value by default, but you can use the (only when an R colour exists for the selected colour). When \code{allowTransparent = TRUE}, the user can type into the input field -any RGBA value, HSLA value, or 8-digit HEX with alpha code. You can also use +any RGBA value, HSLA value, or 8-digit HEX with alpha channel You can also use any of these values as the \code{value} argument as the initial value of the input. } diff --git a/man/colourWidget.Rd b/man/colourWidget.Rd index 5aa7726..dc43995 100644 --- a/man/colourWidget.Rd +++ b/man/colourWidget.Rd @@ -25,7 +25,7 @@ applicable when \code{palette == "limited"}. The \code{limited} palette uses a default list of 40 colours if \code{allowedCols} is not defined.} \item{allowTransparent}{If \code{TRUE}, enables a slider to choose an alpha -pacity (transparency) value for the colour. When a colour with an opacity is +(transparency) value for the colour. When a colour with opacity is chosen, the return value is an 8-digit HEX code.} \item{returnName}{If \code{TRUE}, then return the name of an R colour instead diff --git a/man/updateColourInput.Rd b/man/updateColourInput.Rd index 64ced8d..6d1979e 100644 --- a/man/updateColourInput.Rd +++ b/man/updateColourInput.Rd @@ -30,7 +30,7 @@ applicable when \code{palette == "limited"}. The \code{limited} palette uses a default list of 40 colours if \code{allowedCols} is not defined.} \item{allowTransparent}{If \code{TRUE}, enables a slider to choose an alpha -pacity (transparency) value for the colour. When a colour with an opacity is +(transparency) value for the colour. When a colour with opacity is chosen, the return value is an 8-digit HEX code.} \item{returnName}{If \code{TRUE}, then return the name of an R colour instead diff --git a/vignettes/colourpicker.Rmd b/vignettes/colourpicker.Rmd index d36dc99..dd36b79 100644 --- a/vignettes/colourpicker.Rmd +++ b/vignettes/colourpicker.Rmd @@ -22,7 +22,9 @@ knitr::opts_chunk$set(tidy = FALSE, comment = "#>") `colourpicker` gives you a colour picker widget that can be used in different contexts in R. -The most common uses of `colourpicker` are to use the `colourInput()` function to create a colour input, or to use the `plotHelper()` function/RStudio Addin to easily select colours to use in a plot. +![colour input image](../inst/img/colourinputnew.PNG) + +The most common uses of `colourpicker` are to use the `colourInput()` function to create a [colour input in Shiny](http://daattali.com/shiny/colourInput/), or to use the `plotHelper()` function/RStudio Addin to easily [select colours for a plot](../inst/img/plothelper-demo.gif). # Table of contents @@ -40,7 +42,7 @@ As mentioned above, the most useful functions are `colourInput()` and `plotHelpe - [Click here](http://daattali.com/shiny/colourInput/) to view a live interactive demo the colour input. - - The GIF below shows what the Plot Colour Helper looks like. + - The GIF below shows what the Plot Colour Helper looks like (the GIF is from an old version that did not support opacity/transparency for colours, which is now supported). ![Plot Colour Helper demo](../inst/img/plothelper-demo.gif) @@ -85,7 +87,7 @@ shinyApp(

Select colours to use in your plot: `plotHelper()`

-If you've ever had to spend a long time perfecting the colour scheme of a plot, you'd find the Plot Colour Helper handy. It's an RStudio addin that lets you interactively choose colours for your plot while updating your plot in real-time so you can see the colour changes immediately. +If you've ever had to spend a long time perfecting the colour scheme of a plot, you'd find the Plot Colour Helper handy. It's an RStudio addin that lets you interactively choose colours for your plot while updating your plot in real-time, so you can see the colour changes immediately. To use this tool, either highlight code for a plot and select the addin through the RStudio *Addins* menu, or call the `plotHelper()` function. The colours selected will be available as a variable named `CPCOLS`. @@ -108,19 +110,35 @@ The colour picker input is also available as an 'htmlwidgets' widget using the ` Using `colourInput` is extremely trivial if you've used Shiny, and it's as easy to use as any other input control. It was implemented to very closely mimic all other Shiny inputs so that using it will feel very familiar. You can add a simple colour input to your Shiny app with `colourInput("col", "Select colour", value = "red")`. The return value from a `colourInput` is an uppercase HEX colour, so in the previous example the value of `input$col` would be `#FF0000` (#FF0000 is the HEX value of the colour red). The default value at initialization is white (#FFFFFF). -### Allowing "transparent" +### Retrieving the colour names + +If you use the `returnName = TRUE` parameter, then the return value will be a colour name instead of a HEX value, when possible. For example, if the chosen colour is red, the return value will be `red` instead of `#FF0000`. For any colour that does not have a standard name, its HEX value will be returned. + +### Allowing transparent colours -Since most functions in R that accept colours can also accept the value "transparent", `colourInput` has an option to allow selecting the "transparent" colour. By default, only real colours can be selected, so you need to use the `allowTransparent = TRUE` parameter. When this feature is turned on, a checkbox appears inside the input box. +A simple colour input allow you to choose any opaque colour. If you use the `allowTransparent = TRUE` parameter, the input will display an additional slider that lets you choose a transparency (alpha) value. Using this slider allows you to select semi-transparent colours, of even the fully transparent colour, which is sometimes useful. -If the user checks the checkbox for "transparent", then the colour input is grayed out and the returned value of the input is `transparent`. This is the only case when the value returned from a `colourInput` is not a HEX value. When the checkbox is unchecked, the value of the input will be the last selected colour prior to selecting "transparent". +When using transparent colours, the return value will be an 8-digit HEX code instead of 6 digits (the last 2 digits are the transparency value). For example, if you select a 50% transparent red, the return value would be `#FF000080`. Most R plotting functions can accept colours in this format. -By default, the text of the checkbox reads "Transparent", but you can change that with the `transparentText` parameter. For example, it might be more clear to a user to use the word "None" instead of "Transparent". Note that even if you change the checkbox text, the return value will still be `transparent` since that's the actual colour name in R. +### Limited colour selection + +If you want to only allow the user to select a colour from a specific list of colours, rather than any possible colour, you can use the `palette = "limited"` parameter. By default, the limited palette will contain 40 common colours, but you can supply your own list of colours using the `allowedCols` parameter. Here is an image of the default `limited` colour palette. -This is what a colour input with transparency enabled looks like +![colourInput demo](../inst/img/limited-palette.png) + +### Flexible colour specification + +Specifying a colour to the colour input is very flexible to allow for easier use. When providing a colour as the `value` parameter of the input, there are a few ways to specify a colour: + +- Using a name of an R colour, such as `red`, `gold`, `blue3`, or any other name that R supports (for a full list of R colours, type `colours()`) +- Using a 6-character HEX value, either with or without the leading `#`. For example, initializing a `colourInput` with any of the following values will all result in the colour red: `ff0000`, `FF0000`, `#ff0000`. If transparency is allowed, you can use an 8-character HEX value. +- Using a 3-character HEX value, either with or without the leading `#`. These values will be converted to full HEX values by automatically doubling every character. For example, all the following values would result in the same colour: `1ac`, `#1Ac`, `11aacc`. If transparency is allowed, you can use a 4-character HEX value. +- Using RGB specification, such as `rgb(0, 0, 255)`. If transparency is allowed, you can use an `rgba()` specification. +- Using HSL specification, such as `hsl(240, 100, 50)`. If transparency is allowed, you can use an `hsla()` specification. -![allowTransparent demo](../inst/img/allowTransparent.png) +**Protip:** You can also type in any of these values directly into the input box to select that colour, instead of selecting it from the colour palette with your mouse. For example, you can click on the colour input and literally type the word "blue", and the colour blue will get selected. -### How the chosen colour is shown inside the input +### How the chosen colour is shown inside the input box By default, the colour input's background will match the selected colour and the text inside the input field will be the colour's HEX value. If that's too much for you, you can customize the input with the `showColour` parameter to either only show the text or only show the background colour. @@ -137,23 +155,6 @@ updateColourInput(session, "col", label = "COLOUR:", value = "orange", showColour = "background", allowTransparent = TRUE, transparentText = "None") ``` -### Limited colour selection - -This feature is available in `shinyjs` v0.0.8.0, which is currently only on GitHub and not on CRAN. - -If you want to only allow the user to select a colour from a specific list of colours, rather than any possible HEX colour, you can use the `palette = "limited"` parameter. By default, the limited palette will contain 40 common colours, but you can supply your own list of colours using the `allowedCols` parameter. Here is an image of the default limited colour palette. - -![colourInput demo](../inst/img/limited-palette.png) - -### Flexible colour specification - -Specifying a colour to the colour input is made very flexible to allow for easier use. When giving a colour as the `value` parameter of either `colourInput` or `updateColourInput`, there are a few ways to specify a colour: - -- Using a name of an R colour, such as `red`, `gold`, `blue3`, or any other name that R supports (for a full list of R colours, type `colours()`) -- If transparency is allowed in the `colourInput`, the value `transparent` (lowercase) can be used. This will update the UI to check the checkbox. -- Using a 6-character HEX value, either with or without the leading `#`. For example, initializing a `colourInput` with any of the following values will all result in the colour red: `ff0000`, `FF0000`, `#ff0000`. -- Using a 3-character HEX value, either with or without the leading `#`. These values will be converted to full HEX values by automatically doubling every character. For example, all the following values would result in the same colour: `1ac`, `#1Ac`, `11aacc`. - ### Works on any device If you're worried that maybe someone viewing your Shiny app on a phone won't be able to use this input properly - don't you worry. I haven't quite checked every single device out there, but I did spend extra time making sure the colour selection JavaScript works in most devices I could think of. `colourInput` will work fine in Shiny apps that are viewed on Android cell phones, iPhones, iPads, and even Internet Explorer 8+.