home *** CD-ROM | disk | FTP | other *** search
/ InfoMagic Source Code 1993 July / THE_SOURCE_CODE_CD_ROM.iso / languages / tcl / tk3.3b1 / doc / 3DBorder.3 next >
Encoding:
Text File  |  1993-04-01  |  9.7 KB  |  219 lines
  1. '\"
  2. '\" Copyright (c) 1990-1993 The Regents of the University of California.
  3. '\" All rights reserved.
  4. '\"
  5. '\" Permission is hereby granted, without written agreement and without
  6. '\" license or royalty fees, to use, copy, modify, and distribute this
  7. '\" documentation for any purpose, provided that the above copyright
  8. '\" notice and the following two paragraphs appear in all copies.
  9. '\"
  10. '\" IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY
  11. '\" FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES
  12. '\" ARISING OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
  13. '\" CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. '\"
  15. '\" THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
  16. '\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
  17. '\" AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
  18. '\" ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
  19. '\" PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. '\" 
  21. '\" $Header: /user6/ouster/wish/man/RCS/3DBorder.3,v 1.12 93/04/01 09:40:48 ouster Exp $ SPRITE (Berkeley)
  22. '\" 
  23. .so man.macros
  24. .HS Tk_Get3DBorder tkc
  25. .BS
  26. .SH NAME
  27. Tk_Get3DBorder, Tk_Draw3DRectangle, Tk_Fill3DRectangle, Tk_Draw3DPolygon, Tk_Fill3DPolygon, Tk_SetBackgroundFromBorder, Tk_NameOf3DBorder, Tk_Free3DBorder \- draw borders with three-dimensional appearance
  28. .SH SYNOPSIS
  29. .nf
  30. \fB#include <tk.h>\fR
  31. .sp
  32. Tk_3DBorder
  33. \fBTk_Get3DBorder(\fIinterp, tkwin, colorMap, colorName\fB)\fR
  34. .sp
  35. void
  36. \fBTk_Draw3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  37. .sp
  38. void
  39. \fBTk_Fill3DRectangle(\fIdisplay, drawable, border, x, y, width, height, borderWidth, relief\fB)\fR
  40. .sp
  41. void
  42. \fBTk_Draw3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  43. .sp
  44. void
  45. \fBTk_Fill3DPolygon(\fIdisplay, drawable, border, pointPtr, numPoints, polyBorderWidth, leftRelief\fB)\fR
  46. .sp
  47. void
  48. \fBTk_SetBackgroundFromBorder(\fItkwin, border\fB)\fR
  49. .sp
  50. char *
  51. \fBTk_NameOf3DBorder(\fIborder\fB)\fR
  52. .sp
  53. .VS
  54. XColor *
  55. \fBTk_3DBorderColor(\fIborder\fB)\fR
  56. .VE
  57. .sp
  58. \fBTk_Free3DBorder(\fIborder\fB)\fR
  59. .SH ARGUMENTS
  60. .AS "Tk_3DBorder" borderWidth
  61. .AP Tcl_Interp *interp in
  62. Interpreter to use for error reporting.
  63. .AP Tk_Window tkwin in
  64. Token for window in which border will be drawn.
  65. .AP Colormap colormap in
  66. Colormap from which to allocate colors.  If None, then the default
  67. colormap for \fItkwin\fR's screen is used.
  68. .AP Tk_Uid colorName in
  69. Textual description of color corresponding to background (flat areas).
  70. Illuminated edges will be brighter than this, and shadowed edges will
  71. be darker than this.
  72. .AP Display *display in
  73. Xlib pointer indicating display with which drawable is associated.
  74. .AP Drawable drawable in
  75. X token for window or pixmap;  indicates where border is to be drawn.
  76. .AP Tk_3DBorder border in
  77. Token for border previously allocated in call to \fBTk_Get3DBorder\fR.
  78. .AP int x in
  79. X-coordinate of upper-left corner of rectangle describing border.
  80. .AP int y in
  81. Y-coordinate of upper-left corner of rectangle describing border.
  82. .AP int width in
  83. Width of rectangle describing border, in pixels.
  84. .AP int height in
  85. Height of rectangle describing border, in pixels.
  86. .AP int borderWidth in
  87. Width of border in pixels. Positive means border is inside rectangle
  88. given by \fIx\fR, \fIy\fR, \fIwidth\fR, \fIheight\fR, negative means
  89. border is outside rectangle.
  90. .AP int relief in
  91. Indicates 3-D position of interior of rectangle relative to exterior;
  92. should be TK_RELIEF_RAISED, TK_RELIEF_SUNKEN, TK_RELIEF_GROOVE,
  93. .VS
  94. or TK_RELIEF_RIDGE (may also be TK_RELIEF_FLAT
  95. .VE
  96. for \fBTk_Fill3DRectangle\fR).
  97. .AP XPoint *pointPtr in
  98. Pointer to array of points describing the set of vertices in a polygon.
  99. The polygon need not be closed (it will be closed automatically if it
  100. isn't).
  101. .AP int numPoints in
  102. Number of points at \fI*pointPtr\fR.
  103. .AP int polyBorderWidth in
  104. Width of border in pixels.  If positive, border is drawn to left of
  105. trajectory given by \fIpointPtr\fR;  if negative, border is drawn to
  106. right of trajectory.  If \fIleftRelief\fR is TK_RELIEF_GROOVE or
  107. TK_RELIEF_RIDGE then the border is centered on the trajectory.
  108. .AP int leftRelief in
  109. Height of left side of polygon's path relative to right.  TK_RELIEF_RAISED
  110. means left side should appear higher and TK_RELIEF_SUNKEN means right side
  111. should appear higher;
  112. .VS
  113. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean the obvious things.
  114. .VE
  115. For \fBTk_Fill3DPolygon\fR, TK_RELIEF_FLAT may also be specified to
  116. indicate no difference in height.
  117. .BE
  118.  
  119. .SH DESCRIPTION
  120. .PP
  121. These procedures provide facilities for drawing window borders in a
  122. way that produces a three-dimensional appearance.  \fBTk_Get3DBorder\fR
  123. allocates colors and Pixmaps needed to draw a border in the window
  124. given by the \fItkwin\fR argument.  The \fIcolormap\fR argument
  125. specifies a Colormap to use for allocating colors, and the \fIcolorName\fR
  126. argument indicates what colors should be used in the border.  \fIColorName\fR
  127. may be any value acceptable to \fBTk_GetColor\fR.  The color indicated
  128. by \fIcolorName\fR will not actually be used in the border;  it indicates
  129. the background color for the window (i.e. a color for flat surfaces).
  130. The illuminated portions of the border will appear brighter than indicated
  131. by \fIcolorName\fR, and the shadowed portions of the border will appear
  132. darker than \fIcolorName\fR.
  133. .PP
  134. \fBTk_Get3DBorder\fR returns a token that may be used in later calls
  135. to \fBTk_Draw3DRectangle\fR.  If an error occurs in allocating information
  136. for the border (e.g. \fIcolorName\fR isn't a legal color specifier),
  137. then NULL is returned and an error message is left in \fIinterp->result\fR.
  138. .PP
  139. Once a border structure has been created, \fBTk_Draw3DRectangle\fR may be
  140. invoked to draw the border.  The \fIdisplay\fR and \fIdrawable\fR
  141. arguments specify a window or pixmap in which the border is to be
  142. drawn.  \fIDrawable\fR need not refer to the same window as the
  143. \fItkwin\fR used to create the border, but it must refer to a compatible
  144. pixmap or window:  one associated with the same display and with the
  145. same depth as the \fItkwin\fR used to create the border.
  146. The \fIx\fR, \fIy\fR, \fIwidth\fR, and
  147. \fIheight\fR arguments define the bounding box of the border region
  148. within \fIdrawable\fR (usually \fIx\fR and \fIy\fR are zero and
  149. \fIwidth\fR and \fIheight\fR are the dimensions of the window), and
  150. \fIborderWidth\fR specifies the number of pixels actually
  151. occupied by the border.  The \fIrelief\fR argument indicates
  152. which of several three-dimensional effects is desired:
  153. TK_RELIEF_RAISED means that the interior of the rectangle should appear raised
  154. relative to the exterior of the rectangle, and
  155. TK_RELIEF_SUNKEN means that the interior should appear depressed.
  156. .VS
  157. TK_RELIEF_GROOVE and TK_RELIEF_RIDGE mean that there should appear to be
  158. a groove or ridge around the exterior of the rectangle.
  159. .VE
  160. .PP
  161. \fBTk_Fill3DRectangle\fR is somewhat like \fBTk_Draw3DRectangle\fR except
  162. that it first fills the rectangular area with the background color
  163. (one corresponding
  164. to the \fIcolorName\fR used to create \fIborder\fR).  Then it calls
  165. \fBTk_Draw3DRectangle\fR to draw a border just inside the outer edge of
  166. the rectangular area.  The argument \fIrelief\fR indicates the desired
  167. effect (TK_RELIEF_FLAT means no border should be drawn; all that
  168. happens is to fill the rectangle with the background color).
  169. .PP
  170. The procedure \fBTk_Draw3DPolygon\fR may be used to draw more complex
  171. shapes with a three-dimensional appearance.  The \fIpointPtr\fR and
  172. \fInumPoints\fR arguments define a trajectory, \fIpolyBorderWidth\fR
  173. indicates how wide the border should be (and on which side of the
  174. trajectory to draw it), and \fIleftRelief\fR indicates which side
  175. of the trajectory should appear raised.  \fBTk_Draw3DPolygon\fR
  176. draws a border around the given trajectory using the colors from
  177. \fIborder\fR to produce a three-dimensional appearance.  If the trajectory is
  178. non-self-intersecting, the appearance will be a raised or sunken
  179. polygon shape.  The trajectory may be self-intersecting, although
  180. it's not clear how useful this is.
  181. .PP
  182. \fBTk_Fill3DPolygon\fR is to \fBTk_Draw3DPolygon\fR what
  183. \fBTk_Fill3DRectangle\fR is to \fBTk_Draw3DRectangle\fR:  it fills
  184. the polygonal area with the background color from \fIborder\fR,
  185. then calls \fBTk_Draw3DPolygon\fR to draw a border around the
  186. area (unless \fIleftRelief\fR is TK_RELIEF_FLAT;  in this case no
  187. border is drawn).
  188. .PP
  189. The procedure \fBTk_SetBackgroundFromBorder\fR will modify the background
  190. pixel and/or pixmap of \fItkwin\fR to produce a result compatible
  191. with \fIborder\fR.  For color displays, the resulting background will
  192. just be the color given by the \fIcolorName\fR argument passed to
  193. \fBTk_Get3DBorder\fR when \fIborder\fR was created;  for monochrome
  194. displays, the resulting background
  195. will be a light stipple pattern, in order to distinguish the background from
  196. the illuminated portion of the border.
  197. .PP
  198. Given a token for a border, the procedure \fBTk_NameOf3DBorder\fR
  199. will return the \fIcolorName\fR string that was passed to
  200. \fBTk_Get3DBorder\fR to create the border.
  201. .PP
  202. .VS
  203. The procedure \fBTk_3DBorderColor\fR returns the XColor structure
  204. that will be used for flat surfaces drawn for its \fIborder\fR
  205. argument by procedures like \fBTk_Fill3DRectangle\fR.
  206. The return value corresponds to the \fIcolorName\fR passed to
  207. \fBTk_Get3DBorder\fR.
  208. The XColor, and its associated pixel value, will remain allocated
  209. as long as \fIborder\fR exists.
  210. .VE
  211. .PP
  212. When a border is no longer needed, \fBTk_Free3DBorder\fR should
  213. be called to release the resources associated with the border.
  214. There should be exactly one call to \fBTk_Free3DBorder\fR for
  215. each call to \fBTk_Get3DBorder\fR.
  216.  
  217. .SH KEYWORDS
  218. 3D, background, border, color, depressed, illumination, polygon, raised, shadow, three-dimensional effect
  219.