<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
 "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
  [
    <!ENTITY selfURL
        "http://www.nmt.edu/tcc/help/lang/python/examples/huey/">
    <!ENTITY huey     "<application>huey</application>">
    <!ENTITY rgb-txt  "<filename>rgb.txt</filename>">
  ]
>
<article>
  <articleinfo>
    <title>&huey;: A color and font selection tool</title>
    <authorgroup>
      <author>
        <firstname>John W.</firstname>
        <surname>Shipman</surname>
      </author>
    </authorgroup>
    <address><email>tcc-doc@nmt.edu</email>
    </address>
    <revhistory>
      <revision>
        <revnumber>$Revision: 1.39 $</revnumber>
        <date>$Date: 2008/01/09 04:45:39 $</date>
      </revision>
    </revhistory>
    <abstract>
      <para>
        Describes a program to display and modify colors and
        fonts, using the Python programming language and the
        Tkinter widget set.
      </para>
      <para>
        This publication is available in <ulink url="&selfURL;"
        >Web form</ulink > and also as a <ulink
        url="&selfURL;huey.pdf" >PDF document</ulink >.  Please
        forward any comments to <userinput
        >tcc-doc@nmt.edu</userinput >.
      </para>
    </abstract>
  </articleinfo>
  <section id='intro'>
    <title>Introduction</title>
    <para>
      The selection of colors and fonts of type is an important
      part of the design process for graphical user interfaces
      (GUIs).  &huey; is a program you can use to see how colors
      and fonts look on your screen.
    </para>
    <para>
      &huey; allows you to work with two colors at once:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Type is shown in the <firstterm >text color</firstterm >.  The
          initial text color is black.  You might also think of this as
          the <firstterm >foreground</firstterm > color.
        </para>
      </listitem>
      <listitem>
        <para>
          The area behind the type is the <firstterm >background
          color</firstterm >.  The initial background color is
          bright red.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      For those interested in the implementation of this program,
      see <ulink url='&selfURL;ims/' ><citetitle >&huey;: Internal
      maintenance specification</citetitle ></ulink >.  As an
      example of Python and Tkinter programming, the entire
      Python source for the program is presented there using a
      lightweight literate programming (LLP) style.
    </para>
    <section id='online-files'>
      <title>Files discussed in this publication</title>
      <para>
        Here are online links to all the files required by this
        program (other than Python and Tkinter installs).
      </para>
      <itemizedlist>
        <listitem>
          <para>
            <ulink url='&selfURL;huey' ><filename >huey</filename
            ></ulink >: The main script.
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url='&selfURL;scrolledlist.py' ><filename
            >scrolledlist.py</filename ></ulink >: Source for the
            <code >ScrolledList</code > compound widget.
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url='&selfURL;fontselect.py' ><filename
            >fontselect.py</filename ></ulink >: Source for the
            <code >FontSelect</code > compound widget.
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url='&selfURL;huey.xml' ><filename
            >huey.xml</filename ></ulink >: DocBook source for
            this document.
          </para>
        </listitem>
      </itemizedlist>
    </section> <!--online-files-->
  </section> <!--intro-->
  <section id='color-models'>
    <title>Color models</title>
    <para>
      Before we discuss the operation of &huey;, a brief review
      of color space theory is in order.
    </para>
    <para>
      The author has relied heavily on one book as a
      comprehensive reference on color theory as it relates to
      computer graphics.
    </para>
    <blockquote>
      <para>
        Foley, James D., Andries van Dam, Steven K. Feiner, and
        John F. Hughes.  Computer graphics: principles and
        practice.  Second edition.  Addison-Wesley, 1992. ISBN
        0-201-12110-7.
      </para>
    </blockquote>
    <para>
      There are several different ways to represent a color as a
      set of three numbers called <firstterm
      >parameters</firstterm >.  This program supports three of
      them.  In each model, each parameter varies from 0 to 255.
    </para>
    <section id='hsv-model'>
      <title>The HSV model: hue, saturation, and value</title>
      <para>
        In the HSV model, the three parameters used to describe a
        color are called <firstterm >hue</firstterm >, <firstterm
        >saturation</firstterm >, and <code >value</code >.
      </para>
      <itemizedlist>
        <listitem>
          <para>
            The <firstterm >hue</firstterm > parameter describes
            the general kind of color.  As the hue parameter
            ranges from 0 to 255, the color starts around the
            <firstterm >color wheel</firstterm >, displaying
            first red, then yellow, green, cyan, blue, magenta,
            and finally back to red.
          </para>
          <informalfigure>
            <!--xfig was used to prepare the original artwork in
             !  fig/wheel.fig.  This figure was exported as:
             !    - fig/wheel.png at 200%
             !    - fig/wheel.pdf at 100%
             !-->
            <mediaobject>
              <imageobject role="html">
                <imagedata fileref="fig/wheel.png"/>
              </imageobject>
              <imageobject role="fo">
                <imagedata fileref="fig/wheel.pdf" scale='60'/>
              </imageobject>
            </mediaobject>
          </informalfigure>
        </listitem>
        <listitem>
          <para>
            The <firstterm >saturation</firstterm > parameter
            describes how strong the color is.  A color with full
            saturation (a value of 255 in this program) has full
            color.  As the saturation decreases to zero, there is
            less and less color tint.
          </para>
        </listitem>
        <listitem>
          <para>
            The <firstterm >value</firstterm > parameter
            describes how light or dark the color is.
            A value parameter of zero will always be black,
            regardless of the other parameters.  Increasing
            the value to 255 lightens the shade.
          </para>
        </listitem>
      </itemizedlist>
      <para>
        A color with full saturation and value is called a
        <firstterm >primary</firstterm > color.  For example,
        if the hue is 0 and the saturation and value are
        at 255, the color is bright, primary red.
      </para>
    </section> <!--End hsv-model-->
    <section id='rgb-model'>
      <title>The RGB model: red, green, and blue</title>
      <para>
        The three parameters of a color in the RGB model
        describe the relative amounts of red, green and blue.
      </para>
      <para>
        The RGB model is sometimes called the <firstterm
        >additive color model</firstterm >.  If all three
        parameters are zero, the color is black.  Increasing a
        parameter adds more and more pure color.  For example,
        if the R and B parameters are zero, and the G parameter is
        255 (the maximum), you will see pure green.  White has
        all three parameters at 255.
      </para>
      <para>
        Computer display panels use the RGB model.  Additive
        color mixing is also used in stage lighting.  For
        example, to light a scene in yellow, mix red and green.
      </para>
    </section> <!--End rgb-model-->
    <section id='cmy-model'>
      <title>The CMY model: cyan, magenta, and yellow</title>
      <para>
        The CMY color model is also called the subtractive
        model.  In this model, white has all three parameters
        at zero.  Increasing the amount of cyan is the same as
        subtracting red; increasing magenta is the same as
        decreasing green; and increasing yellow is the same as
        decreasing blue.  Black has all three parameters at
        their maximum.
      </para>
      <para>
        Color darkroom work uses the CMY model. To correct the
        color of a film original, the enlarger's color head can
        produce light with a wide range of colors.  The color
        head starts with pure white light.  Knobs on the color
        head use cyan, magenta, and yellow filters to subtract
        red, green, and blue respectively.
      </para>
    </section> <!--End cmy-model-->
  </section> <!--color-models-->
  <section id='operation'>
    <title>Operation of &huey;</title>
    <para>
      This program is written in the Python programming language,
      and it uses the Tkinter widget set.  You will need both
      these packages installed on your local system.
    </para>
    <itemizedlist>
      <listitem>
        <para>
          For Python, see the <ulink url='http://www.python.org/'
          >Python web site</ulink >.
        </para>
      </listitem>
      <listitem>
        <para>
          For Tkinter, see <ulink
