Skunkware 5

home *** CD-ROM | disk | FTP | other *** search

/ Skunkware 5 / Skunkware 5.iso / man / cat.3 / ConfigWidg.3 < prev next >

Wrap

Text File | 1995-07-26 | 56.5 KB | 858 lines

TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) _________________________________________________________________ NNNNAAAAMMMMEEEE Tk_ConfigureWidget, Tk_Offset, Tk_ConfigureInfo, Tk_FreeOptions - process configuration options for widgets SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS ####iiiinnnncccclllluuuuddddeeee <<<<ttttkkkk....hhhh>>>> int TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((_i_n_t_e_r_p, _t_k_w_i_n, _s_p_e_c_s, _a_r_g_c, _a_r_g_v, _w_i_d_g_R_e_c, _f_l_a_g_s)))) int TTTTkkkk____OOOOffffffffsssseeeetttt((((_t_y_p_e, _f_i_e_l_d)))) int TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo((((_i_n_t_e_r_p, _t_k_w_i_n, _s_p_e_c_s, _w_i_d_g_R_e_c, _a_r_g_v_N_a_m_e, _f_l_a_g_s)))) TTTTkkkk____FFFFrrrreeeeeeeeOOOOppppttttiiiioooonnnnssss((((_s_p_e_c_s, _w_i_d_g_R_e_c, _d_i_s_p_l_a_y, _f_l_a_g_s)))) | AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for returning error messages. Tk_Window _t_k_w_i_n (in) Window used to represent widget (needed to set up X resources). Tk_ConfigSpec *_s_p_e_c_s (in) Pointer to table specifying legal configuration options for this widget. int _a_r_g_c (in) Number of arguments in _a_r_g_v. char **_a_r_g_v (in) Command-line options for configuring widget. char *_w_i_d_g_R_e_c (in/out) Points to widget record structure. Fields in this structure get modified by TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt to hold configuration information. int _f_l_a_g_s (in) If non-zero, then it specifies an OR-ed combination of flags Page 1 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) that control the processing of configuration information. TK_CONFIG_ARGV_ONLY causes the option database and defaults to be ignored, and flag bits TK_CONFIG_USER_BIT and higher are used to selectively disable entries in _s_p_e_c_s. type name _t_y_p_e (in) The name of the type of a widget record. field name _f_i_e_l_d (in) The name of a field in records of type _t_y_p_e. char *_a_r_g_v_N_a_m_e (in) The name used on Tcl command lines to refer to a particular option (e.g. when creating a widget or invoking the ccccoooonnnnffffiiiigggguuuurrrreeee widget command). If non-NULL, then information is returned only for this option. If NULL, then information is returned for all available options. Display *_d_i_s_p_l_a_y (in) Display containing widget whose record is being freed; needed in order to free up resources. _________________________________________________________________ DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt is called to configure various aspects of a widget, such as colors, fonts, border width, etc. It is intended as a convenience procedure to reduce the amount of code that must be written in individual widget managers to handle configuration information. It is typically invoked when widgets are created, and again when the ccccoooonnnnffffiiiigggguuuurrrreeee command is invoked for a widget. Although intended primarily for widgets, TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt can be used in other situations where _a_r_g_c-_a_r_g_v information is to be used to fill in a record structure, such as configuring graphical elements for a canvas widget or entries of a menu. Page 2 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt processes a table specifying the configuration options that are supported (_s_p_e_c_s) and a collection of command-line arguments (_a_r_g_c and _a_r_g_v) to fill in fields of a record (_w_i_d_g_R_e_c). It uses the option database and defaults specified in _s_p_e_c_s to fill in fields of _w_i_d_g_R_e_c that are not specified in _a_r_g_v. TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt normally returns the value TCL_OK; in this case it does not modify _i_n_t_e_r_p. If an error occurs then TCL_ERROR is returned and TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt will leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t in the standard Tcl fashion. In the event of an error return, some of the fields of _w_i_d_g_R_e_c could already have been set, if configuration information for them was successfully processed before the error occurred. The other fields will | be set to reasonable initial values so that TTTTkkkk____FFFFrrrreeeeeeeeOOOOppppttttiiiioooonnnnssss | can be called for cleanup. The _s_p_e_c_s array specifies the kinds of configuration options expected by the widget. Each of its entries specifies one configuration option and has the following structure: typedef struct { int _t_y_p_e; char *_a_r_g_v_N_a_m_e; char *_d_b_N_a_m_e; char *_d_b_C_l_a_s_s; char *_d_e_f_V_a_l_u_e; int _o_f_f_s_e_t; int _s_p_e_c_F_l_a_g_s; Tk_CustomOption *_c_u_s_t_o_m_P_t_r; | } Tk_ConfigSpec; The _t_y_p_e field indicates what type of configuration option this is (e.g. TK_CONFIG_COLOR for a color value, or TK_CONFIG_INT for an integer value). The _t_y_p_e field indicates how to use the value of the option (more on this below). The _a_r_g_v_N_a_m_e field is a string such as ``-font'' or ``-bg'', which is compared with the values in _a_r_g_v (if _a_r_g_v_N_a_m_e is NULL it means this is a grouped entry; see GROUPED ENTRIES below). The _d_b_N_a_m_e and _d_b_C_l_a_s_s fields are used to look up a value for this option in the option database. The _d_e_f_V_a_l_u_e field specifies a default value for this configuration option if no value is specified in either _a_r_g_v or the option database. _O_f_f_s_e_t indicates where in _w_i_d_g_R_e_c to store information about this option, and _s_p_e_c_F_l_a_g_s contains additional information to control the processing of this configuration option (see FLAGS below). The last field, _c_u_s_t_o_m_P_t_r, is only used if _t_y_p_e is TK_CONFIG_CUSTOM; see CUSTOM OPTION TYPES below. TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt first processes _a_r_g_v to see which (if any) configuration options are specified there. _A_r_g_v must Page 3 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) contain an even number of fields; the first of each pair of fields must match the _a_r_g_v_N_a_m_e of some entry in _s_p_e_c_s (unique abbreviations are acceptable), and the second field of the pair contains the value for that configuration option. If there are entries in _s_p_e_c for which there were no matching entries in _a_r_g_v, TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt uses the _d_b_N_a_m_e and _d_b_C_l_a_s_s fields of the _s_p_e_c_s entry to probe the option database; if a value is found, then it is used as the value for the option. Finally, if no entry is found in the option database, the _d_e_f_V_a_l_u_e field of the _s_p_e_c_s entry is used as the value for the configuration option. If the _d_e_f_V_a_l_u_e is NULL, or if the TK_CONFIG_DONT_SET_DEFAULT bit is set in _f_l_a_g_s, then there is no default value and this _s_p_e_c_s entry will be ignored if no value is specified in _a_r_g_v or the option database. Once a string value has been determined for a configuration option, TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt translates the string value into a more useful form, such as a color if _t_y_p_e is TK_CONFIG_COLOR or an integer if _t_y_p_e is TK_CONFIG_INT. This value is then stored in the record pointed to by _w_i_d_g_R_e_c. This record is assumed to contain information relevant to the manager of the widget; its exact type is unknown to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. The _o_f_f_s_e_t field of each _s_p_e_c_s entry indicates where in _w_i_d_g_R_e_c to store the information about this configuration option. You should use the TTTTkkkk____OOOOffffffffsssseeeetttt macro to generate _o_f_f_s_e_t values (see below for a description of TTTTkkkk____OOOOffffffffsssseeeetttt). The location indicated by _w_i_d_g_R_e_c and _o_f_f_s_e_t will be referred to as the ``target'' in the descriptions below. The _t_y_p_e field of each entry in _s_p_e_c_s determines what to do with the string value of that configuration option. The legal values for _t_y_p_e, and the corresponding actions, are: TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____AAAACCCCTTTTIIIIVVVVEEEE____CCCCUUUURRRRSSSSOOOORRRR The value must be an ASCII string identifying a cursor | in a form suitable for passing to TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr. The | value is converted to a CCCCuuuurrrrssssoooorrrr by calling TTTTkkkk____GGGGeeeettttCCCCuuuurrrrssssoooorrrr | and the result is stored in the target. In addition, | the resulting cursor is made the active cursor for | _t_k_w_i_n by calling XXXXDDDDeeeeffffiiiinnnneeeeCCCCuuuurrrrssssoooorrrr. If TK_CONFIG_NULL_OK | is specified in _s_p_e_c_F_l_a_g_s then the value may be an | empty string, in which case the target and _t_k_w_i_n's | active cursor will be set to NNNNoooonnnneeee. If the previous | value of the target wasn't NNNNoooonnnneeee, then it is freed by | passing it to TTTTkkkk____FFFFrrrreeeeeeeeCCCCuuuurrrrssssoooorrrr. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____AAAANNNNCCCCHHHHOOOORRRR || The value must be an ASCII string identifying an anchor | point in one of the ways accepted by TTTTkkkk____GGGGeeeettttAAAAnnnncccchhhhoooorrrr. The | string is converted to a TTTTkkkk____AAAAnnnncccchhhhoooorrrr by calling | Page 4 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk____GGGGeeeettttAAAAnnnncccchhhhoooorrrr and the result is stored in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____BBBBIIIITTTTMMMMAAAAPPPP The value must be an ASCII string identifying a bitmap in a form suitable for passing to TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp. The value is converted to a PPPPiiiixxxxmmmmaaaapppp by calling TTTTkkkk____GGGGeeeettttBBBBiiiittttmmmmaaaapppp and the result is stored in the target. If | TK_CONFIG_NULL_OK is specified in _s_p_e_c_F_l_a_g_s then the | value may be an empty string, in which case the target | is set to NNNNoooonnnneeee. If the previous value of the target wasn't NNNNoooonnnneeee, then it is freed by passing it to TTTTkkkk____FFFFrrrreeeeeeeeBBBBiiiittttmmmmaaaapppp. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____BBBBOOOOOOOOLLLLEEEEAAAANNNN The value must be an ASCII string specifying a boolean value. Any of the values ``true'', ``yes'', ``on'', or ``1'', or an abbreviation of one of these values, means true; any of the values ``false'', ``no'', ``off'', or ``0'', or an abbreviation of one of these values, means false. The target is expected to be an integer; for true values it will be set to 1 and for false values it will be set to 0. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____BBBBOOOORRRRDDDDEEEERRRR The value must be an ASCII string identifying a border color in a form suitable for passing to TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr. The value is converted to a (TTTTkkkk____3333DDDDBBBBoooorrrrddddeeeerrrr ****) by calling TTTTkkkk____GGGGeeeetttt3333DDDDBBBBoooorrrrddddeeeerrrr and the result is stored in the target. | If TK_CONFIG_NULL_OK is specified in _s_p_e_c_F_l_a_g_s then the | value may be an empty string, in which case the target | will be set to NULL. If the previous value of the target wasn't NULL, then it is freed by passing it to TTTTkkkk____FFFFrrrreeeeeeee3333DDDDBBBBoooorrrrddddeeeerrrr. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____CCCCAAAAPPPP____SSSSTTTTYYYYLLLLEEEE The value must be an ASCII string identifying a cap | style in one of the ways accepted by TTTTkkkk____GGGGeeeettttCCCCaaaappppSSSSttttyyyylllleeee. | The string is converted to an integer value | corresponding to the cap style by calling | TTTTkkkk____GGGGeeeettttCCCCaaaappppSSSSttttyyyylllleeee and the result is stored in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____CCCCOOOOLLLLOOOORRRR The value must be an ASCII string identifying a color in a form suitable for passing to TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr. The value is converted to an (XXXXCCCCoooolllloooorrrr ****) by calling TTTTkkkk____GGGGeeeettttCCCCoooolllloooorrrr and the result is stored in the target. If | TK_CONFIG_NULL_OK is specified in _s_p_e_c_F_l_a_g_s then the | value may be an empty string, in which case the target | will be set to NNNNoooonnnneeee. If the previous value of the target wasn't NULL, then it is freed by passing it to TTTTkkkk____FFFFrrrreeeeeeeeCCCCoooolllloooorrrr. Page 5 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____CCCCUUUURRRRSSSSOOOORRRR This option is identical to TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____AAAACCCCTTTTIIIIVVVVEEEE____CCCCUUUURRRRSSSSOOOORRRR except that the new cursor is not made the active one for _t_k_w_i_n. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____CCCCUUUUSSSSTTTTOOOOMMMM This option allows applications to define new option | types. The _c_u_s_t_o_m_P_t_r field of the entry points to a | structure defining the new option type. See the | section CUSTOM OPTION TYPES below for details. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____DDDDOOOOUUUUBBBBLLLLEEEE The value must be an ASCII floating-point number in the format accepted by ssssttttrrrrttttoooollll. The string is converted to a ddddoooouuuubbbblllleeee value, and the value is stored in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____EEEENNNNDDDD Marks the end of the table. The last entry in _s_p_e_c_s must have this type; all of its other fields are ignored and it will never match any arguments. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____FFFFOOOONNNNTTTT The value must be an ASCII string identifying a font in a form suitable for passing to TTTTkkkk____GGGGeeeettttFFFFoooonnnnttttSSSSttttrrrruuuucccctttt. The value is converted to an (XXXXFFFFoooonnnnttttSSSSttttrrrruuuucccctttt ****) by calling TTTTkkkk____GGGGeeeettttFFFFoooonnnnttttSSSSttttrrrruuuucccctttt and the result is stored in the target. If TK_CONFIG_NULL_OK is specified in _s_p_e_c_F_l_a_g_s | then the value may be an empty string, in which case | the target will be set to NULL. If the previous value of the target wasn't NULL, then it is freed by passing it to TTTTkkkk____FFFFrrrreeeeeeeeFFFFoooonnnnttttSSSSttttrrrruuuucccctttt. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____IIIINNNNTTTT The value must be an ASCII integer string in the format accepted by ssssttttrrrrttttoooollll (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). The string is converted to an integer value and the integer is stored in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____JJJJOOOOIIIINNNN____SSSSTTTTYYYYLLLLEEEE The value must be an ASCII string identifying a join | style in one of the ways accepted by TTTTkkkk____GGGGeeeettttJJJJooooiiiinnnnSSSSttttyyyylllleeee. | The string is converted to an integer value | corresponding to the join style by calling | TTTTkkkk____GGGGeeeettttJJJJooooiiiinnnnSSSSttttyyyylllleeee and the result is stored in the target. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____JJJJUUUUSSSSTTTTIIIIFFFFYYYY || The value must be an ASCII string identifying a | justification method in one of the ways accepted by | TTTTkkkk____GGGGeeeettttJJJJuuuussssttttiiiiffffyyyy. The string is converted to a TTTTkkkk____JJJJuuuussssttttiiiiffffyyyy | by calling TTTTkkkk____GGGGeeeettttJJJJuuuussssttttiiiiffffyyyy and the result is stored in | the target. | Page 6 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____MMMMMMMM || The value must specify a screen distance in one of the | forms acceptable to TTTTkkkk____GGGGeeeettttSSSSccccrrrreeeeeeeennnnMMMMMMMM. The string is | converted to double-precision floating-point distance | in millimeters and the value is stored in the target. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____PPPPIIIIXXXXEEEELLLLSSSS || The value must specify screen units in one of the forms | acceptable to TTTTkkkk____GGGGeeeettttPPPPiiiixxxxeeeellllssss. The string is converted to | an integer distance in pixels and the value is stored | in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____RRRREEEELLLLIIIIEEEEFFFF The value must be an ASCII string identifying a relief in a form suitable for passing to TTTTkkkk____GGGGeeeettttRRRReeeelllliiiieeeeffff. The value is converted to an integer relief value by calling TTTTkkkk____GGGGeeeettttRRRReeeelllliiiieeeeffff and the result is stored in the target. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____SSSSTTTTRRRRIIIINNNNGGGG A copy of the value is made by allocating memory space | with mmmmaaaalllllllloooocccc and copying the value into the | dynamically-allocated space. A pointer to the new | string is stored in the target. If TK_CONFIG_NULL_OK | is specified in _s_p_e_c_F_l_a_g_s then the value may be an | empty string, in which case the target will be set to | NULL. If the previous value of the target wasn't NULL, | then it is freed by passing it to ffffrrrreeeeeeee. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____SSSSYYYYNNNNOOOONNNNYYYYMMMM This _t_y_p_e value identifies special entries in _s_p_e_c_s that are synonyms for other entries. If an _a_r_g_v value matches the _a_r_g_v_N_a_m_e of a TK_CONFIG_SYNONYM entry, the entry isn't used directly. Instead, TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt searches _s_p_e_c_s for another entry whose _a_r_g_v_N_a_m_e is the same as the _d_b_N_a_m_e field in the TK_CONFIG_SYNONYM entry; this new entry is used just as if its _a_r_g_v_N_a_m_e had matched the _a_r_g_v value. The synonym mechanism allows multiple _a_r_g_v values to be used for a single configuration option, such as ``-background'' and ``-bg''. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____UUUUIIIIDDDD The value is translated to a TTTTkkkk____UUUUiiiidddd (by passing it to TTTTkkkk____GGGGeeeettttUUUUiiiidddd). The resulting value is stored in the target. If TK_CONFIG_NULL_OK is specified in _s_p_e_c_F_l_a_g_s | and the value is an empty string then the target will | be set to NULL. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____WWWWIIIINNNNDDDDOOOOWWWW || The value must be a window path name. It is translated | to a TTTTkkkk____WWWWiiiinnnnddddoooowwww token and the token is stored in the | Page 7 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) target. GGGGRRRROOOOUUUUPPPPEEEEDDDD EEEENNNNTTTTRRRRIIIIEEEESSSS In some cases it is useful to generate multiple resources from a single configuration value. For example, a color name might be used both to generate the background color for a widget (using TK_CONFIG_COLOR) and to generate a 3-D border to draw around the widget (using TK_CONFIG_BORDER). In cases like this it is possible to specify that several consecutive entries in _s_p_e_c_s are to be treated as a group. The first entry is used to determine a value (using its _a_r_g_v_N_a_m_e, _d_b_N_a_m_e, _d_b_C_l_a_s_s, and _d_e_f_V_a_l_u_e fields). The value will be processed several times (one for each entry in the group), generating multiple different resources and modifying multiple targets within _w_i_d_g_R_e_c. Each of the entries after the first must have a NULL value in its _a_r_g_v_N_a_m_e field; this indicates that the entry is to be grouped with the entry that precedes it. Only the _t_y_p_e and _o_f_f_s_e_t fields are used from these follow-on entries. FFFFLLLLAAAAGGGGSSSS The _f_l_a_g_s argument passed to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt is used in conjunction with the _s_p_e_c_F_l_a_g_s fields in the entries of _s_p_e_c_s to provide additional control over the processing of configuration options. These values are used in three different ways as described below. First, if the _f_l_a_g_s argument to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt has the TK_CONFIG_ARGV_ONLY bit set (i.e., _f_l_a_g_s | TK_CONFIG_ARGV_ONLY != 0), then the option database and _d_e_f_V_a_l_u_e fields are not used. In this case, if an entry in _s_p_e_c_s doesn't match a field in _a_r_g_v then nothing happens: the corresponding target isn't modified. This feature is useful when the goal is to modify certain configuration options while leaving others in their current state, such as when a ccccoooonnnnffffiiiigggguuuurrrreeee widget command is being processed. Second, the _s_p_e_c_F_l_a_g_s field of an entry in _s_p_e_c_s may be used | to control the processing of that entry. Each _s_p_e_c_F_l_a_g_s | field may consists of an OR-ed combination of the following | values: | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____CCCCOOOOLLLLOOOORRRR____OOOONNNNLLLLYYYY || If this bit is set then the entry will only be | considered if the display for _t_k_w_i_n has more than one | bit plane. If the display is monochromatic then this | _s_p_e_c_s entry will be ignored. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____MMMMOOOONNNNOOOO____OOOONNNNLLLLYYYY || If this bit is set then the entry will only be | Page 8 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) considered if the display for _t_k_w_i_n has exactly one bit | plane. If the display is not monochromatic then this | _s_p_e_c_s entry will be ignored. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____NNNNUUUULLLLLLLL____OOOOKKKK || This bit is only relevant for some types of entries | (see the descriptions of the various entry types | above). If this bit is set, it indicates that an empty | string value for the field is acceptable and if it | occurs then the target should be set to NULL or NNNNoooonnnneeee, | depending on the type of the target. This flag is | typically used to allow a feature to be turned off | entirely, e.g. set a cursor value to NNNNoooonnnneeee so that a | window simply inherits its parent's cursor. If this | bit isn't set then empty strings are processed as | strings, which generally results in an error. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____DDDDOOOONNNNTTTT____SSSSEEEETTTT____DDDDEEEEFFFFAAAAUUUULLLLTTTT || If this bit is one, it means that the _d_e_f_V_a_l_u_e field of | the entry should only be used for returning the default | value in TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo. In calls to | TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt no default will be supplied for | entries with this flag set; it is assumed that the | caller has already supplied a default value in the | target location. This flag provides a performance | optimization where it is expensive to process the | default string: the client can compute the default | once, save the value, and provide it before calling | TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. | TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGG____OOOOPPPPTTTTIIIIOOOONNNN____SSSSPPPPEEEECCCCIIIIFFFFIIIIEEEEDDDD || This bit is set and cleared by TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. | Whenever TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt returns, this bit will be | set in all the entries where a value was specified in | _a_r_g_v. It will be zero in all other entries. This bit | provides a way for clients to determine which values | actually changed in a call to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. The TK_CONFIG_MONO_ONLY and TK_CONFIG_COLOR_ONLY flags are typically used to specify different default values for monochrome and color displays. This is done by creating two entries in _s_p_e_c_s that are identical except for their _d_e_f_V_a_l_u_e and _s_p_e_c_F_l_a_g_s fields. One entry should have the value TK_CONFIG_MONO_ONLY in its _s_p_e_c_F_l_a_g_s and the default value for monochrome displays in its _d_e_f_V_a_l_u_e; the other entry entry should have the value TK_CONFIG_COLOR_ONLY in its _s_p_e_c_F_l_a_g_s and the appropriate _d_e_f_V_a_l_u_e for color displays. Third, it is possible to use _f_l_a_g_s and _s_p_e_c_F_l_a_g_s together to selectively disable some entries. This feature is not needed very often. It is useful in cases where several Page 9 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) similar kinds of widgets are implemented in one place. It allows a single _s_p_e_c_s table to be created with all the configuration options for all the widget types. When processing a particular widget type, only entries relevant to that type will be used. This effect is achieved by setting the high-order bits (those in positions equal to or greater than TK_CONFIG_USER_BIT) in _s_p_e_c_F_l_a_g_s values or in _f_l_a_g_s. In order for a particular entry in _s_p_e_c_s to be used, its high-order bits must match exactly the high-order bits of the _f_l_a_g_s value passed to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. If a _s_p_e_c_s table is being used for N different widget types, then N of the high-order bits will be used. Each _s_p_e_c_s entry will have one of more of those bits set in its _s_p_e_c_F_l_a_g_s field to indicate the widget types for which this entry is valid. When calling TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt, _f_l_a_g_s will have a single one of these bits set to select the entries for the desired widget type. For a working example of this feature, see the code in tkButton.c. TTTTKKKK____OOOOFFFFFFFFSSSSEEEETTTT The TTTTkkkk____OOOOffffffffsssseeeetttt macro is provided as a safe way of generating the _o_f_f_s_e_t values for entries in Tk_ConfigSpec structures. It takes two arguments: the name of a type of record, and the name of a field in that record. It returns the byte offset of the named field in records of the given type. TTTTKKKK____CCCCOOOONNNNFFFFIIIIGGGGUUUURRRREEEEIIIINNNNFFFFOOOO The TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo procedure may be used to obtain information about one or all of the options for a given widget. Given a token for a window (_t_k_w_i_n), a table describing the configuration options for a class of widgets (_s_p_e_c_s), a pointer to a widget record containing the current information for a widget (_w_i_d_g_R_e_c), and a NULL _a_r_g_v_N_a_m_e argument, TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo generates a string describing all of the configuration options for the window. The string is placed in _i_n_t_e_r_p->_r_e_s_u_l_t. Under normal circumstances it returns TCL_OK; if an error occurs then it returns TCL_ERROR and _i_n_t_e_r_p->_r_e_s_u_l_t contains an error message. If _a_r_g_v_N_a_m_e is NULL, then the value left in _i_n_t_e_r_p->_r_e_s_u_l_t by TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo consists of a list of one or more entries, each of which describes one configuration option (i.e. one entry in _s_p_e_c_s). Each entry in the list will contain either two or five values. If the corresponding entry in _s_p_e_c_s has type TK_CONFIG_SYNONYM, then the list will contain two values: the _a_r_g_v_N_a_m_e for the entry and the _d_b_N_a_m_e (synonym name). Otherwise the list will contain five values: _a_r_g_v_N_a_m_e, _d_b_N_a_m_e, _d_b_C_l_a_s_s, _d_e_f_V_a_l_u_e, and current value. The current value is computed from the appropriate field of _w_i_d_g_R_e_c by calling procedures like TTTTkkkk____NNNNaaaammmmeeeeOOOOffffCCCCoooolllloooorrrr. Page 10 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) If the _a_r_g_v_N_a_m_e argument to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo is non-NULL, then it indicates a single option, and information is returned only for that option. The string placed in _i_n_t_e_r_p->_r_e_s_u_l_t will be a list containing two or five values as described above; this will be identical to the corresponding sublist that would have been returned if _a_r_g_v_N_a_m_e had been NULL. The _f_l_a_g_s argument to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo is used to restrict the _s_p_e_c_s entries to consider, just as for TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. TTTTKKKK____FFFFRRRREEEEEEEEOOOOPPPPTTTTIIIIOOOONNNNSSSS The TTTTkkkk____FFFFrrrreeeeeeeeOOOOppppttttiiiioooonnnnssss procedure may be invoked during widget | cleanup to release all of the resources associated with | configuration options. It scans through _s_p_e_c_s and for each | entry corresponding to a resource that must be explicitly | freed (e.g. those with type TK_CONFIG_COLOR), it frees the | resource in the widget record. If the field in the widget | record doesn't refer to a resource (e.g. it contains a null | pointer) then no resource is freed for that entry. After | freeing a resource, TTTTkkkk____FFFFrrrreeeeeeeeOOOOppppttttiiiioooonnnnssss sets the corresponding | field of the widget record to null. CCCCUUUUSSSSTTTTOOOOMMMM OOOOPPPPTTTTIIIIOOOONNNN TTTTYYYYPPPPEEEESSSS Applications can extend the built-in configuration types | with additional configuration types by writing procedures to | parse and print options of the a type and creating a | structure pointing to those procedures: | typedef struct Tk_CustomOption { | Tk_OptionParseProc *_p_a_r_s_e_P_r_o_c; | Tk_OptionPrintProc *_p_r_i_n_t_P_r_o_c; | ClientData _c_l_i_e_n_t_D_a_t_a; | } Tk_CustomOption; | typedef int Tk_OptionParseProc( | ClientData _c_l_i_e_n_t_D_a_t_a, | Tcl_Interp *_i_n_t_e_r_p, | Tk_Window _t_k_w_i_n, | char *_v_a_l_u_e, | char *_w_i_d_g_R_e_c, | int _o_f_f_s_e_t); | typedef char *Tk_OptionPrintProc( | ClientData _c_l_i_e_n_t_D_a_t_a, | Tk_Window _t_k_w_i_n, | char *_w_i_d_g_R_e_c, | int _o_f_f_s_e_t, | Tcl_FreeProc **_f_r_e_e_P_r_o_c_P_t_r); | Page 11 (printed 7/23/95) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) The Tk_CustomOption structure contains three fields, which | are pointers to the two procedures and a _c_l_i_e_n_t_D_a_t_a value to | be passed to those procedures when they are invoked. The | _c_l_i_e_n_t_D_a_t_a value typically points to a structure containing | information that is needed by the procedures when they are | parsing and printing options. | The _p_a_r_s_e_P_r_o_c procedure is invoked by TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt to | parse a string and store the resulting value in the widget | record. The _c_l_i_e_n_t_D_a_t_a argument is a copy of the _c_l_i_e_n_t_D_a_t_a | field in the Tk_CustomOption structure. The _i_n_t_e_r_p argument | points to a Tcl interpreter used for error reporting. _T_k_w_i_n | is a copy of the _t_k_w_i_n argument to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt. The | _v_a_l_u_e argument is a string describing the value for the | option; it could have been specified explicitly in the call | to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt or it could come from the option | database or a default. _V_a_l_u_e will never be a null pointer | but it may point to an empty string. _R_e_c_o_r_d_P_t_r is the same | as the _w_i_d_g_R_e_c argument to TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt; it points to | the start of the widget record to modify. The last | argument, _o_f_f_s_e_t, gives the offset in bytes from the start | of the widget record to the location where the option value | is to be placed. The procedure should translate the string | to whatever form is appropriate for the option and store the | value in the widget record. It should normally return | TCL_OK, but if an error occurs in translating the string to | a value then it should return TCL_ERROR and store an error | message in _i_n_t_e_r_p->_r_e_s_u_l_t. | The _p_r_i_n_t_P_r_o_c procedure is called by TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo to | produce a string value describing an existing option. Its | _c_l_i_e_n_t_D_a_t_a, _t_k_w_i_n, _w_i_d_g_R_e_c, and _o_f_f_s_e_t arguments all have | the same meaning as for Tk_OptionParseProc procedures. The | _p_r_i_n_t_P_r_o_c procedure should examine the option whose value is | stored at _o_f_f_s_e_t in _w_i_d_g_R_e_c, produce a string describing | that option, and return a pointer to the string. If the | string is stored in dynamically-allocated memory, then the | procedure must set *_f_r_e_e_P_r_o_c_P_t_r to the address of a | procedure to call to free the string's memory; | TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeIIIInnnnffffoooo will call this procedure when it is | finished with the string. If the result string is stored in | static memory then _p_r_i_n_t_P_r_o_c need not do anything with the | _f_r_e_e_P_r_o_c_P_t_r argument. | Once _p_a_r_s_e_P_r_o_c and _p_r_i_n_t_P_r_o_c have been defined and a | Tk_CustomOption structure has been created for them, options | of this new type may be manipulated with Tk_ConfigSpec | entries whose _t_y_p_e fields are TK_CONFIG_CUSTOM and whose | _c_u_s_t_o_m_P_t_r fields point to the Tk_CustomOption structure. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS PPPPaaaaggggeeee 11112222 ((((pppprrrriiiinnnntttteeeedddd 7777////22223333////99995555)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) TTTTkkkk ((((3333....3333)))) TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt((((3333)))) Although the explanation of TTTTkkkk____CCCCoooonnnnffffiiiigggguuuurrrreeeeWWWWiiiiddddggggeeeetttt is fairly complicated, its actual use is pretty straightforward. The easiest way to get started is to copy the code from an existing widget. The library implementation of frames (tkFrame.c) has a simple configuration table, and the library implementation of buttons (tkButton.c) has a much more complex table that uses many of the fancy _s_p_e_c_F_l_a_g_s mechanisms. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS anchor, bitmap, boolean, border, cap style, color, configuration options, cursor, custom, double, font, integer, join style, justify, millimeters, pixels, relief, synonym, uid Page 13 (printed 7/23/95)