晋太元中，武陵人捕鱼为业。缘溪行，忘路之远近。忽逢桃花林，夹岸数百步，中无杂树，芳草鲜美，落英缤纷。渔人甚异之，复前行，欲穷其林。 　　林尽水源，便得一山，山有小口，仿佛若有光。便舍船，从口入。初极狭，才通人。复行数十步，豁然开朗。土地平旷，屋舍俨然，有良田、美池、桑竹之属。阡陌交通，鸡犬相闻。其中往来种作，男女衣着，悉如外人。黄发垂髫，并怡然自乐。 　　见渔人，乃大惊，问所从来。具答之。便要还家，设酒杀鸡作食。村中闻有此人，咸来问讯。自云先世避秦时乱，率妻子邑人来此绝境，不复出焉，遂与外人间隔。问今是何世，乃不知有汉，无论魏晋。此人一一为具言所闻，皆叹惋。余人各复延至其家，皆出酒食。停数日，辞去。此中人语云：“不足为外人道也。”(间隔 一作：隔绝) 　　既出，得其船，便扶向路，处处志之。及郡下，诣太守，说如此。太守即遣人随其往，寻向所志，遂迷，不复得路。 　　南阳刘子骥，高尚士也，闻之，欣然规往。未果，寻病终。后遂无问津者。 .
Prv8 Shell
Server : Apache
System : Linux srv.rainic.com 4.18.0-553.47.1.el8_10.x86_64 #1 SMP Wed Apr 2 05:45:37 EDT 2025 x86_64
User : rainic ( 1014)
PHP Version : 7.4.33
Disable Function : exec,passthru,shell_exec,system
Directory :  /usr/share/doc/libXt/

Upload File :
current_dir [ Writeable ] document_root [ Writeable ]

 

Current File : //usr/share/doc/libXt/CH08.xml
<chapter id='Callbacks'>
<title>Callbacks</title>
<para>
Applications and other widgets often need to register a procedure
with a widget that gets called under certain prespecified conditions.
For example,
when a widget is destroyed,
every procedure on the widget's <emphasis remap='I'>destroy_callbacks</emphasis>
list is called to notify clients of the widget's impending doom.
</para>

<para>
Every widget has an XtNdestroyCallbacks callback list resource.
Widgets can define additional callback lists as they see fit.
For example, the Pushbutton widget has a callback
list to notify clients when the button has been activated.
</para>

<para>
Except where otherwise noted, it is the intent that all Intrinsics
functions may be called at any time, including from within callback
procedures, action routines, and event handlers.
</para>
<sect1 id="Using_Callback_Procedure_and_Callback_List_Definitions">
<title>Using Callback Procedure and Callback List Definitions</title>
<para>
Callback procedure pointers for use in callback lists are of type
<xref linkend='XtCallbackProc' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCallbackProc'>
<funcprototype>
<funcdef>typedef void <function>(*XtCallbackProc)</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
   <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget owning the list in which the callback is registered.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies additional data supplied by the client when the procedure
was registered.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>call_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies any callback-specific data the widget wants to pass to the client.
For example,  when Scrollbar executes its XtNthumbChanged callback list,
it passes the new position of the thumb.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The <emphasis remap='I'>client_data</emphasis> argument provides a way for the
client registering the callback procedure also to register client-specific data,
for example, a pointer to additional information about the widget,
a reason for invoking the callback, and so on.
The <emphasis remap='I'>client_data</emphasis> value may be NULL
if all necessary information is in the widget.
The <emphasis remap='I'>call_data</emphasis> argument is a convenience to avoid having simple
cases where the client could otherwise always call
<xref linkend='XtGetValues' xrefstyle='select: title'/>
or a widget-specific function to retrieve data from the widget.
Widgets should generally avoid putting complex state information
in <emphasis remap='I'>call_data</emphasis>.
The client can use the more general data retrieval methods, if necessary.
</para>

