Initial import of the CDE 2.1.30 sources from the Open Group.
This commit is contained in:
Peter Howkins
354
cde/doc/C/guides/man/m3_ttdt/ses_join.sgm
Normal file
354
cde/doc/C/guides/man/m3_ttdt/ses_join.sgm
Normal file
@@ -0,0 +1,354 @@
|
||||
<!-- $XConsortium: ses_join.sgm /main/7 1996/09/08 20:22:12 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.MAN266.rsml.1">]]>
|
||||
<![ %CDE.C.XO; [<RefEntry Id="XCDI.MAN266.rsml.1">]]>
|
||||
<RefMeta>
|
||||
<RefEntryTitle>ttdt_session_join</RefEntryTitle>
|
||||
<ManVolNum>library call</ManVolNum>
|
||||
</RefMeta>
|
||||
<RefNameDiv>
|
||||
<RefName><Function>ttdt_session_join</Function></RefName>
|
||||
<RefPurpose>join a ToolTalk session
|
||||
</RefPurpose>
|
||||
</RefNameDiv>
|
||||
<!-- $XConsortium: ses_join.sgm /main/7 1996/09/08 20:22:12 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_pattern <Function>*ttdt_session_join</Function></FuncDef>
|
||||
<ParamDef>const char *<Parameter>sessid</Parameter></ParamDef>
|
||||
<ParamDef>Ttdt_contract_cb <Parameter>cb</Parameter></ParamDef>
|
||||
<ParamDef>Widget <Parameter>shell</Parameter></ParamDef>
|
||||
<ParamDef>void *<Parameter>clientdata</Parameter></ParamDef>
|
||||
<ParamDef>int <Parameter>join</Parameter></ParamDef>
|
||||
</FuncSynopsis>
|
||||
</RefSynopsisDiv>
|
||||
<RefSect1>
|
||||
<Title>DESCRIPTION</Title>
|
||||
<Para>The
|
||||
<Function>ttdt_session_join</Function> function
|
||||
joins the session
|
||||
<Emphasis>sessid</Emphasis>, registering patterns and
|
||||
default callbacks for many standard Desktop message interfaces.
|
||||
If
|
||||
<Emphasis>sessid</Emphasis> is
|
||||
<SystemItem Class="Constant">NULL</SystemItem>, the default session is joined.
|
||||
</Para>
|
||||
<Para>The
|
||||
<Function>ttdt_session_join</Function> function
|
||||
registers for the following
|
||||
<SystemItem Class="Constant">TT_HANDLER</SystemItem>-addressed requests:
|
||||
</Para>
|
||||
<OrderedList>
|
||||
<ListItem>
|
||||
<Para><Symbol Role="Message">Get_Environment</Symbol>, <Symbol Role="Message">Set_Environment</Symbol>, <Symbol Role="Message">Get_Locale</Symbol>, <Symbol Role="Message">Set_Locale</Symbol>, <Symbol Role="Message">Get_Situation</Symbol>, <Symbol Role="Message">Set_Situation</Symbol>, <Symbol Role="Message">Signal</Symbol>, <Symbol Role="Message">Get_Sysinfo</Symbol></Para>
|
||||
</ListItem>
|
||||
<ListItem>
|
||||
<Para><Symbol Role="Message">Get_Geometry</Symbol>, <Symbol Role="Message">Set_Geometry</Symbol>, <Symbol Role="Message">Get_Iconified</Symbol>, <Symbol Role="Message">Set_Iconified</Symbol>, <Symbol Role="Message">Get_Mapped</Symbol>, <Symbol Role="Message">Set_Mapped</Symbol>, <Symbol Role="Message">Raise</Symbol>, <Symbol Role="Message">Lower</Symbol>, <Symbol Role="Message">Get_XInfo</Symbol></Para>
|
||||
</ListItem>
|
||||
<ListItem>
|
||||
<Para><Symbol Role="Message">Pause</Symbol>, <Symbol Role="Message">Resume</Symbol>, <Symbol Role="Message">Quit</Symbol></Para>
|
||||
</ListItem>
|
||||
<ListItem>
|
||||
<Para><Symbol Role="Message">Get_Status</Symbol>, <Emphasis>Do_Command</Emphasis></Para>
|
||||
</ListItem>
|
||||
</OrderedList>
|
||||
<Para>If
|
||||
<Emphasis>join</Emphasis> is True,
|
||||
<Function>ttdt_session_join</Function> actually joins the indicated session.
|
||||
</Para>
|
||||
<Para>The ToolTalk service
|
||||
handles messages in (1) transparently.
|
||||
</Para>
|
||||
<Para>If
|
||||
<Symbol Role="Variable">shell</Symbol> is non-
|
||||
<SystemItem Class="Constant">NULL</SystemItem>, then it is expected to be a realized
|
||||
<Emphasis>mappedWhenManaged</Emphasis> <Emphasis>applicationShellWidget</Emphasis>, and
|
||||
the ToolTalk service
|
||||
handles messages in (2) transparently.
|
||||
(If
|
||||
<Symbol Role="Variable">shell</Symbol> is merely a realized widget, then
|
||||
the ToolTalk service
|
||||
handles only the
|
||||
<Symbol Role="Message">Get_XInfo</Symbol> request, and
|
||||
<Function>ttdt_session_join</Function> fails the rest of (2) with
|
||||
<SystemItem Class="Constant">TT_DESKTOP_ENOTSUP</SystemItem>.) If
|
||||
<Symbol Role="Variable">shell</Symbol> is
|
||||
<SystemItem Class="Constant">NULL</SystemItem>, then
|
||||
the ToolTalk service
|
||||
treats messages in (2) equivalently to those in (4).
|
||||
</Para>
|
||||
<Para>If
|
||||
<Symbol Role="Variable">shell</Symbol> is non-
|
||||
<SystemItem Class="Constant">NULL</SystemItem> and
|
||||
<Emphasis>cb</Emphasis> is
|
||||
<SystemItem Class="Constant">NULL</SystemItem>, then
|
||||
the ToolTalk service
|
||||
handles messages in (3) transparently as follows;
|
||||
otherwise, it treats them as equivalent to those in (4).
|
||||
The
|
||||
<Symbol Role="Message">Quit</Symbol> request results in a
|
||||
<SystemItem Class="Constant">WM_DELETE_WINDOW</SystemItem> event on
|
||||
<Symbol Role="Variable">shell</Symbol> if the
|
||||
<Emphasis>silent</Emphasis> and
|
||||
<Emphasis>force</Emphasis> arguments of the
|
||||
<Symbol Role="Message">Quit</Symbol> request are both False.
|
||||
In other words, if
|
||||
<Symbol Role="Variable">shell</Symbol> is supplied without a
|
||||
<Emphasis>cb</Emphasis>, then a
|
||||
<Symbol Role="Message">Quit</Symbol> request may imply that the user
|
||||
quit the application's top-level window using the window manager.
|
||||
<Symbol Role="Message">Pause</Symbol> and
|
||||
<Symbol Role="Message">Resume</Symbol> requests result in
|
||||
the ToolTalk service
|
||||
passing
|
||||
<Symbol Role="Variable">shell</Symbol> and the appropriate boolean value to
|
||||
<Function>XtSetSensitive</Function>(3).</Para>
|
||||
<Para>If
|
||||
<Emphasis>cb</Emphasis> is not
|
||||
<SystemItem Class="Constant">NULL</SystemItem>, the ToolTalk service passes
|
||||
messages in (4) to
|
||||
<Emphasis>cb</Emphasis>; otherwise,
|
||||
<Function>ttdt_session_join</Function> fails with
|
||||
<SystemItem Class="Constant">TT_DESKTOP_ENOTSUP</SystemItem>.</Para>
|
||||
<Para>The
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName> argument is a callback defined as:
|
||||
</Para>
|
||||
<InformalExample Remap="indent">
|
||||
<ProgramListing>Tt_message (*Ttdt_contract_cb)(Tt_message <Emphasis>msg</Emphasis>,
|
||||
void *<Emphasis>clientdata</Emphasis>,
|
||||
Tt_message <Emphasis>contract</Emphasis>);
|
||||
</ProgramListing>
|
||||
</InformalExample>
|
||||
<Para>The
|
||||
<Emphasis>msg</Emphasis> argument is
|
||||
a message in
|
||||
<StructName Role="typedef">Tt_state</StructName> <SystemItem Class="Constant">TT_SENT</SystemItem>. If
|
||||
<Emphasis>msg</Emphasis> is a
|
||||
<SystemItem Class="Constant">TT_REQUEST</SystemItem>, the client program becomes responsible for either failing,
|
||||
rejecting or replying to
|
||||
<Emphasis>msg</Emphasis>. After doing so, the client program may dispose of
|
||||
<Emphasis>msg</Emphasis> with
|
||||
<Function>tttk_message_destroy</Function>. The
|
||||
<Emphasis>clientdata</Emphasis> argument is the
|
||||
<Emphasis>clientdata</Emphasis> passed to
|
||||
<Function>ttdt_session_join</Function> or
|
||||
&cdeman.ttdt.message.accept;. The
|
||||
<Emphasis>contract</Emphasis> argument is the
|
||||
<Emphasis>contract</Emphasis> passed to
|
||||
<Function>ttdt_message_accept</Function>. For callbacks installed by
|
||||
<Function>ttdt_session_join</Function>, <Emphasis>contract</Emphasis> is always zero.
|
||||
</Para>
|
||||
</RefSect1>
|
||||
<RefSect1>
|
||||
<Title>RETURN VALUE</Title>
|
||||
<Para>Upon successful completion, the
|
||||
<Function>ttdt_session_join</Function> function
|
||||
returns a null-terminated array of
|
||||
<StructName Role="typedef">Tt_pattern</StructName>; otherwise, it returns an error pointer.
|
||||
The application can use
|
||||
&cdeman.tt.ptr.error; to extract one of the following
|
||||
<StructName Role="typedef">Tt_status</StructName> values from the returned handle:
|
||||
</Para>
|
||||
<VariableList>
|
||||
<VarListEntry>
|
||||
<Term>TT_ERR_NOMEM</Term>
|
||||
<ListItem>
|
||||
<Para>There is insufficient memory available to perform the function.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>TT_ERR_NOMP</Term>
|
||||
<ListItem>
|
||||
<Para>The
|
||||
&cdeman.ttsession; process is not running and the ToolTalk service cannot restart it.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>TT_ERR_POINTER</Term>
|
||||
<ListItem>
|
||||
<Para>The pointer passed does not point to an object
|
||||
of the correct type for this operation.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>TT_ERR_PROCID</Term>
|
||||
<ListItem>
|
||||
<Para>The specified process identifier is out of date or invalid.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
<VarListEntry>
|
||||
<Term>TT_ERR_SESSION</Term>
|
||||
<ListItem>
|
||||
<Para>The specified ToolTalk session is out of date or invalid.
|
||||
</Para>
|
||||
</ListItem>
|
||||
</VarListEntry>
|
||||
</VariableList>
|
||||
</RefSect1>
|
||||
<RefSect1>
|
||||
<Title>APPLICATION USAGE</Title>
|
||||
<Para>The null-terminated array of
|
||||
<StructName Role="typedef">Tt_pattern</StructName> returned by
|
||||
<Function>ttdt_session_join</Function> should be destroyed by passing the array to
|
||||
&cdeman.ttdt.file.quit;.</Para>
|
||||
<Para>The ToolTalk service will reply to the
|
||||
<Symbol Role="Message">Quit</Symbol> request before generating the
|
||||
<SystemItem Class="Constant">WM_DELETE_WINDOW</SystemItem> event.
|
||||
If the application catches and cancels this event,
|
||||
then the sender of the
|
||||
<Symbol Role="Message">Quit</Symbol> request will be misled
|
||||
into thinking the application actually quit.
|
||||
Applications that can cancel
|
||||
<SystemItem Class="Constant">WM_DELETE_WINDOW</SystemItem> should install a real
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName>.</Para>
|
||||
<Para>The ToolTalk service handles the
|
||||
<Symbol Role="Message">Pause</Symbol> and
|
||||
<Symbol Role="Message">Resume</Symbol> requests by setting the sensitivity of
|
||||
<Symbol Role="Variable">widget</Symbol>. If
|
||||
<Symbol Role="Variable">widget</Symbol> is the parent of any top-level pop-up shells,
|
||||
<Function>XtSetSensitive</Function>(3) will not affect them.
|
||||
Applications that can have such pop-ups
|
||||
should install a real
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName>.</Para>
|
||||
<Para>A
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName> should return zero if it processes
|
||||
<Emphasis>msg</Emphasis> successfully, or a
|
||||
<Function>tt_error_pointer</Function> cast to
|
||||
<StructName Role="typedef">Tt_message</StructName> if processing results in an error.
|
||||
It should return the
|
||||
<Emphasis>msg</Emphasis> if it does not consume it.
|
||||
If
|
||||
<Emphasis>msg</Emphasis> is returned, then the ToolTalk service passes
|
||||
<SystemItem Class="Constant">TT_CALLBACK_CONTINUE</SystemItem> down the call stack, so that
|
||||
<Emphasis>msg</Emphasis> will be offered to other callbacks or (more likely) be returned from
|
||||
&cdeman.tt.message.receive;. Applications will rarely want
|
||||
<Emphasis>msg</Emphasis> to get processed by other callbacks or in the main event loop.
|
||||
</Para>
|
||||
</RefSect1>
|
||||
<RefSect1>
|
||||
<Title>EXAMPLES</Title>
|
||||
<Para>This is the typical algorithm of a
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName> for an application that handles
|
||||
<Symbol Role="Message">Pause</Symbol>, <Symbol Role="Message">Resume</Symbol> or
|
||||
<Symbol Role="Message">Quit</Symbol> requests for itself, but lets the ToolTalk service
|
||||
handle the X11-related requests listed in (2).
|
||||
Since this example callback deals with the case when
|
||||
<Emphasis>contract</Emphasis> is not zero, it can also be used as the
|
||||
<StructName Role="typedef">Ttdt_contract_cb</StructName> passed to
|
||||
<Function>ttdt_message_accept</Function>.</Para>
|
||||
<InformalExample>
|
||||
<ProgramListing>Tt_message myContractCB(Tt_message msg,
|
||||
void *clientdata,
|
||||
Tt_message contract)
|
||||
{
|
||||
char *opString = tt_message_op(msg);
|
||||
Tttk_op op = tttk_string_op(opString);
|
||||
tt_free(opString);
|
||||
int silent = 0;
|
||||
int force = 0;
|
||||
Boolean cancel = False;
|
||||
Boolean sensitive = True;
|
||||
char *status, command;
|
||||
switch(op) {
|
||||
case TTDT_QUIT:
|
||||
tt_message_arg_ival(msg, 0, &silent);
|
||||
tt_message_arg_ival(msg, 1, &force);
|
||||
if (contract == 0) {
|
||||
/* Quit entire application */
|
||||
cancel = ! myQuitWholeApp(silent, force);
|
||||
} else {
|
||||
/* Quit just the specified request being
|
||||
worked on */
|
||||
cancel = ! myCancelThisRequest(contract,
|
||||
silent, force);
|
||||
}
|
||||
if (cancel) {
|
||||
/* User canceled Quit; fail the Quit request */
|
||||
tttk_message_fail(msg, TT_DESKTOP_ECANCELED, 0, 1);
|
||||
} else {
|
||||
tt_message_reply(msg);
|
||||
tttk_message_destroy(msg);
|
||||
}
|
||||
return 0;
|
||||
case TTDT_PAUSE:
|
||||
sensitive = False;
|
||||
case TTDT_RESUME:
|
||||
if (contract == 0) {
|
||||
int already = 1;
|
||||
if (XtIsSensitive(myTopShell) != sensitive) {
|
||||
already = 0;
|
||||
XtSetSensitive(myTopShell, sensitive);
|
||||
}
|
||||
if (already) {
|
||||
tt_message_status_set(msg,
|
||||
TT_DESKTOP_EALREADY);
|
||||
}
|
||||
} else {
|
||||
if (XtIsSensitive(thisShell) == sensitive) {
|
||||
tt_message_status_set(msg,
|
||||
TT_DESKTOP_EALREADY);
|
||||
} else {
|
||||
XtSetSensitive(thisShell, sensitive);
|
||||
}
|
||||
}
|
||||
tt_message_reply(msg);
|
||||
tttk_message_destroy(msg);
|
||||
return 0;
|
||||
case TTDT_GET_STATUS:
|
||||
if (contract == 0) {
|
||||
status = "Message about status of entire app";
|
||||
} else {
|
||||
status = "Message about status of this request";
|
||||
}
|
||||
tt_message_arg_val_set(msg, 0, status);
|
||||
tt_message_reply(msg);
|
||||
tttk_message_destroy(msg);
|
||||
return 0;
|
||||
case TTDT_DO_COMMAND:
|
||||
if (! haveExtensionLanguage) {
|
||||
tttk_message_fail(msg, TT_DESKTOP_ENOTSUP, 0, 1);
|
||||
return 0;
|
||||
}
|
||||
command = tt_message_arg_val(msg, 0);
|
||||
result = myEval(command);
|
||||
tt_free(command);
|
||||
tt_message_status_set(msg, result);
|
||||
if (tt_is_err(result)) {
|
||||
tttk_message_fail(msg, result, 0, 1);
|
||||
} else {
|
||||
tt_message_reply(msg);
|
||||
tttk_message_destroy(msg);
|
||||
}
|
||||
return 0;
|
||||
}
|
||||
/* Unrecognized message; do not consume it */
|
||||
return msg;
|
||||
}
|
||||
</ProgramListing>
|
||||
</InformalExample>
|
||||
</RefSect1>
|
||||
<RefSect1>
|
||||
<Title>SEE ALSO</Title>
|
||||
<Para>&cdeman.Tt.tttk.h;, &cdeman.ttdt.session.quit;, &cdeman.tt.session.join;, <![ %CDE.C.CDE; [<Function>XtSetSensitive</Function>(3), ]]><![ %CDE.C.XO; [<Function>XtSetSensitive</Function> in the &str-Zt;,
|
||||
]]></Para>
|
||||
</RefSect1>
|
||||
</RefEntry>
|
||||
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:18:47-->
|
||||
Reference in New Issue
Block a user