NAME

XtAllocateGC - obtain a sharable GC with modifiable fields

SYNTAX

GC XtAllocateGC(Widget _w, Cardinal _d_e_p_t_h, XtGCMask _v_a_l_u_e___m_a_s_k, XGCValues *_v_a_l_u_e_s, XtGCMask _d_y_n_a_m_i_c___m_a_s_k, XtGCMask _u_n_u_s_e_d___m_a_s_k);

ARGUMENTS

_v_a_l_u_e_s Specifies the actual values for this GC.
_v_a_l_u_e___m_a_s_k Specifies which fields of the values are specified.
_w Specifies the widget.
_d_e_p_t_h Specifies the depth for which the returned GC is valid, or 0.
_d_y_n_a_m_i_c___m_a_s_k Specifies the fields of the GC that will be modified by the caller.
_u_n_u_s_e_d___m_a_s_k Specifies the fields of the GC that will not be needed by the caller.

DESCRIPTION

The _X_t_A_l_l_o_c_a_t_e_G_C function returns a sharable GC that may be modified by the client. The _s_c_r_e_e_n field of the specified widget or of the nearest widget ancestor of the specified object and the specified _d_e_p_t_h argument supply the root and drawable depths for which the GC is to be valid. If _d_e_p_t_h is zero the depth is taken from the _d_e_p_t_h field of the specified widget or of the nearest widget ancestor of the specified object.

The _v_a_l_u_e___m_a_s_k argument specifies the fields of the GC that will be initialized with the respective members of the _v_a_l_u_e_s structure. The _d_y_n_a_m_i_c___m_a_s_k argument specifies fields that the caller intends to modify during program execution. The caller must ensure that the corresponding GC field is set prior to each use of the GC. The _u_n_u_s_e_d___m_a_s_k argument specifies fields of the GC that are of no interest to the caller. The caller may make no assumptions about the contents of any fields specified in _u_n_u_s_e_d___m_a_s_k. The caller may assume that at all times all fields not specified in either _d_y_n_a_m_i_c___m_a_s_k or _u_n_u_s_e_d___m_a_s_k have their default value if not specified in _v_a_l_u_e___m_a_s_k or the value specified by _v_a_l_u_e_s. If a field is specified in both _v_a_l_u_e___m_a_s_k and _d_y_n_a_m_i_c___m_a_s_k, the effect is as if it were specified only in _d_y_n_a_m_i_c___m_a_s_k and then immediately set to the value in _v_a_l_u_e_s. If a field is set in _u_n_u_s_e_d___m_a_s_k and also in either _v_a_l_u_e___m_a_s_k or _d_y_n_a_m_i_c___m_a_s_k, the specification in _u_n_u_s_e_d___m_a_s_k is ignored.

_X_t_A_l_l_o_c_a_t_e_G_C tries to minimize the number of unique GCs created by comparing the arguments with those of previous calls and returning an existing GC when there are no conflicts. _X_t_A_l_l_o_c_a_t_e_G_C may modify and return an existing GC if it was allocated with a nonzero _u_n_u_s_e_d___m_a_s_k.

SEE ALSO

_X_t_G_e_t_G_C
_X _T_o_o_l_k_i_t _I_n_t_r_i_n_s_i_c_s _- _C _L_a_n_g_u_a_g_e _I_n_t_e_r_f_a_c_e
_X_l_i_b _- _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e