


XtCreateWidget(3Xt)					  XtCreateWidget(3Xt)
X11R5									X11R5



NAME
  XtCreateWidget, XtCreateManagedWidget, XtDestroyWidget - create and destroy
  widgets

SYNTAX
  Widget XtCreateWidget(_n_a_m_e, _w_i_d_g_e_t__c_l_a_s_s, _p_a_r_e_n_t, _a_r_g_s, _n_u_m__a_r_g_s)
	String _n_a_m_e;
	WidgetClass _w_i_d_g_e_t__c_l_a_s_s;
	Widget _p_a_r_e_n_t;
	ArgList	_a_r_g_s;
	Cardinal _n_u_m__a_r_g_s;

  Widget XtCreateManagedWidget(_n_a_m_e, _w_i_d_g_e_t__c_l_a_s_s, _p_a_r_e_n_t, _a_r_g_s, _n_u_m__a_r_g_s)
	String _n_a_m_e;
	WidgetClass _w_i_d_g_e_t__c_l_a_s_s;
	Widget _p_a_r_e_n_t;
	ArgList	_a_r_g_s;
	Cardinal _n_u_m__a_r_g_s;

  void XtDestroyWidget(_w)
	Widget _w;

ARGUMENTS

  _a_r_g_s	    Specifies the argument list	to override the	resource defaults.

  _n_a_m_e	    Specifies the resource name	for the	created	widget,	which is used
	    for	retrieving resources and, for that reason, should not be the
	    same as any	other widget that is a child of	same parent.

  _n_u_m__a_r_g_s  Specifies the number of arguments in the argument list.

  _p_a_r_e_n_t    Specifies the parent widget.

  _w	    Specifies the widget.

  _w_i_d_g_e_t__c_l_a_s_s
	    Specifies the widget class pointer for the created widget.

DESCRIPTION
  The _X_t_C_r_e_a_t_e_W_i_d_g_e_t function performs much of the boilerplate operations of
  widget creation:

  oo++    Checks to see if	the class_initialize procedure has been	called for
       this class and for all superclasses and,	if not,	calls those necessary
       in a superclass-to-subclass order.

  oo++    Allocates memory	for the	widget instance.

  oo++    If the parent is	a subclass of _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s, it	allocates
       memory for the parent's constraints and stores the address of this
       memory into the constraints field.

  oo++    Initializes the core nonresource	data fields (for example, parent and
       visible).

  oo++    Initializes the resource	fields (for example, background_pixel) by
       using the resource lists	specified for this class and all
       superclasses.

  oo++    If the parent is	a subclass of _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s, it	initializes
       the resource fields of the constraints record by	using the constraint
       resource	list specified for the parent's	class and all superclasses up
       to _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s.

  oo++    Calls the initialize procedures for the widget by starting at the _C_o_r_e
       initialize procedure on down to the widget's initialize procedure.

  oo++    If the parent is	a subclass of _c_o_m_p_o_s_i_t_e_W_i_d_g_e_t_C_l_a_s_s, it puts the	wid-
       get into	its parent's children list by calling its parent's
       insert_child procedure.	For further information, see Section 3.5.

  oo++    If the parent is	a subclass of _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s, it	calls the
       constraint initialize procedures, starting at _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s on
       down to the parent's constraint initialize procedure.

  Note that you	can determine the number of arguments in an argument list by
  using	the _X_t_N_u_m_b_e_r macro.  For further information, see Section 11.1.

  The _X_t_C_r_e_a_t_e_M_a_n_a_g_e_d_W_i_d_g_e_t function is	a convenience routine that calls
  _X_t_C_r_e_a_t_e_W_i_d_g_e_t and _X_t_M_a_n_a_g_e_C_h_i_l_d.

  The _X_t_D_e_s_t_r_o_y_W_i_d_g_e_t function provides	the only method	of destroying a	wid-
  get, including widgets that need to destroy themselves.  It can be called
  at any time, including from an application callback routine of the widget
  being	destroyed.  This requires a two-phase destroy process in order to
  avoid	dangling references to destroyed widgets.

  In phase one,	_X_t_D_e_s_t_r_o_y_W_i_d_g_e_t	performs the following:

  oo++    If the being_destroyed field of the widget is _T_r_u_e, it returns immedi-
       ately.

  oo++    Recursively descends the	widget tree and	sets the being_destroyed
       field to	_T_r_u_e for the widget and	all children.

  oo++    Adds the	widget to a list of widgets (the destroy list) that should be
       destroyed when it is safe to do so.

  Entries on the destroy list satisfy the invariant that if w2 occurs after
  w1 on	the destroy list then w2 is not	a descendent of	w1.  (A	descendant
  refers to both normal	and pop-up children.)

  Phase	two occurs when	all procedures that should execute as a	result of the
  current event	have been called (including all	procedures registered with
  the event and	translation managers), that is,	when the current invocation
  of _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t is	about to return	or immediately if not in
  _X_t_D_i_s_p_a_t_c_h_E_v_e_n_t.

  In phase two,	_X_t_D_e_s_t_r_o_y_W_i_d_g_e_t	performs the following on each entry in	the
  destroy list:

  oo++    Calls the destroy callback procedures registered	on the widget (and
       all descendants)	in post-order (it calls	children callbacks before
       parent callbacks).

  oo++    If the widget's parent is a subclass of _c_o_m_p_o_s_i_t_e_W_i_d_g_e_t_C_l_a_s_s and	if
       the parent is not being destroyed, it calls _X_t_U_n_m_a_n_a_g_e_C_h_i_l_d on the
       widget and then calls the widget's parent's delete_child	procedure
       (see Section 3.4).

  oo++    If the widget's parent is a subclass of _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s, it
       calls the constraint destroy procedure for the parent, then the
       parent's	superclass, until finally it calls the constraint destroy
       procedure for _c_o_n_s_t_r_a_i_n_t_W_i_d_g_e_t_C_l_a_s_s.

  oo++    Calls the destroy methods for the widget	(and all descendants) in
       post-order.  For	each such widget, it calls the destroy procedure
       declared	in the widget class, then the destroy procedure	declared in
       its superclass, until finally it	calls the destroy procedure declared
       in the Core class record.

  oo++    Calls _X_D_e_s_t_r_o_y_W_i_n_d_o_w if the widget is realized (that is,	has an X win-
       dow).  The server recursively destroys all descendant windows.

  oo++    Recursively descends the	tree and deallocates all pop-up	widgets, con-
       straint records,	callback lists and, if the widget is a subclass	of
       _c_o_m_p_o_s_i_t_e_W_i_d_g_e_t_C_l_a_s_s, children.

SEE ALSO
  XtAppCreateShell(3Xt), XtCreatePopupShell(3Xt)
  _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	delim off















