url='http://tkinter.unpythonic.net/wiki/How_20to_20install_20Tkinter'
          ><citetitle >How to install Tkinter</citetitle ></ulink
          >.
        </para>
      </listitem>
    </itemizedlist>
    <para>
      To run &huey;, copy the script to a convenient location and
      run it from there.  Get the <ulink
url='http://www.nmt.edu/tcc/help/lang/python/examples/huey/huey'
      >&huey; source file online</ulink >.
    </para>
    <para>
      Under a Unix-type system, you can run &huey; from the
      command line; there are no command line arguments.  On a
      Windows box, rename the script as <filename
      >huey.py</filename > and double-click on it.
    </para>
    <informalfigure>
      <!--Used Gimp to take a screen shot.  Changed the X and Y
       !  resolution to 200dpi in Image->Scale Image.  Cropped out
       !  the window decorations.  Then pasted the figure into
       !  xfig and added labels.  Exported at:
       !    - 100% to PDF
       !    - 100% to PNG
       !-->
      <mediaobject>
        <imageobject role="html">
          <imagedata fileref="fig/keyed-shot.png"/>
        </imageobject>
        <imageobject role="fo">
          <imagedata fileref="fig/keyed-shot.pdf" scale='50'/> 
        </imageobject>
      </mediaobject>
    </informalfigure>
    <itemizedlist>
      <listitem>
        <para>
          The <firstterm >Color swatch</firstterm > in the top
          right corner shows a sample of the current font, in the
          current text color, against the current background
          color.
        </para>
      </listitem>
      <listitem>
        <para>
          The names of the <firstterm >current background
          color</firstterm > and <firstterm >current text
          color</firstterm > are displayed in &#x201c;<code
          >#RRGGBB</code >&#x201d; form.  You can cut and paste
          these color names into any application anywhere.
        </para>
      </listitem>
      <listitem>
        <para>
          If you want to change either color, use the <firstterm
          >Background/text selector</firstterm > to select which
          color to change.
        </para>
      </listitem>
      <listitem>
        <para>
          To change the selected color using a color name, click
          on a name in the <firstterm >color name
          selector</firstterm >, or type the color name into the
          <firstterm >color name field</firstterm > and press
          <keysym >Enter</keysym >.
        </para>
      </listitem>
      <listitem>
        <para>
          You can make fine adjustments to the selected color by
          dragging the three <firstterm >color sliders</firstterm
          >.  Each slider controls one <firstterm
          >parameter</firstterm > of the color.  The meaning of
          each slider depends on the current color model; see
          <xref linkend='color-models' />.  Use the <firstterm
          >color model selector</firstterm > radiobuttons to
          select a color model.
        </para>
      </listitem>
      <listitem>
        <para>
          To change the general kind of text font displayed in
          the color swatch, click on a family name in the
          <firstterm >font family selector</firstterm >.
        </para>
        <para>
          To change the size of the text, type the font size in
          points (1/72") into the <firstterm >font size
          field</firstterm >, and either press <keysym
          >Enter</keysym > or click the <guibutton >Set
          size</guibutton > button.  You can also specify the font
          size in pixels by entering a negative number; for
          example, entering -15 in the font size field gives you
          a font 15 pixels high.
        </para>
        <para>
          To change the text from regular to boldface or back to
          regular, click the <firstterm >boldface
          button</firstterm >.  Click the <firstterm >italics
          button</firstterm > to change from regular to italic
          and back.
        </para>
        <para>
          Because not all fonts are available in all styles and
          sizes, the <firstterm >actual font name</firstterm >
          displayed may not be exactly what you requested.
        </para>
      </listitem>
    </itemizedlist>
  </section> <!--operation-->
</article>

