Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Tk_Alloc3DBorderFromObj(3)   Tk	Library	Procedures  Tk_Alloc3DBorderFromObj(3)

______________________________________________________________________________

NAME
       Tk_Alloc3DBorderFromObj,	    Tk_Get3DBorder,	Tk_Get3DBorderFromObj,
       Tk_Draw3DRectangle,	  Tk_Fill3DRectangle,	     Tk_Draw3DPolygon,
       Tk_Fill3DPolygon, Tk_3DVerticalBevel, Tk_3DHorizontalBevel, Tk_SetBack-
       groundFromBorder, Tk_NameOf3DBorder,  Tk_3DBorderColor,	Tk_3DBorderGC,
       Tk_Free3DBorderFromObj,	Tk_Free3DBorder	 - draw	borders	with three-di-
       mensional appearance

SYNOPSIS
       #include	<tk.h>

       Tk_3DBorder
       Tk_Alloc3DBorderFromObj(interp, tkwin, objPtr)

       Tk_3DBorder
       Tk_Get3DBorder(interp, tkwin, colorName)

       Tk_3DBorder
       Tk_Get3DBorderFromObj(tkwin, objPtr)

       void
       Tk_Draw3DRectangle(tkwin, drawable, border, x, y, width,	height,	borderWidth, relief)

       void
       Tk_Fill3DRectangle(tkwin, drawable, border, x, y, width,	height,	borderWidth, relief)

       void
       Tk_Draw3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

       void
       Tk_Fill3DPolygon(tkwin, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief)

       void
       Tk_3DVerticalBevel(tkwin, drawable, border, x, y, width,	height,	leftBevel, relief)

       void
       Tk_3DHorizontalBevel(tkwin, drawable, border, x,	y, width, height, leftIn, rightIn, topBevel, relief)

       void
       Tk_SetBackgroundFromBorder(tkwin, border)

       const char *
       Tk_NameOf3DBorder(border)

       XColor *
       Tk_3DBorderColor(border)

       GC *
       Tk_3DBorderGC(tkwin, border, which)

       Tk_Free3DBorderFromObj(tkwin, objPtr)

       Tk_Free3DBorder(border)

ARGUMENTS
       Tcl_Interp *interp (in)		     Interpreter to use	for error  re-
					     porting.

       Tk_Window tkwin (in)		     Token  for	window (for all	proce-
					     dures except Tk_Get3DBorder, must
					     be	 the window for	which the bor-
					     der was allocated).

       Tcl_Obj *objPtr (in)		     Pointer to	value whose value  de-
					     scribes  color  corresponding  to
					     background	(flat areas).  Illumi-
					     nated edges will be brighter than
					     this and shadowed edges  will  be
					     darker than this.

       char *colorName (in)		     Same  as  objPtr  except value is
					     supplied as a string rather  than
					     a value.

       Drawable	drawable (in)		     X	token  for  window  or pixmap;
					     indicates where graphics  are  to
					     be	 drawn.	  Must either be the X
					     window for	tkwin or a pixmap with
					     the  same screen and depth	as tk-
					     win.

       Tk_3DBorder border (in)		     Token for border previously allo-
					     cated in call to Tk_Get3DBorder.

       int x (in)			     X-coordinate of upper-left	corner
					     of	rectangle describing border or
					     bevel, in pixels.

       int y (in)			     Y-coordinate of upper-left	corner
					     of	rectangle describing border or
					     bevel, in pixels.

       int width (in)			     Width   of	 rectangle  describing
					     border or bevel, in pixels.

       int height (in)			     Height  of	 rectangle  describing
					     border or bevel, in pixels.

       int borderWidth (in)		     Width  of border in pixels. Posi-
					     tive means	border is inside  rec-
					     tangle  given  by	x,  y,	width,
					     height, negative means border  is
					     outside rectangle.

       int relief (in)			     Indicates	3-D  position of inte-
					     rior of value relative  to	 exte-
					     rior; should be TK_RELIEF_RAISED,
					     TK_RELIEF_SUNKEN,		TK_RE-
					     LIEF_GROOVE,  TK_RELIEF_SOLID, or
					     TK_RELIEF_RIDGE  (may   also   be
					     TK_RELIEF_FLAT for	Tk_Fill3DRect-
					     angle).

       XPoint *pointPtr	(in)		     Pointer to	array  of  points  de-
					     scribing the set of vertices in a
					     polygon.  The polygon need	not be
					     closed  (it  will be closed auto-
					     matically if it is	not).

       int numPoints (in)		     Number of points at *pointPtr.

       int polyBorderWidth (in)		     Width of border  in  pixels.   If
					     positive, border is drawn to left
					     of	trajectory given by  pointPtr;
					     if	 negative,  border is drawn to
					     right of trajectory.  If  leftRe-
					     lief   is	 TK_RELIEF_GROOVE   or
					     TK_RELIEF_RIDGE then  the	border
					     is	centered on the	trajectory.

       int leftRelief (in)		     Height  of	left side of polygon's
					     path relative to  right.	TK_RE-
					     LIEF_RAISED   means   left	  side
					     should appear higher  and	TK_RE-
					     LIEF_SUNKEN   means   right  side
					     should  appear   higher;	TK_RE-
					     LIEF_GROOVE  and  TK_RELIEF_RIDGE
					     mean  the	obvious	 things.   For
					     Tk_Fill3DPolygon,	TK_RELIEF_FLAT
					     may also be specified to indicate
					     no	difference in height.

       int leftBevel (in)		     Non-zero  means  this bevel forms
					     the left side of the value;  zero
					     means it forms the	right side.

       int leftIn (in)			     Non-zero means that the left edge
					     of	the  horizontal	 bevel	angles
					     in,  so  that  the	 bottom	of the
					     edge is farther to	the right than
					     the top.  Zero means the edge an-
					     gles out, so that the  bottom  is
					     farther to	the left than the top.

       int rightIn (in)			     Non-zero  means  that  the	 right
					     edge of the horizontal bevel  an-
					     gles  in,	so  that the bottom of
					     the edge is farther to  the  left
					     than  the	top.   Zero  means the
					     edge angles out, so that the bot-
					     tom  is farther to	the right than
					     the top.

       int topBevel (in)		     Non-zero means this  bevel	 forms
					     the  top side of the value;  zero
					     means it forms the	bottom side.

       int which (in)			     Specifies which of	 the  border's
					     graphics	contexts  is  desired.
					     Must      be	TK_3D_FLAT_GC,
					     TK_3D_LIGHT_GC, or	TK_3D_DARK_GC.