<para>
Whenever a client wants to pass a callback list as an argument in an
<xref linkend='XtCreateWidget' xrefstyle='select: title'/>,
<xref linkend='XtSetValues' xrefstyle='select: title'/>,
or
<xref linkend='XtGetValues' xrefstyle='select: title'/>
call, it should specify the address
of a NULL-terminated array of type
<function>XtCallbackList</function>.
</para>
<literallayout >
typedef struct {
	XtCallbackProc callback;
	XtPointer closure;
} XtCallbackRec, *XtCallbackList;
</literallayout>
<para>
For example, the callback list for procedures A and B with client data
clientDataA and clientDataB, respectively, is
</para>
<literallayout >
static XtCallbackRec callbacks[] = {
	{A, (XtPointer) clientDataA},
	{B, (XtPointer) clientDataB},
	{(XtCallbackProc) NULL, (XtPointer) NULL}
};
</literallayout>
<para>
Although callback lists are passed by address in arglists
and varargs lists,
the Intrinsics recognize callback lists
through the widget resource list and will copy the contents
when necessary.
Widget initialize and set_values procedures
should not allocate memory for the callback list contents.
The Intrinsics automatically do this,
potentially using a different structure for their
internal representation.
</para>
</sect1>

<sect1 id="Identifying_Callback_Lists">
<title>Identifying Callback Lists</title>
<para>
Whenever a widget contains a callback list for use by clients,
it also exports in its public .h file the resource name of the callback list.
Applications and client widgets never access callback list fields directly.
Instead, they always identify the desired callback list by using the exported
resource name.
All the callback manipulation functions described in this chapter
except
<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
check
to see that the requested callback list is indeed implemented by the widget.
</para>

<para>
For the Intrinsics to find and correctly handle callback lists,
they must be declared with a resource type of
<function>XtRCallback</function>.
The internal representation of a callback list is
implementation-dependent; widgets may make no assumptions about the
value stored in this resource if it is non-NULL.  Except to compare
the value to NULL (which is equivalent to
<function>XtCallbackStatus</function>
<function>XtCallbackHasNone ),</function>
access to callback list resources must be made
through other Intrinsics procedures.
</para>
</sect1>

<sect1 id="Adding_Callback_Procedures">
<title>Adding Callback Procedures</title>
<para>
To add a callback procedure to a widget's callback list, use
<xref linkend='XtAddCallback' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAddCallback'>
<funcprototype>
<funcdef>void <function>XtAddCallback</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
   <paramdef>XtCallbackProc <parameter>callback</parameter></paramdef>
   <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to which the procedure is to be appended.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback procedure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies additional data to be passed to the specified procedure
when it is invoked,
or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
A callback will be invoked as many times as it occurs in the callback list.
</para>

<para>
To add a list of callback procedures to a given widget's callback list, use
<xref linkend='XtAddCallbacks' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtAddCallbacks'>
<funcprototype>
<funcdef>void <function>XtAddCallbacks</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
   <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to which the procedures are to be appended.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callbacks</emphasis>
    </term>
    <listitem>
      <para>
Specifies the null-terminated list of callback procedures and corresponding
client data.
    </para>
  </listitem>
  </varlistentry>
</variablelist>


</sect1>

<sect1 id="Removing_Callback_Procedures">
<title>Removing Callback Procedures</title>
<para>
To delete a callback procedure from a widget's callback list, use
<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRemoveCallback'>
<funcprototype>
<funcdef>void <function>XtRemoveCallback</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
   <paramdef>XtCallbackProc <parameter>callback</parameter></paramdef>
   <paramdef>XtPointer <parameter>client_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list from which the procedure is to be deleted.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback procedure.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>client_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies the client data to match with the registered callback entry.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtRemoveCallback' xrefstyle='select: title'/>
function removes a callback only if both the procedure and the client
data match.
</para>

<para>
To delete a list of callback procedures from a given widget's callback list, use
<xref linkend='XtRemoveCallbacks' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRemoveCallbacks'>
<funcprototype>
<funcdef>void <function>XtRemoveCallbacks</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
   <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list from which the procedures are to be deleted.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callbacks</emphasis>
    </term>
    <listitem>
      <para>
