156 lines
6.0 KiB
Plaintext
156 lines
6.0 KiB
Plaintext
<!-- $XConsortium: block_wh.sgm /main/5 1996/08/30 14:01:38 rws $ -->
|
|
<!-- (c) Copyright 1995 Digital Equipment Corporation. -->
|
|
<!-- (c) Copyright 1995 Hewlett-Packard Company. -->
|
|
<!-- (c) Copyright 1995 International Business Machines Corp. -->
|
|
<!-- (c) Copyright 1995 Sun Microsystems, Inc. -->
|
|
<!-- (c) Copyright 1995 Novell, Inc. -->
|
|
<!-- (c) Copyright 1995 FUJITSU LIMITED. -->
|
|
<!-- (c) Copyright 1995 Hitachi. -->
|
|
|
|
<![ %CDE.C.CDE; [<RefEntry Id="CDEMX.XCDI.MAN274.rsml.1">]]>
|
|
<![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN274.rsml.1">]]>
|
|
<RefMeta>
|
|
<RefEntryTitle>tttk_block_while</RefEntryTitle>
|
|
<ManVolNum>library call</ManVolNum>
|
|
</RefMeta>
|
|
<RefNameDiv>
|
|
<RefName><Function>tttk_block_while</Function></RefName>
|
|
<RefPurpose>block while a counter is greater than zero
|
|
</RefPurpose>
|
|
</RefNameDiv>
|
|
<!-- $XConsortium: block_wh.sgm /main/5 1996/08/30 14:01:38 rws $-->
|
|
<!-- CDE Common Source Format, Version 1.0.0-->
|
|
<!-- (c) Copyright 1993, 1994, 1995 Hewlett-Packard Company-->
|
|
<!-- (c) Copyright 1993, 1994, 1995 International Business Machines Corp.-->
|
|
<!-- (c) Copyright 1993, 1994, 1995 Sun Microsystems, Inc.-->
|
|
<!-- (c) Copyright 1993, 1994, 1995 Novell, Inc.-->
|
|
<RefSynopsisDiv>
|
|
<FuncSynopsis Remap="ANSI">
|
|
<FuncSynopsisInfo>#include <Tt/tttk.h>
|
|
</FuncSynopsisInfo>
|
|
<FuncDef>Tt_status <Function>tttk_block_while</Function></FuncDef>
|
|
<ParamDef>XtAppContext <Parameter>app2run</Parameter></ParamDef>
|
|
<ParamDef>const int *<Parameter>blocked</Parameter></ParamDef>
|
|
<ParamDef>int <Parameter>ms_timeout</Parameter></ParamDef>
|
|
</FuncSynopsis>
|
|
</RefSynopsisDiv>
|
|
<RefSect1>
|
|
<Title>DESCRIPTION</Title>
|
|
<Para>The
|
|
<Function>tttk_block_while</Function> function
|
|
is used to process asynchronous events, such as ToolTalk messages
|
|
or window system events, while waiting for a condition or timeout.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>app2run</Emphasis> is not zero, then an event loop is run for that application context,
|
|
by repeatedly calling
|
|
<Function>XtAppProcessEvent</Function>(3) with
|
|
<Emphasis>ms_timeout</Emphasis> being effected using
|
|
<Function>XtAppAddTimeOut</Function>(3). If
|
|
<Emphasis>app2run</Emphasis> is zero, then the file descriptor (as returned by
|
|
&cdeman.tt.fd;) of the default procid is polled (using the
|
|
<Function>poll</Function>(2) function) and
|
|
&cdeman.tttk.Xt.input.handler; is called whenever the file descriptor is active.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>blocked</Emphasis> is zero, then
|
|
<Function>tttk_block_while</Function> runs until
|
|
<Emphasis>ms_timeout</Emphasis> occurs.
|
|
If
|
|
<Emphasis>blocked</Emphasis> is non-zero, then the loop is run until either
|
|
<Emphasis>ms_timeout</Emphasis> occurs, or
|
|
<Emphasis>*blocked</Emphasis> is less than 1.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>ms_timeout</Emphasis> is zero,
|
|
<Function>tttk_block_while</Function> checks once for events, processes the first one, and then returns.
|
|
If
|
|
<Emphasis>ms_timeout</Emphasis> is negative,
|
|
no timeout is in effect.
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>RETURN VALUE</Title>
|
|
<Para>Upon successful completion, the
|
|
<Function>tttk_block_while</Function> function returns the status of the operation as one of the following
|
|
<StructName Role="typedef">Tt_status</StructName> values:
|
|
</Para>
|
|
<VariableList>
|
|
<VarListEntry>
|
|
<Term>TT_OK</Term>
|
|
<ListItem>
|
|
<Para>The operation completed successfully.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_DESKTOP_ETIMEDOUT</Term>
|
|
<ListItem>
|
|
<Para>The timeout occurred within
|
|
<Emphasis>ms_timeout</Emphasis> milliseconds, or
|
|
<Emphasis>ms_timeout</Emphasis> was zero and no input was available.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_DESKTOP_EINTR</Term>
|
|
<ListItem>
|
|
<Para>The
|
|
<Emphasis>app2run</Emphasis> argument was zero, and
|
|
<Function>poll</Function>(2) was interrupted by a signal.
|
|
</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
<VarListEntry>
|
|
<Term>TT_DESKTOP_EAGAIN</Term>
|
|
<ListItem>
|
|
<Para>The
|
|
<Emphasis>app2run</Emphasis> argument was zero, and
|
|
<Function>poll</Function>(2) returned
|
|
<SystemItem Class="Constant">EAGAIN</SystemItem>.</Para>
|
|
</ListItem>
|
|
</VarListEntry>
|
|
</VariableList>
|
|
<Para>If
|
|
<Emphasis>app2run</Emphasis> is not zero and
|
|
<Emphasis>ms_timeout</Emphasis> is negative, then
|
|
<Function>tttk_block_while</Function> will only return when
|
|
<Emphasis>*blocked</Emphasis> is less than 1, with
|
|
<SystemItem Class="Constant">TT_OK</SystemItem> being returned.
|
|
</Para>
|
|
<Para>If
|
|
<Emphasis>app2run</Emphasis> is not zero,
|
|
<Emphasis>ms_timeout</Emphasis> is negative, and
|
|
<Emphasis>blocked</Emphasis> is zero, then
|
|
<Function>tttk_block_while</Function> behaves equivalent to
|
|
<Function>XtAppMainLoop</Function>(3), and will never return.
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>APPLICATION USAGE</Title>
|
|
<Para>If
|
|
<Emphasis>app2run</Emphasis> is zero, then only messaging events for the default procid will be serviced.
|
|
Events for other procids will be blocked, as will window
|
|
system events, so that the graphical user interface of the application
|
|
will not update itself even, for example, after expose events.
|
|
</Para>
|
|
<Para>On the other hand, if the application passes its Xt context in as
|
|
<Emphasis>app2run</Emphasis>, then window system events will continue to be handled, as will message
|
|
activity for all procids for which an
|
|
<Function>XtAppAddInput</Function>(3) has been done.
|
|
Since the window system event loop is fully operational
|
|
in this case, the application should take care to disable any
|
|
user interface controls that the user should not operate while
|
|
the application is waiting for
|
|
<Function>tttk_block_while</Function> to return.
|
|
</Para>
|
|
</RefSect1>
|
|
<RefSect1>
|
|
<Title>SEE ALSO</Title>
|
|
<Para>&cdeman.Tt.tttk.h;, &cdeman.tttk.Xt.input.handler;; <![ %CDE.C.CDE; [<Function>poll</Function>(2), <Function>XtAppPending</Function>(3), <Function>XtAppAddTimeOut</Function>(3), <Function>XtAppNextEvent</Function>(3), <Function>XtDispatchEvent</Function>(3). ]]><![ %CDE.C.XO; [<Function>poll</Function> in the &str-ZK;;
|
|
<Function>XtAppPending</Function>, <Function>XtAppAddTimeOut</Function>, <Function>XtAppNextEvent</Function>, <Function>XtDispatchEvent</Function> in the &str-Zt;.
|
|
]]></Para>
|
|
</RefSect1>
|
|
</RefEntry>
|
|
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
|