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	object 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
					     an	object.

       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 object 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  object;
					     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 object;  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 in interp-_result.  If  it  returns
       successfully,  Tk_Alloc3DBorderFromObj caches information about the re-
       turn value in objPtr, which speeds up future calls to Tk_Alloc3DBorder-
       FromObj with the	same objPtr and	tkwin.

       Tk_Get3DBorder  is identical to Tk_Alloc3DBorderFromObj except that the
       color is	specified with a string	instead	of an object.	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 object, and	relief indicates the relief of
       the inside of the object	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,	object,	 poly-
       gon, 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.tk85&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help