From 789d1fd327b9e6162cc31f3b2b80a53ef767fe6d Mon Sep 17 00:00:00 2001 From: John Wiggins Date: Fri, 5 Mar 2021 17:29:58 +0100 Subject: [PATCH] Document how colors work in Kiva --- docs/source/kiva/state.rst | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/docs/source/kiva/state.rst b/docs/source/kiva/state.rst index 96f3898d6..c4044577e 100644 --- a/docs/source/kiva/state.rst +++ b/docs/source/kiva/state.rst @@ -29,6 +29,26 @@ along with the methods which operate on them: * Miter limit (:py:meth:`set_miter_limit`) * Flatness (:py:meth:`set_flatness`) * Image interpolation (:py:meth:`set_image_interpolation`, :py:meth:`get_image_interpolation`) +* Text drawing mode (:py:meth:`set_text_drawing_mode`) + +Color +----- +Kiva has two colors in its graphics state: stroke color and fill color. Stroke +color is used for the lines in paths when the drawing mode is ``STROKE``, +``FILL_STROKE`` or ``EOF_FILL_STROKE``. Fill color is used for text and for +the enclosed sections of paths when the drawing mode is ``FILL``, ``EOF_FILL``, +``FILL_STROKE``, or ``EOF_FILL_STROKE``. Additionally, the fill color can be +set by the :py:meth:`linear_gradient` and :py:meth:`radial_gradient` methods. + +.. note:: + Even though text uses the fill color, text will not be filled with a + gradient *unless* the text drawing mode is ``TEXT_FILL_STROKE`` and even that + will only work if the backend supports it. + +Color values should always be passed in as 3- or 4- tuples. The order of the +color components is ``(R, G, B[, A])`` and values must be floating point numbers +in the range [0, 1]. Even if a graphics context is not able to draw with alpha +blending, it's still OK to pass a 4 component color value when setting state. State Stack Management ----------------------