GetColor man page on BSDi

Man page or keyword search:  
man Server   6284 pages
apropos Keyword Search (all sections)
Output format
BSDi logo
[printable version]



Tk_GetColor(3)	      Tk Library Procedures	   Tk_GetColor(3)

_________________________________________________________________

NAME
       Tk_GetColor,  Tk_GetColorByValue, Tk_NameOfColor, Tk_Free-
       Color - maintain database of colors

SYNOPSIS
       #include <tk.h>

       XColor *
       Tk_GetColor(interp, tkwin, nameId)

       XColor *
       Tk_GetColorByValue(tkwin, prefPtr)

       char *
       Tk_NameOfColor(colorPtr)

       GC
       Tk_GCForColor(colorPtr, drawable)

       Tk_FreeColor(colorPtr)

ARGUMENTS
       Tcl_Interp   *interp	(in)	  Interpreter to use  for
					  error reporting.

       Tk_Window    tkwin	(in)	  Token	  for  window  in
					  which	 color	will   be
					  used.

       Tk_Uid	    nameId	(in)	  Textual  description of
					  desired color.

       XColor	    *prefPtr	(in)	  Indicates  red,  green,
					  and blue intensities of
					  desired color.

       XColor	    *colorPtr	(in)	  Pointer  to	X   color
					  information.	Must have
					  been allocated by  pre-
					  vious	 call  to Tk_Get-
					  Color or Tk_GetColorBy-
					  Value,    except   when
					  passed  to   Tk_NameOf-
					  Color.

       Drawable	    drawable	(in)	  Drawable  in	which the
					  result graphics context
					  will	 be  used.   Must
					  have	same  screen  and
					  depth as the window for
					  which	 the  color   was
					  allocated.

Tk			       4.0				1

Tk_GetColor(3)	      Tk Library Procedures	   Tk_GetColor(3)

_________________________________________________________________

DESCRIPTION
       The  Tk_GetColor	 and Tk_GetColorByValue procedures locate
       pixel values that may be used to render particular  colors
       in  the window given by tkwin.  In Tk_GetColor the desired
       color is specified with a Tk_Uid (nameId), which may  have
       any of the following forms:

       colorname	   Any	of  the valid textual names for a
			   color defined in  the  server's  color
			   database  file,  such as red or Peach-
			   Puff.

       #RGB

       #RRGGBB

       #RRRGGGBBB

       #RRRRGGGGBBBB	   A numeric specification  of	the  red,
			   green,  and blue intensities to use to
			   display the color.  Each R,	G,  or	B
			   represents a single hexadecimal digit.
			   The four forms  permit  colors  to  be
			   specified with 4-bit, 8-bit, 12-bit or
			   16-bit values.   When  fewer	 than  16
			   bits are provided for each color, they
			   represent the most significant bits of
			   the	color.	 For example, #3a7 is the
			   same as #3000a0007000.

       In Tk_GetColorByValue, the desired color is indicated with
       the  red,  green, and blue fields of the structure pointed
       to by colorPtr.

       If Tk_GetColor  or  Tk_GetColorByValue  is  successful  in
       allocating the desired color, then it returns a pointer to
       an XColor structure;  the structure  indicates  the  exact
       intensities  of	the  allocated	color  (which  may differ
       slightly from those requested, depending	 on  the  limita-
       tions of the screen) and a pixel value that may be used to
       draw in the color.  If the colormap  for	 tkwin	is  full,
       Tk_GetColor  and	 Tk_GetColorByValue  will use the closest
       existing color in the colormap.	If Tk_GetColor encounters
       an  error  while	 allocating the color (such as an unknown
       color name) then NULL is returned and an error message  is
       stored in interp->result; Tk_GetColorByValue never returns
       an error.

       Tk_GetColor and Tk_GetColorByValue maintain a database  of
       all  the	 colors	 currently in use.  If the same nameId is
       requested  multiple  times  from	 Tk_GetColor   (e.g.   by

Tk			       4.0				2

Tk_GetColor(3)	      Tk Library Procedures	   Tk_GetColor(3)

       different   windows),  or  if  the  same	 intensities  are
       requested multiple  times  from	Tk_GetColorByValue,  then
       existing pixel values will be re-used.  Re-using an exist-
       ing pixel avoids any interaction with the X server,  which
       makes  the  allocation much more efficient.  For this rea-
       son, you should generally use Tk_GetColor or  Tk_GetColor-
       ByValue	instead of Xlib procedures like XAllocColor, XAl-
       locNamedColor, or XParseColor.

       Since different calls to Tk_GetColor or Tk_GetColorByValue
       may  return  the	 same  shared pixel value, callers should
       never change the color of a pixel returned by  the  proce-
       dures.	If  you need to change a color value dynamically,
       you should use  XAllocColorCells	 to  allocate  the  pixel
       value for the color.

       The  procedure  Tk_NameOfColor  is  roughly the inverse of
       Tk_GetColor.  If its  colorPtr  argument	 was  created  by
       Tk_GetColor,  then  the	return value is the nameId string
       that was passed to Tk_GetColor to create	 the  color.   If
       colorPtr	 was  created by a call to Tk_GetColorByValue, or
       by any other mechanism, then the return value is a  string
       that  could  be	passed	to Tk_GetColor to return the same
       color.  Note:  the string returned  by  Tk_NameOfColor  is
       only guaranteed to persist until the next call to Tk_Name-
       OfColor.

       Tk_GCForColor returns a graphics context whose  Foreground
       field  is the pixel allocated for colorPtr and whose other
       fields all have default values.	This provides an easy way
       to do basic drawing with a color.  The graphics context is
       cached with the color and will exist only as long as  col-
       orPtr exists;  it is freed when the last reference to col-
       orPtr is freed by calling Tk_FreeColor.

       When a pixel value returned by Tk_GetColor or Tk_GetColor-
       ByValue is no longer needed, Tk_FreeColor should be called
       to release the color.  There should be exactly one call to
       Tk_FreeColor  for each call to Tk_GetColor or Tk_GetColor-
       ByValue.	 When a pixel value is no longer in use	 anywhere
       (i.e.  it has been freed as many times as it has been got-
       ten) Tk_FreeColor will release it  to  the  X  server  and
       delete it from the database.

KEYWORDS
       color, intensity, pixel value

Tk			       4.0				3

[top]

List of man pages available for BSDi

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net