IRIX Base Documentation 2002 November/SGI IRIX Base Documentation 2002 November.iso/usr/share/catman/u_man/cat3/Tk/getcursor.z/getcursor

Text File | 2002-10-03 | 14.3 KB | 265 lines

TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))



NNNNAAAAMMMMEEEE
     Tk_GetCursor, Tk_GetCursorFromData, Tk_NameOfCursor, Tk_FreeCursor -
     maintain database of cursors

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
     ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>>

     Cursor
     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((_i_n_t_e_r_p, _t_k_w_i_n, _n_a_m_e_I_d))))

     Cursor
     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa((((_i_n_t_e_r_p, _t_k_w_i_n, _s_o_u_r_c_e, _m_a_s_k, _w_i_d_t_h, _h_e_i_g_h_t,
      _x_H_o_t, _y_H_o_t, _f_g, _b_g))))

     char *
     TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr((((_d_i_s_p_l_a_y, _c_u_r_s_o_r))))

     TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr((((_d_i_s_p_l_a_y, _c_u_r_s_o_r))))

AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS
     Tcl_Interp      *_i_n_t_e_r_p     (in)      Interpreter to use for error
                                           reporting.

     Tk_Window       _t_k_w_i_n       (in)      Token for window in which the
                                           cursor will be used.

     Tk_Uid          _n_a_m_e_I_d      (in)      Description of cursor;  see below
                                           for possible values.

     char            *_s_o_u_r_c_e     (in)      Data for cursor bitmap, in standard
                                           bitmap format.

     char            *_m_a_s_k       (in)      Data for mask bitmap, in standard
                                           bitmap format.

     int             _w_i_d_t_h       (in)      Width of _s_o_u_r_c_e and _m_a_s_k.          |

     int             _h_e_i_g_h_t      (in)      Height of _s_o_u_r_c_e and _m_a_s_k.         |

     int             _x_H_o_t        (in)      X-location of cursor hot-spot.     |

     int             _y_H_o_t        (in)      Y-location of cursor hot-spot.     |

     Tk_Uid          _f_g          (in)      Textual description of foreground
                                           color for cursor.

     Tk_Uid          _b_g          (in)      Textual description of background
                                           color for cursor.

     Display         *_d_i_s_p_l_a_y    (in)      Display for which _c_u_r_s_o_r was
                                           allocated.




                                                                        PPPPaaaaggggeeee 1111






TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))



     Cursor          _c_u_r_s_o_r      (in)      X identifier for cursor.  If passed
                                           toTTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr, must have been
                                           returned by some previous call to
                                           TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or
                                           TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa.


DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     These procedures manage a collection of cursors being used by an
     application.  The procedures allow cursors to be re-used efficiently,
     thereby avoiding server overhead, and also allow cursors to be named with
     character strings (actually Tk_Uids).

     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr takes as argument a Tk_Uid describing a cursor, and returns
     the X identifier for a cursor corresponding to the description.  It re-
     uses an existing cursor if possible and creates a new one otherwise.
     _N_a_m_e_I_d must be a standard Tcl list with one of the following forms:

     _n_a_m_e  [_f_g_C_o_l_o_r  [_b_g_C_o_l_o_r]]
          _N_a_m_e is the name of a cursor in the standard X cursor font, i.e.,
          any of the names defined in ccccuuuurrrrssssoooorrrrffffoooonnnntttt....hhhh, without the XXXXCCCC____.  Some
          example values are XXXX____ccccuuuurrrrssssoooorrrr, hhhhaaaannnndddd2222, or lllleeeefffftttt____ppppttttrrrr.  Appendix B of
          ``The X Window System'' by Scheifler & Gettys has illustrations
          showing what each of these cursors looks like.  If _f_g_C_o_l_o_r and
          _b_g_C_o_l_o_r are both specified, they give the foreground and background
          colors to use for the cursor (any of the forms acceptable to
          TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr may be used).  If only _f_g_C_o_l_o_r is specified, then there
          will be no background color:  the background will be transparent.
          If no colors are specified, then the cursor will use black for its
          foreground color and white for its background color.

     @@@@_s_o_u_r_c_e_N_a_m_e  _m_a_s_k_N_a_m_e  _f_g_C_o_l_o_r  _b_g_C_o_l_o_r
          In this form, _s_o_u_r_c_e_N_a_m_e and _m_a_s_k_N_a_m_e are the names of files
          describing bitmaps for the cursor's source bits and mask.  Each file
          must be in standard X11 or X10 bitmap format.  _F_g_C_o_l_o_r and _b_g_C_o_l_o_r
          indicate the colors to use for the cursor, in any of the forms
          acceptable to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr.

     @@@@_s_o_u_r_c_e_N_a_m_e  _f_g_C_o_l_o_r
          This form is similar to the one above, except that the source is
          used as mask also.  This means that the cursor's background is
          transparent.

     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa allows cursors to be created from in-memory
     descriptions of their source and mask bitmaps.  _S_o_u_r_c_e points to standard
     bitmap data for the cursor's source bits, and _m_a_s_k points to standard
     bitmap data describing which pixels of _s_o_u_r_c_e are to be drawn and which
     are to be considered transparent.  _W_i_d_t_h and _h_e_i_g_h_t give the dimensions
     of the cursor, _x_H_o_t and _y_H_o_t indicate the location of the cursor's hot-
     spot (the point that is reported when an event occurs), and _f_g and _b_g
     describe the cursor's foreground and background colors textually (any of
     the forms suitable for TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr may be used).  Typically, the



                                                                        PPPPaaaaggggeeee 2222






TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))



     arguments to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa are created by including a cursor file
     directly into the source code for a program, as in the following example:
          Cursor cursor;
          #include "source.cursor"
          #include "mask.cursor"
          cursor = Tk_GetCursorFromData(interp, tkwin, source_bits,
                          mask_bits, source_width, source_height, source_x_hot,
                          source_y_hot, Tk_GetUid("red"), Tk_GetUid("blue"));

     Under normal conditions, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa will
     return an identifier for the requested cursor.  If an error occurs in
     creating the cursor, such as when _n_a_m_e_I_d refers to a non-existent file,
     then NNNNoooonnnneeee is returned and an error message will be stored in _i_n_t_e_r_p-
     >_r_e_s_u_l_t.

     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa maintain a database of all the
     cursors they have created.  Whenever possible, a call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or
     TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa will return an existing cursor rather than creating
     a new one.  This approach can substantially reduce server overhead, so
     the Tk procedures should generally be used in preference to Xlib
     procedures like XXXXCCCCrrrreeeeaaaatttteeeeFFFFoooonnnnttttCCCCuuuurrrrssssoooorrrr or XXXXCCCCrrrreeeeaaaatttteeeePPPPiiiixxxxmmmmaaaappppCCCCuuuurrrrssssoooorrrr, which create a
     new cursor on each call.

     The procedure TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr is roughly the inverse of TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr.  If
     its _c_u_r_s_o_r argument was created by TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr, then the return value is
     the _n_a_m_e_I_d argument that was passed to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr to create the cursor.
     If _c_u_r_s_o_r was created by a call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa, or by any other
     mechanism, then the return value is a hexadecimal string giving the X
     identifier for the cursor.  Note:  the string returned by TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr
     is only guaranteed to persist until the next call to TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCuuuurrrrssssoooorrrr.

     When a cursor returned by TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr or TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa is no
     longer needed, TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr should be called to release it.  There
     should be exactly one call to TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr for each call to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr
     or TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa.  When a cursor is no longer in use anywhere
     (i.e. it has been freed as many times as it has been gotten)
     TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr will release it to the X server and remove it from the
     database.


BBBBUUUUGGGGSSSS
     In determining whether an existing cursor can be used to satisfy a new
     request, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr and TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa consider only the
     immediate values of their arguments.  For example, when a file name is
     passed to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr will assume it is safe to re-use an
     existing cursor created from the same file name:  it will not check to
     see whether the file itself has changed, or whether the current directory
     has changed, thereby causing the name to refer to a different file.
     Similarly, TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrrFFFFrrrroooommmmDDDDaaaattttaaaa assumes that if the same _s_o_u_r_c_e pointer
     is used in two different calls, then the pointers refer to the same data;
     it does not check to see if the actual data values have changed.




                                                                        PPPPaaaaggggeeee 3333






TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))                                            TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr((((3333TTTTkkkk))))



KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
     cursor





















































                                                                        PPPPaaaaggggeeee 4444