CDE/cde/doc/C/guides/man/m3_Dt/EdChange.sgm

<!-- $XConsortium: EdChange.sgm /main/5 1996/08/30 12:57:35 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.XCSA.MAN16.rsml.1">]]>
<![ %CDE.C.XO; [<RefEntry Id="XCSA.MAN16.rsml.1">]]>
<RefMeta>
<RefEntryTitle>DtEditorChange</RefEntryTitle>
<ManVolNum>library call</ManVolNum>
</RefMeta>
<RefNameDiv>
<RefName><Function>DtEditorChange</Function></RefName>
<RefPurpose>change one or all occurrences of a string in a DtEditor widget
</RefPurpose>
</RefNameDiv>
<!-- 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 &lt;Dt/Editor.h>
</FuncSynopsisInfo>
<FuncDef>Boolean <Function>DtEditorChange</Function></FuncDef>
<ParamDef>Widget <Parameter>widget</Parameter></ParamDef>
<ParamDef>DtEditorChangeValues *<Parameter>findChangeStrings</Parameter></ParamDef>
<ParamDef>unsigned int <Parameter>instanceToChange</Parameter></ParamDef>
</FuncSynopsis>
</RefSynopsisDiv>
<RefSect1>
<Title>DESCRIPTION</Title>
<Para>The
<Function>DtEditorChange</Function> function replaces the next occurrence of a string, all occurrences of
the string, or the currently selected text in a DtEditor widget with a
replacement string.
The string to search for and the value to
change it to can be the last values entered in the Find/Change
dialog (see
&cdeman.DtEditorInvokeFindChangeDialog;) or passed as arguments to
<Function>DtEditorChange</Function>.</Para>
<Para>The search begins at the insertion cursor.
If the string is not found by the time the end of the document is reached,
the search continues at the beginning of the document,
stopping at the character before the insertion cursor.
</Para>
<Para>The
<Symbol Role="Variable">widget</Symbol> argument specifies the DtEditor widget ID.
</Para>
<Para>The
<Emphasis>findChangeStrings</Emphasis> argument specifies the string to change and the replacement value.
If
<Emphasis>findChangeStrings</Emphasis> is
<SystemItem Class="Constant">NULL</SystemItem>, <Function>DtEditorChange</Function> uses the last string specified in the Find and Change To fields
of the Find/Change dialog.
If the
<Emphasis>instanceToChange</Emphasis> argument is
<SystemItem Class="Constant">DtEDITOR_CURRENT_SELECTION</SystemItem>, the Find field of
<StructName Role="typedef">DtEditorChangeValues</StructName> is ignored.
</Para>
<Para>If the
<Emphasis>instanceToChange</Emphasis> argument
is set to
<SystemItem Class="Constant">DtEDITOR_NEXT_OCCURRENCE</SystemItem>, <Function>DtEditorChange</Function> replaces the next occurrence (relative to the
insertion cursor) of the find string.
If this argument is set to
<SystemItem Class="Constant">DtEDITOR_ALL_OCCURRENCES</SystemItem>, all instances of the find string are changed.
If this argument ia set to
<SystemItem Class="Constant">DtEDITOR_CURRENT_SELECTION</SystemItem>, the Find field of
<StructName Role="typedef">DtEditorChangeValues</StructName>, is ignored and the currently selected text is replaced.
<![ %CDE.C.CDE; [</Para>
<Para>For a complete definition of the DtEditor widget
and its associated resources, see
&cdeman.DtEditor;. ]]></Para>
<Para>For a complete definition of
<StructName Role="typedef">DtEditorChangeValues</StructName>, see
&cdeman.Dt.Editor.h;.</Para>
</RefSect1>
<RefSect1>
<Title>RETURN VALUE</Title>
<Para>Upon successful completion, the
<Function>DtEditorChange</Function> function returns
True
if the substitution occurred;
otherwise, it returns
False.
</Para>
</RefSect1>
<RefSect1>
<Title>SEE ALSO</Title>
<Para>&cdeman.Dt.Editor.h;, &cdeman.DtEditor;, &cdeman.DtEditorFind;, &cdeman.DtEditorInvokeFindChangeDialog;.</Para>
</RefSect1>
</RefEntry>
<!--fickle 1.12 mancsf-to-docbook 1.2 08/07/95 23:40:24-->