Skip to content

Latest commit

 

History

History
128 lines (104 loc) · 13.6 KB

hs.drawing.color.md

File metadata and controls

128 lines (104 loc) · 13.6 KB
Raw

docs » hs.drawing.color

Additions to hs.drawing which provide access to the system color lists and a wider variety of ways to represent color within Hammerspoon.

Color is represented within Hammerspoon as a table containing keys which tell Hammerspoon how the color is specified. You can specify a color in one of the following ways, depending upon the keys you supply within the table:

  • As a combination of Red, Green, and Blue elements (RGB Color):

    • red - the red component of the color specified as a number from 0.0 to 1.0.
    • green - the green component of the color specified as a number from 0.0 to 1.0.
    • blue - the blue component of the color specified as a number from 0.0 to 1.0.
    • alpha - the color transparency from 0.0 (completely transparent) to 1.0 (completely opaque)

  • As a combination of Hue, Saturation, and Brightness (HSB or HSV Color):

    • hue - the hue component of the color specified as a number from 0.0 to 1.0.
    • saturation - the saturation component of the color specified as a number from 0.0 to 1.0.
    • brightness - the brightness component of the color specified as a number from 0.0 to 1.0.
    • alpha - the color transparency from 0.0 (completely transparent) to 1.0 (completely opaque)

  • As grayscale (Grayscale Color):

    • white - the ratio of white to black from 0.0 (completely black) to 1.0 (completely white)
    • alpha - the color transparency from 0.0 (completely transparent) to 1.0 (completely opaque)

  • From the system or Hammerspoon color lists:

    • list - the name of a system color list or a collection list defined in hs.drawing.color
    • name - the color name within the specified color list

  • As an HTML style hex color specification:

    • hex - a string of the format "#rrggbb" or "#rgb" where r, g, and b are hexadecimal digits (i.e. 0-9, A-F)
    • alpha - the color transparency from 0.0 (completely transparent) to 1.0 (completely opaque)

  • From an image to be used as a tiled pattern:

    • image - an hs.image object representing the image to be used as a tiled pattern

Any combination of the above keys may be specified within the color table and they will be evaluated in the following order:

  1. if the image key is specified, it will be used to create a tiling pattern.
  2. If the list and name keys are specified, and if they can be matched to an existing color within the system color lists, that color is used.
  3. If the hue key is provided, then the color is generated as an HSB color
  4. If the white key is provided, then the color is generated as a Grayscale color
  5. Otherwise, an RGB color is generated.

Except where specified above to indicate the color model being used, any key which is not provided defaults to a value of 0.0, except for alpha, which defaults to 1.0. This means that specifying an empty table as the color will result in an opaque black color.

API Overview

API Documentation

Constants

definedCollections

Signature hs.drawing.color.definedCollections
Type Constant
Description This table contains this list of defined color collections provided by the hs.drawing.color module. Collections differ from the system color lists in that you can modify the color values their members contain by modifying the table at hs.drawing.color.<collection>.<color> and future references to that color will reflect the new changes, thus allowing you to customize the palettes for your installation.
Notes
  • This list is a constant, but the members it refers to are not.

Variables

ansiTerminalColors

Signature hs.drawing.color.ansiTerminalColors
Type Variable
Description A collection of colors representing the ANSI Terminal color sequences. The color definitions are based upon code found at https://github.com/balthamos/geektool-3 in the /NerdTool/classes/ANSIEscapeHelper.m file.
Notes
  • This is not a constant, so you can adjust the colors at run time for your installation if desired.

hammerspoon

Signature hs.drawing.color.hammerspoon
Type Variable
Description This table contains a collection of various useful pre-defined colors:
Notes
  • This is not a constant, so you can adjust the colors at run time for your installation if desired.

x11

Signature hs.drawing.color.x11
Type Variable
Description A collection of colors representing the X11 color names as defined at https://en.wikipedia.org/wiki/Web_colors#X11_color_names (names in lowercase)
Notes
  • This is not a constant, so you can adjust the colors at run time for your installation if desired.

Functions

asHSB

| Signature | hs.drawing.color.asHSB(color) -> table | string | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Returns a table containing the HSB representation of the specified color. | | Parameters |

  • color - a table specifying a color as described in the module definition (see hs.drawing.color in the online help or Dash documentation)
| | Returns |
  • a table containing the hue, saturation, brightness, and alpha keys representing the specified color as HSB or a string describing the color's colorspace if conversion is not possible.
| | Notes |
  • See also hs.drawing.color.asRGB
|

asRGB

| Signature | hs.drawing.color.asRGB(color) -> table | string | | -----------------------------------------------------|---------------------------------------------------------------------------------------------------------| | Type | Function | | Description | Returns a table containing the RGB representation of the specified color. | | Parameters |

  • color - a table specifying a color as described in the module definition (see hs.drawing.color in the online help or Dash documentation)
| | Returns |
  • a table containing the red, blue, green, and alpha keys representing the specified color as RGB or a string describing the color's colorspace if conversion is not possible.
| | Notes |
  • See also hs.drawing.color.asHSB
|

colorsFor

Signature hs.drawing.color.colorsFor(list) -> table
Type Function
Description Returns a table containing the colors for the specified system color list or hs.drawing.color collection.
Parameters
  • list - the name of the list to provide colors for
Returns
  • a table whose keys are made from the colors provided by the color list or nil if the list does not exist.
Notes
  • Where possible, each color node is provided as its RGB color representation. Where this is not possible, the color node contains the keys list and name which identify the indicated color. This means that you can use the following wherever a color parameter is expected: hs.drawing.color.colorsFor(list)["color-name"]
  • This function provides a tostring metatable method which allows listing the defined colors in the list in the Hammerspoon console with: hs.drawing.colorsFor(list)
  • See also hs.drawing.color.lists

lists

Signature hs.drawing.color.lists() -> table
Type Function
Description Returns a table containing the system color lists and hs.drawing.color collections with their defined colors.
Parameters
  • None
Returns
  • a table whose keys are made from the currently defined system color lists and hs.drawing.color collections. Each color list key refers to a table whose keys make up the colors provided by the specific color list.
Notes
  • Where possible, each color node is provided as its RGB color representation. Where this is not possible, the color node contains the keys list and name which identify the indicated color. This means that you can use the following wherever a color parameter is expected: hs.drawing.color.lists()["list-name"]["color-name"]
  • This function provides a tostring metatable method which allows listing the defined color lists in the Hammerspoon console with: hs.drawing.color.lists()
  • See also hs.drawing.color.colorsFor