Specifying Colors & Gradients
=============================

Colors
------

by hex-string
^^^^^^^^^^^^^

You can specify a color via the standard hexadecimal string for RGB (as in HTML and CSS).  You also have a few other options as well. You can use:

  * 12-bit (3 hex numbers), RGB. e.g. ``'#f08'``
  * 24-bit (6 hex numbers), RRGGBB. e.g. ``'#ff0088'``
  * 48-bit (9 hex numbers), RRRGGGBBB. e.g. ``'#fff000888'``


Additionally, you can specify the alpha (i.e. transparency) of the color as RGBA. An alpha of ``0`` is full transparent, and ``f`` is fully opaque. Thus, you can also use:

  * 12-bit (4 hex numbers), RGBA. e.g. ``'#f085'``
  * 24-bit (8 hex numbers), RRGGBBAA. e.g. ``'#ff008855'``
  * 48-bit (12 hex numbers), RRRGGGBBBAAA. e.g. ``'#fff000888555'``

The ``#`` at the beginning is optional, but encouraged for readability. In layout files (described in :doc:`/layouts`), the ``#`` character will initiate a comment in Yaml. So to specify a color in a layout file, just quote it::

  # this is a comment in yaml
  attack:
    fill_color: '#fff'


by name
^^^^^^^

Under the hood, Squib uses the rcairo `color parser <https://github.com/rcairo/rcairo/blob/master/lib/cairo/color.rb>`_ to accept around 300 named colors. The full list can be found `here <https://github.com/rcairo/rcairo/blob/master/lib/cairo/colors.rb>`_.

Names of colors can be either strings or symbols, and case does not matter. Multiple words are separated by underscores. For example, ``'white'``, ``:burnt_orange``, or ``'ALIZARIN_CRIMSON'`` are all acceptable names.

by custom name
^^^^^^^^^^^^^^

In your ``config.yml``, as described in :doc:`/config`, you can specify custom names of colors. For example, ``'foreground'``.

Gradients
---------

In most places where colors are allowed, you may also supply a string that defines a gradient. Squib supports two flavors of gradients: linear and radial. Gradients are specified by supplying some xy coordinates, which are relative to the card (not the command). Each stop must be between ``0.0`` and ``1.0``, and you can supply as many as you like. Colors can be specified as above (in any of the hex notations or built-in constant). If you add two or more colors at the same stop, then the gradient keeps the colors in the in order specified and treats it like sharp transition.

The format for linear gradient strings look like this::

  '(x1,y1)(x2,y2) color1@stop1 color2@stop2'

The xy coordinates define the angle of the gradient.

The format for radial gradients look like this::

  '(x1,y1,radius1)(x2,y2,radius2) color1@stop1 color2@stop2'

The coordinates specify an inner circle first, then an outer circle.

In both of these formats, whitespace is ignored between tokens so as to make complex gradients more readable.

If you need something more powerful than these two types of gradients (e.g. mesh gradients), then we suggest encapsulating your logic within an SVG and using the :doc:`/dsl/svg` method to render it.

Samples
-------

Code is maintained in the `repository here <https://github.com/andymeneely/squib/tree/master/samples>`_ in case you need some of the assets referenced.

Sample: colors and color constants
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

.. literalinclude:: ../samples/colors/_colors.rb
  :language: ruby
  :linenos:

.. raw:: html

  <img src="colors/colors_00_expected.png" width=600 class="figure">

  <img src="colors/color_constants_00_expected.png" width=600 class="figure">

Sample: gradients
^^^^^^^^^^^^^^^^^

.. literalinclude:: ../samples/colors/_gradients.rb
  :language: ruby
  :linenos:

.. raw:: html

  <img src="colors/gradient_00_expected.png" width=600 class="figure">

Sample: Switch color based on variable
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Say you have different card types with different colors or themes but you would like to change the theme quickly without changing all parameters for each method inside ``Squib::Deck.new()``.

You could use something like the following snippet to have one place to define the color/theme and use that in all map functions. The example inverts the color from white to black for one card type. Use a switch-statement inside the map function to differentiate multiple types.

It's possible to use that for e.g. background color, text color or to choose the correct SVG for that color scheme (e.g. use the white or the black version of an image). The sample shows how to define the color at one place, e.g. choose between white and black, to quickly change the color scheme for the cards:

Here's the data or see the tab-separated file in the sample directory:

=====  ======================
Type   Text
=====  ======================
Snake  This is a snake.
Lion   This is a lion.
=====  ======================

.. literalinclude:: ../samples/colors/_switch_color.rb
  :language: ruby
  :linenos:
