sec-gdkvisual.html

gtk 开发手册和参考文档。 包括gtk glib gdk等

          A <span class="STRUCTNAME">GdkColor</span> stores an RGB
          value and a pixel. Red, green, and blue are given as
          16-bit unsigned integers; so they are in the range [0,
          65535]. The contents of the pixel depend on the visual.
          Here is <span class="STRUCTNAME">GdkColor</span>:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;typedef struct _GdkColor GdkColor;

struct _GdkColor
{
  gulong  pixel;
  gushort red;
  gushort green;
  gushort blue;
};&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          Before you can use a color to draw, you must:
        </p>
        <ul>
          <li>
            <p>
              Ensure that the pixel value contains an appropriate
              value.&#13;
            </p>
          </li>
          <li>
            <p>
              Ensure that the color exists in the colormap of the
              drawable you intend to draw to. (A <i class=
              "FIRSTTERM">drawable</i> is a window or pixmap you
              can draw to; see <a href="sec-gdkdrawable.html">the
              section called <i>Drawables and
              Pixmaps</i></a>.)&#13;
            </p>
          </li>
        </ul>
        <p>
          In Xlib, this is an enormously complicated process,
          because it has to be done differently for every kind of
          visual. GDK conceals things fairly well. You simply call
          <tt class="FUNCTION">gdk_colormap_alloc_color()</tt> to
          fill in the pixel value and add the color to the colormap
          (<a href="sec-gdkvisual.html#FL-COLORALLOC">Figure
          3</a>). Here is an example; it assumes a preexisting
          <span class="STRUCTNAME">GdkColormap* colormap</span>,
          which should be the colormap of the drawable you are
          targetting:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  GdkColor color;
  
  /* Describe a pure red */
  color.red   = 65535;
  color.green = 0;
  color.blue  = 0;

  if (gdk_colormap_alloc_color(colormap, &amp;color, FALSE, TRUE))
    {
      /* Success! */
    }&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          If <tt class="FUNCTION">gdk_colormap_alloc_color()</tt>
          returns <span class="STRUCTNAME">TRUE</span>, then the
          color was allocated and <span class="STRUCTNAME">
          color.pixel</span> contains a valid value. The color can
          then be used to draw. The two boolean arguments to <tt
          class="FUNCTION">gdk_colormap_alloc_color()</tt> specify
          whether the color should be <i class="FIRSTTERM">
          writeable</i>, and whether to try to find a "best match"
          if the color can't be allocated. If a best match is used
          instead of allocating a new color, the color's RGB values
          will be changed to the best match. If you request a best
          match for a non-writeable entry, allocation really should
          not fail, since even on a black and white display either
          black or white will be the best match; only an empty
          colormap could cause failure. The only way to get an
          empty colormap is to create a custom colormap yourself.
          If you don't ask for the best match, failure is quite
          possible on displays with a limited number of colors.
          Failure is always possible with writeable colormap
          entries (where best match makes no sense, because the
          entry can be modified).
        </p>
        <p>
          A <i class="FIRSTTERM">writeable</i> colormap entry is
          one that you can change at any time; some visuals support
          this, and some don't. The purpose of a writeable colormap
          entry is to change an on-screen color without redrawing
          the graphics. Some hardware stores pixels as indices into
          a color lookup table, so changing the lookup table
          changes how the pixels are displayed. The disadvantages
          of writeable colormap entries are numerous. Most notably:
          not all visuals support them, and writeable colormap
          entries can't be used by other applications (read-only
          entries can be shared, since other applications know the
          color will remain constant). Thus, it is a good idea to
          avoid allocating writeable colors. On modern hardware,
          they are more trouble than they're worth; the speed gain
          compared to simply redrawing your graphics will not be
          noticeable.
        </p>
        <p>
          When you're finished with a color, you can remove it from
          the colormap with <tt class="FUNCTION">
          gdk_colormap_free_colors()</tt>. This is only really
          important for pseudo color and grayscale visuals, where
          colors are in short supply and the colormap can be
          modified by clients. GDK will automatically do the right
          thing for each visual type, so always call this function.
        </p>
        <p>
          A convenient way to obtain RGB values is the <tt class= 
          "FUNCTION">gdk_color_parse()</tt> function. This takes an
          X color specification, and fills in the <span class= 
          "STRUCTNAME">red</span>, <span class="STRUCTNAME">
          green</span>, and <span class="STRUCTNAME">blue</span>
          fields of a <span class="STRUCTNAME">GdkColor</span>. An
          X color specification can have many forms; one
          possibility is an RGB string:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13; RGB:FF/FF/FF&#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          This specifies white (red, green, and blue are all at
          full intensity). The <span class="STRUCTNAME">RGB:</span>
          specifies a "color space," and determines the meaning of
          the numbers after it. X also understands several more
          obscure color spaces. If the color specification string
          doesn't begin with a recognized color space, X assumes
          it's a color name and looks it up in a database of names.
          So you can write code like this:
        </p>
        <table border="0" bgcolor="#E0E0E0" width="100%">
          <tr>
            <td>
