home *** CD-ROM | disk | FTP | other *** search
/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / 3DBorder.3 next >
Encoding:
Text File  |  1995-07-26  |  21.4 KB  |  331 lines
  1.  
  2.  
  3.  
  4.      TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))            TTTTkkkk (((( ))))             TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))
  5.  
  6.  
  7.  
  8.      _________________________________________________________________
  9.  
  10.      NNNNAAAAMMMMEEEE
  11.           Tk_Get3DBorder,   Tk_Draw3DRectangle,    Tk_Fill3DRectangle,
  12.           Tk_Draw3DPolygon,                          Tk_Fill3DPolygon,
  13.           Tk_SetBackgroundFromBorder,               Tk_NameOf3DBorder,
  14.           Tk_Free3DBorder   -   draw  borders  with  three-dimensional
  15.           appearance
  16.  
  17.      SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  18.           ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>
  19.  
  20.           Tk_3DBorder
  21.           TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((_i_n_t_e_r_p, _t_k_w_i_n, _c_o_l_o_r_M_a_p, _c_o_l_o_r_N_a_m_e))))
  22.  
  23.           void
  24.           TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee((((_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r_W_i_d_t_h, _r_e_l_i_e_f))))
  25.  
  26.           void
  27.           TTTTkkkk____FFFFiiiillllllll3333DDDDRRRReeeeccccttttaaaannnngggglllleeee((((_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _x, _y, _w_i_d_t_h, _h_e_i_g_h_t, _b_o_r_d_e_r_W_i_d_t_h, _r_e_l_i_e_f))))
  28.  
  29.           void
  30.           TTTTkkkk____DDDDrrrraaaawwww3333DDDDPPPPoooollllyyyyggggoooonnnn((((_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _p_o_i_n_t_P_t_r, _n_u_m_P_o_i_n_t_s, _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h, _l_e_f_t_R_e_l_i_e_f))))
  31.  
  32.           void
  33.           TTTTkkkk____FFFFiiiillllllll3333DDDDPPPPoooollllyyyyggggoooonnnn((((_d_i_s_p_l_a_y, _d_r_a_w_a_b_l_e, _b_o_r_d_e_r, _p_o_i_n_t_P_t_r, _n_u_m_P_o_i_n_t_s, _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h, _l_e_f_t_R_e_l_i_e_f))))
  34.  
  35.           void
  36.           TTTTkkkk____SSSSeeeettttBBBBaaaacccckkkkggggrrrroooouuuunnnnddddFFFFrrrroooommmmBBBBoooorrrrddddeeeerrrr((((_t_k_w_i_n, _b_o_r_d_e_r))))
  37.  
  38.           char *
  39.           TTTTkkkk____NNNNaaaammmmeeeeOOOOffff3333DDDDBBBBoooorrrrddddeeeerrrr((((_b_o_r_d_e_r))))
  40.  
  41.           XColor *                                                      |
  42.           TTTTkkkk____3333DDDDBBBBoooorrrrddddeeeerrrrCCCCoooolllloooorrrr((((_b_o_r_d_e_r))))                                      |
  43.  
  44.           TTTTkkkk____FFFFrrrreeeeeeee3333DDDDBBBBoooorrrrddddeeeerrrr((((_b_o_r_d_e_r))))
  45.  
  46.      AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
  47.           Tcl_Interp    *_i_n_t_e_r_p       (in)      Interpreter to use for
  48.                                                 error reporting.
  49.  
  50.           Tk_Window     _t_k_w_i_n         (in)      Token  for  window  in
  51.                                                 which  border  will be
  52.                                                 drawn.
  53.  
  54.           Colormap      _c_o_l_o_r_m_a_p      (in)      Colormap from which to
  55.                                                 allocate  colors.   If
  56.                                                 None, then the default
  57.                                                 colormap  for  _t_k_w_i_n's
  58.                                                 screen is used.
  59.  
  60.  
  61.  
  62.  
  63.      Page 1                                          (printed 7/23/95)
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.      TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))            TTTTkkkk (((( ))))             TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))
  71.  
  72.  
  73.  
  74.           Tk_Uid        _c_o_l_o_r_N_a_m_e     (in)      Textual description of
  75.                                                 color corresponding to
  76.                                                 background       (flat
  77.                                                 areas).    Illuminated
  78.                                                 edges will be brighter
  79.                                                 than     this,     and
  80.                                                 shadowed edges will be
  81.                                                 darker than this.
  82.  
  83.           Display       *_d_i_s_p_l_a_y      (in)      Xlib           pointer
  84.                                                 indicating     display
  85.                                                 with which drawable is
  86.                                                 associated.
  87.  
  88.           Drawable      _d_r_a_w_a_b_l_e      (in)      X token for window  or
  89.                                                 pixmap;      indicates
  90.                                                 where border is to  be
  91.                                                 drawn.
  92.  
  93.           Tk_3DBorder   _b_o_r_d_e_r        (in)      Token    for    border
  94.                                                 previously   allocated
  95.                                                 in       call       to
  96.                                                 TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr.
  97.  
  98.           int           _x             (in)      X-coordinate        of
  99.                                                 upper-left  corner  of
  100.                                                 rectangle   describing
  101.                                                 border.
  102.  
  103.           int           _y             (in)      Y-coordinate        of
  104.                                                 upper-left  corner  of
  105.                                                 rectangle   describing
  106.                                                 border.
  107.  
  108.           int           _w_i_d_t_h         (in)      Width   of   rectangle
  109.                                                 describing  border, in
  110.                                                 pixels.
  111.  
  112.           int           _h_e_i_g_h_t        (in)      Height  of   rectangle
  113.                                                 describing  border, in
  114.                                                 pixels.
  115.  
  116.           int           _b_o_r_d_e_r_W_i_d_t_h   (in)      Width  of  border   in
  117.                                                 pixels. Positive means
  118.                                                 border    is    inside
  119.                                                 rectangle  given by _x,
  120.                                                 _y,   _w_i_d_t_h,    _h_e_i_g_h_t,
  121.                                                 negative  means border
  122.                                                 is outside rectangle.
  123.  
  124.           int           _r_e_l_i_e_f        (in)      Indicates 3-D position
  125.                                                 of     interior     of
  126.  
  127.  
  128.  
  129.      Page 2                                          (printed 7/23/95)
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.      TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))            TTTTkkkk (((( ))))             TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))
  137.  
  138.  
  139.  
  140.                                                 rectangle relative  to
  141.                                                 exterior;   should  be
  142.                                                 TK_RELIEF_RAISED,
  143.                                                 TK_RELIEF_SUNKEN,
  144.                                                 TK_RELIEF_GROOVE,   or  |
  145.                                                 TK_RELIEF_RIDGE   (may  |
  146.                                                 also be TK_RELIEF_FLAT
  147.                                                 for
  148.                                                 TTTTkkkk____FFFFiiiillllllll3333DDDDRRRReeeeccccttttaaaannnngggglllleeee).
  149.  
  150.           XPoint        *_p_o_i_n_t_P_t_r     (in)      Pointer  to  array  of
  151.                                                 points  describing the
  152.                                                 set of vertices  in  a
  153.                                                 polygon.   The polygon
  154.                                                 need not be closed (it
  155.                                                 will     be     closed
  156.                                                 automatically  if   it
  157.                                                 isn't).
  158.  
  159.           int           _n_u_m_P_o_i_n_t_s     (in)      Number  of  points  at
  160.                                                 *_p_o_i_n_t_P_t_r.
  161.  
  162.           int           _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h(in)     Width  of  border   in
  163.                                                 pixels.   If positive,
  164.                                                 border  is  drawn   to
  165.                                                 left   of   trajectory
  166.                                                 given by _p_o_i_n_t_P_t_r;  if
  167.                                                 negative,   border  is
  168.                                                 drawn  to   right   of
  169.                                                 trajectory.         If
  170.                                                 _l_e_f_t_R_e_l_i_e_f          is
  171.                                                 TK_RELIEF_GROOVE    or
  172.                                                 TK_RELIEF_RIDGE   then
  173.                                                 the border is centered
  174.                                                 on the trajectory.
  175.  
  176.           int           _l_e_f_t_R_e_l_i_e_f    (in)      Height of left side of
  177.                                                 polygon's         path
  178.                                                 relative   to   right.
  179.                                                 TK_RELIEF_RAISED means
  180.                                                 left    side    should
  181.                                                 appear    higher   and
  182.                                                 TK_RELIEF_SUNKEN means
  183.                                                 right    side   should
  184.                                                 appear         higher;  |
  185.                                                 TK_RELIEF_GROOVE   and  |
  186.                                                 TK_RELIEF_RIDGE   mean  |
  187.                                                 the   obvious  things.
  188.                                                 For  TTTTkkkk____FFFFiiiillllllll3333DDDDPPPPoooollllyyyyggggoooonnnn,
  189.                                                 TK_RELIEF_FLAT     may
  190.                                                 also be  specified  to
  191.                                                 indicate no difference
  192.  
  193.  
  194.  
  195.      Page 3                                          (printed 7/23/95)
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.      TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))            TTTTkkkk (((( ))))             TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))
  203.  
  204.  
  205.  
  206.                                                 in height.
  207.      _________________________________________________________________
  208.  
  209.  
  210.      DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  211.           These  procedures  provide  facilities  for  drawing  window
  212.           borders   in   a   way  that  produces  a  three-dimensional
  213.           appearance.  TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr  allocates  colors  and  Pixmaps
  214.           needed  to  draw  a  border in the window given by the _t_k_w_i_n
  215.           argument.  The _c_o_l_o_r_m_a_p argument specifies a Colormap to use
  216.           for  allocating colors, and the _c_o_l_o_r_N_a_m_e argument indicates
  217.           what colors should be used in the border.  _C_o_l_o_r_N_a_m_e may  be
  218.           any value acceptable to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr.  The color indicated by
  219.           _c_o_l_o_r_N_a_m_e will not actually  be  used  in  the  border;   it
  220.           indicates  the background color for the window (i.e. a color
  221.           for flat surfaces).  The illuminated portions of the  border
  222.           will  appear  brighter  than indicated by _c_o_l_o_r_N_a_m_e, and the
  223.           shadowed portions of the  border  will  appear  darker  than
  224.           _c_o_l_o_r_N_a_m_e.
  225.  
  226.           TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr returns a token that may  be  used  in  later
  227.           calls   to   TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee.   If  an  error  occurs  in
  228.           allocating information for the border (e.g. _c_o_l_o_r_N_a_m_e  isn't
  229.           a legal color specifier), then NULL is returned and an error
  230.           message is left in _i_n_t_e_r_p->_r_e_s_u_l_t.
  231.  
  232.           Once a border structure has been created, TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee
  233.           may be invoked to draw the border.  The _d_i_s_p_l_a_y and _d_r_a_w_a_b_l_e
  234.           arguments specify a window or pixmap in which the border  is
  235.           to  be drawn.  _D_r_a_w_a_b_l_e need not refer to the same window as
  236.           the _t_k_w_i_n used to create the border, but it must refer to  a
  237.           compatible  pixmap  or window:  one associated with the same
  238.           display and with the same depth as the _t_k_w_i_n used to  create
  239.           the  border.   The  _x, _y, _w_i_d_t_h, and _h_e_i_g_h_t arguments define
  240.           the bounding  box  of  the  border  region  within  _d_r_a_w_a_b_l_e
  241.           (usually  _x  and  _y  are  zero  and _w_i_d_t_h and _h_e_i_g_h_t are the
  242.           dimensions of the window),  and  _b_o_r_d_e_r_W_i_d_t_h  specifies  the
  243.           number  of  pixels  actually  occupied  by  the border.  The
  244.           _r_e_l_i_e_f argument indicates which of several three-dimensional
  245.           effects is desired: TK_RELIEF_RAISED means that the interior
  246.           of the  rectangle  should  appear  raised  relative  to  the
  247.           exterior  of  the rectangle, and TK_RELIEF_SUNKEN means that
  248.           the interior should appear depressed.  TK_RELIEF_GROOVE  and  |
  249.           TK_RELIEF_RIDGE mean that there should appear to be a groove  |
  250.           or ridge around the exterior of the rectangle.
  251.  
  252.           TTTTkkkk____FFFFiiiillllllll3333DDDDRRRReeeeccccttttaaaannnngggglllleeee  is  somewhat   like   TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee
  253.           except  that  it  first  fills the rectangular area with the
  254.           background color (one corresponding to the _c_o_l_o_r_N_a_m_e used to
  255.           create  _b_o_r_d_e_r).  Then it calls TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee to draw a
  256.           border just inside the outer edge of the  rectangular  area.
  257.           The   argument   _r_e_l_i_e_f   indicates   the   desired   effect
  258.  
  259.  
  260.  
  261.      Page 4                                          (printed 7/23/95)
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.      TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))            TTTTkkkk (((( ))))             TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr((((3333))))
  269.  
  270.  
  271.  
  272.           (TK_RELIEF_FLAT means no border should be  drawn;  all  that
  273.           happens is to fill the rectangle with the background color).
  274.  
  275.           The procedure TTTTkkkk____DDDDrrrraaaawwww3333DDDDPPPPoooollllyyyyggggoooonnnn may  be  used  to  draw  more
  276.           complex  shapes  with  a  three-dimensional appearance.  The
  277.           _p_o_i_n_t_P_t_r  and  _n_u_m_P_o_i_n_t_s  arguments  define  a   trajectory,
  278.           _p_o_l_y_B_o_r_d_e_r_W_i_d_t_h indicates how wide the border should be (and
  279.           on which side of the trajectory to draw it), and  _l_e_f_t_R_e_l_i_e_f
  280.           indicates which side of the trajectory should appear raised.
  281.           TTTTkkkk____DDDDrrrraaaawwww3333DDDDPPPPoooollllyyyyggggoooonnnn draws a border around the given  trajectory
  282.           using  the colors from _b_o_r_d_e_r to produce a three-dimensional
  283.           appearance.  If the trajectory is non-self-intersecting, the
  284.           appearance  will  be  a raised or sunken polygon shape.  The
  285.           trajectory may be self-intersecting, although it's not clear
  286.           how useful this is.
  287.  
  288.           TTTTkkkk____FFFFiiiillllllll3333DDDDPPPPoooollllyyyyggggoooonnnn     is     to     TTTTkkkk____DDDDrrrraaaawwww3333DDDDPPPPoooollllyyyyggggoooonnnn     what
  289.           TTTTkkkk____FFFFiiiillllllll3333DDDDRRRReeeeccccttttaaaannnngggglllleeee  is  to TTTTkkkk____DDDDrrrraaaawwww3333DDDDRRRReeeeccccttttaaaannnngggglllleeee:  it fills the
  290.           polygonal area with the background color from  _b_o_r_d_e_r,  then
  291.           calls  TTTTkkkk____DDDDrrrraaaawwww3333DDDDPPPPoooollllyyyyggggoooonnnn  to  draw  a  border around the area
  292.           (unless _l_e_f_t_R_e_l_i_e_f  is  TK_RELIEF_FLAT;   in  this  case  no
  293.           border is drawn).
  294.  
  295.           The procedure  TTTTkkkk____SSSSeeeettttBBBBaaaacccckkkkggggrrrroooouuuunnnnddddFFFFrrrroooommmmBBBBoooorrrrddddeeeerrrr  will  modify  the
  296.           background  pixel and/or pixmap of _t_k_w_i_n to produce a result
  297.           compatible with _b_o_r_d_e_r.  For color displays,  the  resulting
  298.           background  will  just  be  the color given by the _c_o_l_o_r_N_a_m_e
  299.           argument passed to TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr when _b_o_r_d_e_r  was  created;
  300.           for  monochrome displays, the resulting background will be a
  301.           light  stipple  pattern,  in  order   to   distinguish   the
  302.           background from the illuminated portion of the border.
  303.  
  304.           Given a token for a border, the procedure  TTTTkkkk____NNNNaaaammmmeeeeOOOOffff3333DDDDBBBBoooorrrrddddeeeerrrr
  305.           will   return  the  _c_o_l_o_r_N_a_m_e  string  that  was  passed  to
  306.           TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr to create the border.
  307.  
  308.           The procedure TTTTkkkk____3333DDDDBBBBoooorrrrddddeeeerrrrCCCCoooolllloooorrrr returns the XColor  structure  |
  309.           that  will  be  used  for flat surfaces drawn for its _b_o_r_d_e_r  |
  310.           argument by procedures like TTTTkkkk____FFFFiiiillllllll3333DDDDRRRReeeeccccttttaaaannnngggglllleeee.  The  return  |
  311.           value corresponds to the _c_o_l_o_r_N_a_m_e passed to TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr.  |
  312.           The XColor, and its  associated  pixel  value,  will  remain  |
  313.           allocated as long as _b_o_r_d_e_r exists.
  314.  
  315.           When a border is no longer needed, TTTTkkkk____FFFFrrrreeeeeeee3333DDDDBBBBoooorrrrddddeeeerrrr should be
  316.           called  to release the resources associated with the border.
  317.           There should be exactly one call to TTTTkkkk____FFFFrrrreeeeeeee3333DDDDBBBBoooorrrrddddeeeerrrr for each
  318.           call to TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr.
  319.  
  320.  
  321.      KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  322.           3D,  background,  border,  color,  depressed,  illumination,
  323.           polygon, raised, shadow, three-dimensional effect
  324.  
  325.  
  326.  
  327.      Page 5                                          (printed 7/23/95)
  328.  
  329.  
  330.  
  331.