Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►                          ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_WINDIALOGS
 
SHORT WinSubstituteStrings(hwnd, pszSrc, cchDstMax, pszDst)
HWND hwnd;          /* handle of the window                     */
PSZ pszSrc;         /* address of the source string             */
SHORT cchDstMax;    /* size of destination string buffer        */
PSZ pszDst;         /* address of buffer for destination string */
 
The WinSubstituteStrings function performs a substitution process on a text
string, replacing certain marker characters with text supplied by the
application. The WinSubstituteStrings function is particularly useful for
displaying variable information in dialog boxes, menus, and other
user-interface functions. Variable information can include things such as
filenames, which cannot be statically declared within resource files.
 
This function is called by the system while creating the child windows in a
dialog box. It allows the child windows to perform textual substitutions in
their window text.
 
Parameter  Description
────────────────────────────────────────────────────────────────────────────
 
hwnd       Identifies the window that processes the function.
 
pszSrc     Points to the null-terminated text string to perform the
           substitution.
 
cchDstMax  Specifies the maximum number of characters that can be returned
           in the pszDst parameter.
 
pszDst     Points to the null-terminated text string produced by the
           substitution process. The string is truncated if it would
           otherwise contain more than the number of characters specified by
           the cchDstMax parameter. When truncation occurs, the last
           character of the truncated string is always the NULL termination
           character.
 
Return Value
 
The return value is the number of characters returned in pszDst, not
including the terminating NULL character. The maximum value is (cchDstMax -
1). It is zero if an error occurred.
 
Comments
 
When a string of the form %n is encountered in the source string, where n is
a digit from 0 through 9, a WM_SUBSTITUTESTRING message is sent to the
specified window. This message returns a text string to use as a
substitution for the %n in the destination string, which is otherwise an
exact copy of the source string.
 
If % is encountered in the source, % is copied to the destination, but no
other substitution occurs. If %x occurs in the source, where x is neither a
digit nor %, then the source is copied to the destination unchanged.
 
The source and destination strings must not overlap in memory.
 
To use this function, your application must process WM_SUBSTITUTESTRING
messages and perform the requested string substitution.
 
See Also
 
WM_SUBSTITUTESTRING
 
                                      ♦