Specifies the null-terminated list of callback procedures and corresponding
client data.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
To delete all callback procedures from a given widget's callback list
and free all storage associated with the callback list, use
<xref linkend='XtRemoveAllCallbacks' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtRemoveAllCallbacks'>
<funcprototype>
<funcdef>void <function>XtRemoveAllCallbacks</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to be cleared.
    </para>
  </listitem>
  </varlistentry>
</variablelist>


</sect1>

<sect1 id="Executing_Callback_Procedures">
<title>Executing Callback Procedures</title>
<para>
To execute the procedures in a given widget's callback list,
specifying the callback list by resource name, use
<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCallCallbacks'>
<funcprototype>
<funcdef>void <function>XtCallCallbacks</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
   <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to be executed.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>call_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies a callback-list-specific data value to pass to each of the callback
procedure in the list, or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>


<para>
<xref linkend='XtCallCallbacks' xrefstyle='select: title'/>
calls each of the callback procedures in the list
named by <emphasis remap='I'>callback_name</emphasis> in the specified widget, passing the client
data registered with the procedure and <emphasis remap='I'>call-data</emphasis>.
</para>

<para>
To execute the procedures in a callback list, specifying the callback
list by address, use
<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>.
</para>

<funcsynopsis id='XtCallCallbackList'>
<funcprototype>
<funcdef>void <function>XtCallCallbackList</function></funcdef>
   <paramdef>Widget <parameter>widget</parameter></paramdef>
   <paramdef>XtCallbackList <parameter>callbacks</parameter></paramdef>
   <paramdef>XtPointer <parameter>call_data</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>widget</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget instance that contains the callback list.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callbacks</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to be executed.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>call_data</emphasis>
    </term>
    <listitem>
      <para>
Specifies a callback-list-specific data value to pass
to each of the callback procedures in the list, or NULL.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The <emphasis remap='I'>callbacks</emphasis> parameter must specify the contents of a widget or
object resource declared with representation type
<function>XtRCallback</function>.
If <emphasis remap='I'>callbacks</emphasis> is NULL,
<xref linkend='XtCallCallbackList' xrefstyle='select: title'/>
returns immediately; otherwise it calls each of the callback
procedures in the list, passing the client data and <emphasis remap='I'>call_data</emphasis>.
</para>
</sect1>

<sect1 id="Checking_the_Status_of_a_Callback_List">
<title>Checking the Status of a Callback List</title>
<para>
To find out the status of a given widget's callback list, use
<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>.
</para>

<para>
typedef enum {XtCallbackNoList, XtCallbackHasNone, XtCallbackHasSome} XtCallbackStatus;
</para>

<funcsynopsis id='XtHasCallbacks'>
<funcprototype>
<funcdef>XtCallbackStatus <function>XtHasCallbacks</function></funcdef>
   <paramdef>Widget <parameter>w</parameter></paramdef>
   <paramdef>String <parameter>callback_name</parameter></paramdef>
</funcprototype>
</funcsynopsis>

<variablelist>
  <varlistentry>
    <term>
      <emphasis remap='I'>w</emphasis>
    </term>
    <listitem>
      <para>
Specifies the widget.  Must be of class Object or any subclass thereof.
      </para>
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      <emphasis remap='I'>callback_name</emphasis>
    </term>
    <listitem>
      <para>
Specifies the callback list to be checked.
    </para>
  </listitem>
  </varlistentry>
</variablelist>

<para>
The
<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>
function first checks to see if the widget has a callback list identified
by <emphasis remap='I'>callback_name</emphasis>.
If the callback list does not exist,
<xref linkend='XtHasCallbacks' xrefstyle='select: title'/>
returns
<function>XtCallbackNoList</function>.
If the callback list exists but is empty,
it returns
<function>XtCallbackHasNone</function>.
If the callback list exists and has at least one callback registered,
it returns
<function>XtCallbackHasSome</function>.
</para>
</sect1>
</chapter>

haha - 2025