


XmbTextPerCharExtents(3X11)			  XmbTextPerCharExtents(3X11)
X11R5									X11R5



NAME
  XmbTextPerCharExtents, XwcTextPerCharExtents - obtain	per-character infor-
  mation for a text string

SYNTAX
  Status XmbTextPerCharExtents(_f_o_n_t__s_e_t, _s_t_r_i_n_g, _n_u_m__b_y_t_e_s, _i_n_k__a_r_r_a_y__r_e_t_u_r_n,
	     _l_o_g_i_c_a_l__a_r_r_a_y__r_e_t_u_r_n, _a_r_r_a_y__s_i_z_e, _n_u_m__c_h_a_r_s__r_e_t_u_r_n,
  _o_v_e_r_a_l_l__r_e_t_u_r_n)
	XFontSet _f_o_n_t__s_e_t;
	char *_s_t_r_i_n_g;
	int _n_u_m__b_y_t_e_s;
	XRectangle *_i_n_k__a_r_r_a_y__r_e_t_u_r_n;
	XRectangle *_l_o_g_i_c_a_l__a_r_r_a_y__r_e_t_u_r_n;
	int _a_r_r_a_y__s_i_z_e;
	int *_n_u_m__c_h_a_r_s__r_e_t_u_r_n;
	XRectangle *_o_v_e_r_a_l_l__i_n_k__r_e_t_u_r_n;
	XRectangle *_o_v_e_r_a_l_l__l_o_g_i_c_a_l__r_e_t_u_r_n;

  Status XwcTextPerCharExtents(_f_o_n_t__s_e_t, _s_t_r_i_n_g, _n_u_m__w_c_h_a_r_s,
  _i_n_k__a_r_r_a_y__r_e_t_u_r_n,
	    _l_o_g_i_c_a_l__a_r_r_a_y__r_e_t_u_r_n, _a_r_r_a_y__s_i_z_e, _n_u_m__c_h_a_r_s__r_e_t_u_r_n,
  _o_v_e_r_a_l_l__r_e_t_u_r_n)
	XFontSet _f_o_n_t__s_e_t;
	wchar_t	*_s_t_r_i_n_g;
	int _n_u_m__w_c_h_a_r_s;
	XRectangle *_i_n_k__a_r_r_a_y__r_e_t_u_r_n;
	XRectangle *_l_o_g_i_c_a_l__a_r_r_a_y__r_e_t_u_r_n;
	int _a_r_r_a_y__s_i_z_e;
	int *_n_u_m__c_h_a_r_s__r_e_t_u_r_n;
	XRectangle *_o_v_e_r_a_l_l__i_n_k__r_e_t_u_r_n;
	XRectangle *_o_v_e_r_a_l_l__l_o_g_i_c_a_l__r_e_t_u_r_n;

ARGUMENTS

  _a_r_r_a_y__s_i_z_e
	    Specifies the size of ink_array_return and logical_array_return.
	    Note that the caller must pass in arrays of	this size.

  _f_o_n_t__s_e_t  Specifies the font set.

  _i_n_k__a_r_r_a_y__r_e_t_u_r_n
	    Returns the	ink dimensions for each	character.

  _l_o_g_i_c_a_l__a_r_r_a_y__r_e_t_u_r_n
	    Returns the	logical	dimensions for each character.

  _n_u_m__b_y_t_e_s Specifies the number of bytes in the string	argument.

  _n_u_m__c_h_a_r_s__r_e_t_u_r_n
	    Returns the	number characters in the string	argument.

  _n_u_m__w_c_h_a_r_s
	    Specifies the number of characters in the string argument.

  _o_v_e_r_a_l_l__i_n_k__r_e_t_u_r_n
	    Returns the	overall	ink extents of the entire string.

  _o_v_e_r_a_l_l__l_o_g_i_c_a_l__r_e_t_u_r_n
	    Returns the	overall	logical	extents	of the entire string.

  _s_t_r_i_n_g    Specifies the character string.

DESCRIPTION
  The _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s and	_X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s return the text dimen-
  sions	of each	character of the specified text, using the fonts loaded	for
  the specified	font set.  Each	successive element of ink_array_return and
  logical_array_return is set to the successive	character's drawn metrics,
  relative to the drawing origin of the	string,	one _X_R_e_c_t_a_n_g_l_e for each	char-
  acter	in the supplied	text string.  The number of elements of
  ink_array_return and logical_array_return that have been set is returned to
  num_chars_return.

  Each element of ink_array_return is set to the bounding box of the
  corresponding	character's drawn foreground color.  Each element of
  logical_array_return is set to the bounding box which	provides minimum
  spacing to other graphical features for the corresponding character.	Other
  graphical features should not	intersect any of the logical_array_return
  rectangles.

  Note that an _X_R_e_c_t_a_n_g_l_e represents the effective drawing dimensions of the
  character, regardless	of the number of font glyphs that are used to draw
  the character, or the	direction in which the character is drawn.  If multi-
  ple characters map to	a single character glyph, the dimensions of all	the
  _X_R_e_c_t_a_n_g_l_e_s of those characters are the same.

  When the _X_F_o_n_t_S_e_t has	missing	charsets, metrics for each unavailable char-
  acter	are taken from the default string returned by _X_C_r_e_a_t_e_F_o_n_t_S_e_t, so that
  the metrics represent	the text as it will actually be	drawn.	The behavior
  for an invalid codepoint is undefined.

  If the array_size is too small for the number	of characters in the supplied
  text,	the functions return zero and num_chars_return is set to the number
  of rectangles	required.  Otherwise, the routines return a non-zero value.

  If the overall_ink_return or overall_logical_return argument is non-NULL,
  _X_m_b_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s	and _X_w_c_T_e_x_t_P_e_r_C_h_a_r_E_x_t_e_n_t_s return the maximum extent
  of the string's metrics to overall_ink_return	or overall_logical_return, as
  returned by _X_m_b_T_e_x_t_E_x_t_e_n_t_s or	_X_w_c_T_e_x_t_E_x_t_e_n_t_s.

SEE ALSO
  XmbTextEscapement(3X11), XmbTextExtents(3X11)	_X_l_i_b - _C _L_a_n_g_u_a_g_e _X _I_n_t_e_r_f_a_c_e