<pre class="PROGRAMLISTING">
&#13;  GdkColor color;

  if (gdk_color_parse("orange", &amp;color))
    {
      if (gdk_colormap_alloc_color(colormap, &amp;color, FALSE, TRUE))
        {
          /* We have orange! */
        }
    } &#13;
</pre>
            </td>
          </tr>
        </table>
        <p>
          As you can see, <tt class="FUNCTION">
          gdk_color_parse()</tt> returns <span class="STRUCTNAME">
          TRUE</span> if it figures out the string you pass it.
          There is no way to know exactly what will be in the color
          database, so always check this return value.
        </p>
        <div class="FIGURE">
          <a name="FL-COLORALLOC"></a>
          <div class="FUNCSYNOPSIS">
            <a name="FL-COLORALLOC.SYNOPSIS"></a>
            <table border="0" bgcolor="#E0E0E0" width="100%">
              <tr>
                <td>
<pre class="FUNCSYNOPSISINFO">
#include &lt;gdk/gdk.h&gt;
</pre>
                </td>
              </tr>
            </table>
            <p>
              <code><code class="FUNCDEF">gboolean <tt class= 
              "FUNCTION">
              gdk_colormap_alloc_color</tt></code>(GdkColormap* <tt
              class="PARAMETER"><i>colormap</i></tt>, GdkColor* <tt
              class="PARAMETER"><i>color</i></tt>, gboolean <tt
              class="PARAMETER"><i>writeable</i></tt>, gboolean <tt
              class="PARAMETER"><i>best_match</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">void <tt class=
              "FUNCTION">
              gdk_colormap_free_colors</tt></code>(GdkColormap* <tt
              class="PARAMETER"><i>colormap</i></tt>, GdkColor* <tt
              class="PARAMETER"><i>colors</i></tt>, gint <tt class= 
              "PARAMETER"><i>ncolors</i></tt>);</code>
            </p>
            <p>
              <code><code class="FUNCDEF">gint <tt class=
              "FUNCTION">gdk_color_parse</tt></code>(gchar* <tt
              class="PARAMETER"><i>spec</i></tt>, GdkColor* <tt
              class="PARAMETER"><i>color</i></tt>);</code>
            </p>
          </div>
          <p>
            <b>Figure 3. Color Allocation</b>
          </p>
        </div>
        <div class="SECT3">
          <h3 class="SECT3">
            <a name="Z116">Obtaining a Colormap</a>
          </h3>
          <p>
            If you're writing a <tt class="CLASSNAME">
            GtkWidget</tt> subclass, the correct way to obtain a
            colormap is with <tt class="FUNCTION">
            gtk_widget_get_colormap()</tt> (see <a href= 
            "cha-widget.html">the chapter called <i>Writing a <tt
            class="CLASSNAME">GtkWidget</tt></i></a>). Otherwise,
            the system (default) colormap is usually what you want;
            call <tt class="FUNCTION">
            gdk_colormap_get_system()</tt>, which takes no
            arguments and returns the default colormap.
          </p>
          <p>
            The GdkRGB module (see <a href="z132.html#SEC-GDKRGB">
            the section called <i>RGB Buffers</i></a>) is another
            way to deal with colors; among other capabilities, it
            can set the foreground and background colors of a
            graphics context from an RGB value. The relevant
            functions are <tt class="FUNCTION">
            gdk_rgb_gc_set_foreground()</tt> and <tt class=
            "FUNCTION">gdk_rgb_gc_set_background()</tt>. GdkRGB has
            a pre-allocated colormap that it uses to pick a
            best-match color; using it means that your application
            can share limited colormap resources with other
            applications using GdkRGB (such as the Gimp). You can
            also obtain GdkRGB's colormap and use it directly (see
            <a href="z132.html#SEC-GDKRGB">the section called <i>
            RGB Buffers</i></a>).
          </p>
        </div>
      </div>
    </div>
    <div class="NAVFOOTER">
      <br>
      <br>
      <table width="100%" border="0" bgcolor="#ffffff" cellpadding= 
      "1" cellspacing="0">
        <tr>
          <td width="25%" bgcolor="#ffffff" align="left">
            <a href="sec-gdkwindow.html"><font color="#0000ff"
            size="2"><b>&lt;&lt;&lt; Previous</b></font></a>
          </td>
          <td width="25%" colspan="2" bgcolor="#ffffff" align= 
          "center">
            <font color="#0000ff" size="2"><b><a href="ggad.html">
            <font color="#0000ff" size="2"><b>
            Home</b></font></a></b></font>
          </td>
          <td width="25%" bgcolor="#ffffff" align="right">
            <a href="sec-gdkdrawable.html"><font color="#0000ff"
            size="2"><b>Next &gt;&gt;&gt;</b></font></a>
          </td>
        </tr>
        <tr>
          <td colspan="2" align="left">
            <font color="#000000" size="2"><b><span class= 
            "STRUCTNAME">GdkWindow</span></b></font>
          </td>
          <td colspan="2" align="right">
            <font color="#000000" size="2"><b>Drawables and
            Pixmaps</b></font>
          </td>
        </tr>
      </table>
    </div>
  </body>
</html>