______________________________________________________________________________

DESCRIPTION
       These procedures	provide	facilities for drawing window borders in a way
       that produces a three-dimensional appearance.   Tk_Alloc3DBorderFromObj
       allocates  colors  and  Pixmaps	needed	to draw	a border in the	window
       given by	the tkwin argument.  The value of  objPtr  is  a  standard  Tk
       color  name  that determines the	border colors.	The color indicated by
       objPtr will not actually	be used	in the border;	it indicates the back-
       ground  color for the window (i.e. a color for flat surfaces).  The il-
       luminated portions of the border	will appear brighter than indicated by
       objPtr, and the shadowed	portions of the	border will appear darker than
       objPtr.

       Tk_Alloc3DBorderFromObj returns a token that may	be used	in later calls
       to  Tk_Draw3DRectangle.	 If  an	error occurs in	allocating information
       for the border (e.g. a bogus color name was given)  then	 NULL  is  re-
       turned  and  an	error message is left as the result of interpreter in-
       terp.  If it returns successfully, Tk_Alloc3DBorderFromObj  caches  in-
       formation  about	 the  return  value  in	objPtr,	which speeds up	future
       calls to	Tk_Alloc3DBorderFromObj	with the same objPtr and tkwin.

       Tk_Get3DBorder is identical to Tk_Alloc3DBorderFromObj except that  the
       color  is  specified  with  a string instead of a value.	 This prevents
       Tk_Get3DBorder from caching the return value, so	Tk_Get3DBorder is less
       efficient than Tk_Alloc3DBorderFromObj.

       Tk_Get3DBorderFromObj  returns  the token for an	existing border, given
       the window and color name used to create	the  border.   Tk_Get3DBorder-
       FromObj	does not actually create the border; it	must already have been
       created with a previous call to Tk_Alloc3DBorderFromObj or Tk_Get3DBor-
       der.   The  return  value  is  cached in	objPtr,	which speeds up	future
       calls to	Tk_Get3DBorderFromObj with the same objPtr and tkwin.

       Once a border structure has been	created, Tk_Draw3DRectangle may	be in-
       voked  to draw the border.  The tkwin argument specifies	the window for
       which the border	was allocated, and  drawable  specifies	 a  window  or
       pixmap  in which	the border is to be drawn.  Drawable need not refer to
       the same	window as tkwin, but it	must refer to a	compatible  pixmap  or
       window:	one associated with the	same screen and	with the same depth as
       tkwin.  The x, y, width,	and height arguments define the	 bounding  box
       of  the	border	region	within	drawable (usually x and	y are zero and
       width and height	are the	dimensions of  the  window),  and  borderWidth
       specifies  the  number  of pixels actually occupied by the border.  The
       relief argument indicates which of several three-dimensional effects is
       desired:	 TK_RELIEF_RAISED  means  that	the  interior of the rectangle
       should appear raised relative to	the exterior  of  the  rectangle,  and
       TK_RELIEF_SUNKEN	 means	that  the  interior  should  appear depressed.
       TK_RELIEF_GROOVE	and TK_RELIEF_RIDGE mean that there should  appear  to
       be a groove or ridge around the exterior	of the rectangle.

       Tk_Fill3DRectangle  is  somewhat	like Tk_Draw3DRectangle	except that it
       first fills the rectangular area	with the background color (one	corre-
       sponding	  to  the  color  used	to  create  border).   Then  it	 calls
       Tk_Draw3DRectangle to draw a border just	inside the outer edge  of  the
       rectangular  area.   The	 argument  relief indicates the	desired	effect
       (TK_RELIEF_FLAT means no	border should be drawn;	all that happens is to
       fill the	rectangle with the background color).

       The  procedure Tk_Draw3DPolygon may be used to draw more	complex	shapes
       with a three-dimensional	appearance.  The pointPtr and numPoints	 argu-
       ments  define a trajectory, polyBorderWidth indicates how wide the bor-
       der should be (and on which side	of the trajectory  to  draw  it),  and
       leftRelief indicates which side of the trajectory should	appear raised.
       Tk_Draw3DPolygon	draws a	border around the given	trajectory  using  the
       colors  from  border to produce a three-dimensional appearance.	If the
       trajectory is non-self-intersecting, the	appearance will	be a raised or
       sunken  polygon	shape.	 The  trajectory may be	self-intersecting, al-
       though it's not clear how useful	this is.

       Tk_Fill3DPolygon	is to Tk_Draw3DPolygon what Tk_Fill3DRectangle	is  to
       Tk_Draw3DRectangle:   it	 fills	the polygonal area with	the background
       color from border, then calls Tk_Draw3DPolygon to draw a	border	around
       the  area  (unless leftRelief is	TK_RELIEF_FLAT;	in this	case no	border
       is drawn).

       The  procedures	Tk_3DVerticalBevel  and	 Tk_3DHorizontalBevel  provide
       lower-level  drawing  primitives	 that  are  used by procedures such as
       Tk_Draw3DRectangle.  These procedures are  also	useful	in  their  own
       right  for drawing rectilinear border shapes.  Tk_3DVerticalBevel draws
       a vertical beveled edge,	such as	the left or right side of a rectangle,
       and  Tk_3DHorizontalBevel  draws	a horizontal beveled edge, such	as the
       top or bottom of	a rectangle.  Each procedure takes x,  y,  width,  and
       height arguments	that describe the rectangular area of the beveled edge
       (e.g., width is the border width	for Tk_3DVerticalBevel).  The leftBor-
       der  and	 topBorder arguments indicate the position of the border rela-
       tive to the "inside" of the value, and relief indicates the  relief  of
       the  inside  of	the value relative to the outside.  Tk_3DVerticalBevel
       just draws a rectangular	region.	 Tk_3DHorizontalBevel draws  a	trape-
       zoidal  region  to generate mitered corners;  it	should be called after
       Tk_3DVerticalBevel (otherwise Tk_3DVerticalBevel	will overwrite the mi-
       tering  in the corner).	The leftIn and rightIn arguments to Tk_3DHori-
       zontalBevel describe the	mitering at the	corners;  a value of  1	 means
       that  the  bottom edge of the trapezoid will be shorter than the	top, 0
       means it	will be	longer.	 For example, to draw a	rectangular border the
       top  bevel  should be drawn with	1 for both leftIn and rightIn, and the
       bottom bevel should be drawn with 0 for both arguments.

       The procedure Tk_SetBackgroundFromBorder	 will  modify  the  background
       pixel  and/or  pixmap of	tkwin to produce a result compatible with bor-
       der.  For color displays, the resulting background  will	 just  be  the
       color  specified	when border was	created;  for monochrome displays, the
       resulting background will be a light stipple pattern, in	order to  dis-
       tinguish	the background from the	illuminated portion of the border.

       Given a token for a border, the procedure Tk_NameOf3DBorder will	return
       the color name that was used to create the border.

       The procedure Tk_3DBorderColor returns the XColor structure  that  will
       be  used	 for flat surfaces drawn for its border	argument by procedures
       like Tk_Fill3DRectangle.	 The return value  corresponds	to  the	 color
       name  that  was used to create the border.  The XColor, and its associ-
       ated pixel value, will remain allocated as long as border exists.

       The procedure Tk_3DBorderGC returns one of the X	graphics contexts that
       are  used  to draw the border.  The argument which selects which	one of
       the three possible GC's:	TK_3D_FLAT_GC returns  the  context  used  for
       flat  surfaces,	TK_3D_LIGHT_GC	returns	the context for	light shadows,
       and TK_3D_DARK_GC returns the context for dark shadows.

       When  a	border	is  no	longer	 needed,   Tk_Free3DBorderFromObj   or
       Tk_Free3DBorder	should	be  called to release the resources associated
       with it.	 For Tk_Free3DBorderFromObj the	border to release is specified
       with  the  window  and  color  name  used  to  create  the  border; for
       Tk_Free3DBorder the border to release is	specified with the Tk_3DBorder
       token   for   the   border.   There  should  be	exactly	 one  call  to
       Tk_Free3DBorderFromObj or  Tk_Free3DBorder  for	each  call  to	Tk_Al-
       loc3DBorderFromObj or Tk_Get3DBorder.

KEYWORDS
       3D, background, border, color, depressed, illumination, value, polygon,
       raised, shadow, three-dimensional effect

Tk				      8.1	    Tk_Alloc3DBorderFromObj(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_3DBorderColor.tk86&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help