Tk_FreeColor man page on OpenMandriva

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

Tk_AllocColorFromObj(3)	     Tk Library Procedures     Tk_AllocColorFromObj(3)

______________________________________________________________________________

NAME
       Tk_AllocColorFromObj,  Tk_GetColor,  Tk_GetColorFromObj, Tk_GetColorBy‐
       Value, Tk_NameOfColor,  Tk_FreeColorFromObj,  Tk_FreeColor  -  maintain
       database of colors

SYNOPSIS
       #include <tk.h>

       XColor *
       Tk_AllocColorFromObj(interp, tkwin, objPtr)

       XColor *
       Tk_GetColor(interp, tkwin, name)

       XColor *
       Tk_GetColorFromObj(tkwin, objPtr)

       XColor *
       Tk_GetColorByValue(tkwin, prefPtr)

       const char *
       Tk_NameOfColor(colorPtr)

       GC
       Tk_GCForColor(colorPtr, drawable)

       Tk_FreeColorFromObj(tkwin, objPtr)

       Tk_FreeColor(colorPtr)

ARGUMENTS
       Tcl_Interp *interp (in)		  Interpreter to use for error report‐
					  ing.

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

       Tcl_Obj *objPtr (in/out)		  String   value   describes   desired
					  color; internal rep will be modified
					  to  cache  pointer  to corresponding
					  (XColor *).

       char *name (in)			  Same as objPtr except description of
					  color	 is  passed  as	 a  string and
					  resulting (XColor *) is not cached.

       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 previous
					  call	   to	 Tk_AllocColorFromObj,
					  Tk_GetColor  or  Tk_GetColorByValue,
					  except  when	passed	to  Tk_NameOf‐
					  Color.

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

DESCRIPTION
       These  procedures  manage  the  colors  being used by a Tk application.
       They allow colors to be shared  whenever	 possible,  so	that  colormap
       space  is  preserved,  and they pick closest available colors when col‐
       ormap space is exhausted.

       Given a textual description of a color, Tk_AllocColorFromObj locates  a
       pixel  value  that may be used to render the color in a particular win‐
       dow.  The desired color is specified with an object whose string	 value
       must have one 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
			   PeachPuff.

       #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 rep‐
			   resent the most significant bits of the color.  For
			   example, #3a7 is the same as #3000a0007000.

       Tk_AllocColorFromObj 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  limitations
       of  the	screen)	 and  a	 pixel value that may be used to draw with the
       color in tkwin.	If an error occurs in Tk_AllocColorFromObj (such as an
       unknown	color  name)  then  NULL  is  returned and an error message is
       stored in interp's result if interp is not NULL.	 If the	 colormap  for
       tkwin is full, Tk_AllocColorFromObj will use the closest existing color
       in the colormap.	 Tk_AllocColorFromObj  caches  information  about  the
       return value in objPtr, which speeds up future calls to procedures such
       as Tk_AllocColorFromObj and Tk_GetColorFromObj.

       Tk_GetColor  is	identical  to  Tk_AllocColorFromObj  except  that  the
       description  of	the  color  is	specified  with a string instead of an
       object.	This prevents Tk_GetColor from caching the  return  value,  so
       Tk_GetColor is less efficient than Tk_AllocColorFromObj.

       Tk_GetColorFromObj  returns  the token for an existing color, given the
       window and description used to create  the  color.   Tk_GetColorFromObj
       does  not  actually  create the color; the color must already have been
       created with a previous call to	Tk_AllocColorFromObj  or  Tk_GetColor.
       The  return  value is cached in objPtr, which speeds up future calls to
       Tk_GetColorFromObj with the same objPtr and tkwin.

       Tk_GetColorByValue is similar to Tk_GetColor except  that  the  desired
       color  is  indicated with the red, green, and blue fields of the struc‐
       ture pointed to by colorPtr.

       This package maintains a database of all the colors currently  in  use.
       If  the	same  color  is	 requested  multiple times from Tk_GetColor or
       Tk_AllocColorFromObj (e.g. by different windows), or if the same inten‐
       sities  are  requested  multiple	 times	from  Tk_GetColorByValue, then
       existing pixel values will be  re-used.	 Re-using  an  existing	 pixel
       avoids  any interaction with the window server, which makes the alloca‐
       tion much more efficient.  These procedures  also  provide  a  portable
       interface that works across all platforms.  For this reason, you should
       generally use Tk_AllocColorFromObj, Tk_GetColor, or  Tk_GetColorByValue
       instead of lower level procedures like XAllocColor.

       Since  different calls to this package may return the same shared pixel
       value, callers should never change the color of a pixel returned by the
       procedures.   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_AllocColorFromObj or Tk_Get‐
       Color then the return value is the string that was used 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_NameOfColor.

       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	 colorPtr exists;  it is freed when the last reference to col‐
       orPtr is freed by calling Tk_FreeColor.

       When a color is no longer needed	 Tk_FreeColorFromObj  or  Tk_FreeColor
       should  be  called to release it.  For Tk_FreeColorFromObj the color to
       release is specified with the same information used to create  it;  for
       Tk_FreeColor  the  color	 to release is specified with a pointer to its
       XColor structure.  There should be exactly one call to Tk_FreeColorFro‐
       mObj  or	 Tk_FreeColor  for  each call to Tk_AllocColorFromObj, Tk_Get‐
       Color, or Tk_GetColorByValue.

KEYWORDS
       color, intensity, object, pixel value

Tk				      8.1	       Tk_AllocColorFromObj(3)
[top]

List of man pages available for OpenMandriva

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