View source for WinSubstituteStrings

This function performs a substitution process on a text string, replacing specific marker characters with text supplied by the application.

==Syntax==
 WinSubstituteStrings(''hwnd, pszSrc, lDestMax, pszDest'')

==Parameters==
;''hwnd'' (HWND) - input: Handle of window that processes the call.
;''pszSrc'' (PSZ) - input:Source string.
:This is the text string that is to have substitution performed.
;''lDestMax'' (LONG) - input:Maximum number of characters returnable.
:This is the maximum number of characters that can be returned in pszDest. It must be greater than 0.
;''pszDest'' (PSZ) - output:Resultant string.
:This is the text string produced by the substitution process.
:The string is truncated if it would otherwise contain more than lDestMax characters. When truncation occurs, the last character of the truncated string is always the null-termination character.

==Returns==
;lDestRet (LONG) - returns:Actual number of characters returned.
:This is the actual number returned in pszDest, excluding the null-termination character. The maximum value is (lDestMax-1). It is zero if an error occurred.

==Errors==
Possible returns from WinGetLastError
;PMERR_INVALID_HWND (0x1001):An invalid window handle was specified.

==Remarks==
When a string of the form "%n" (where n is in the range 0 through 9) occurs in the source string, a WM_SUBSTITUTESTRING message is sent to the specified window. This message returns a text string to use as a substitution for "%n" in the destination string, which is otherwise an exact copy of the source string.

If "%%" occurs in the source, "%" is copied to the destination, but no other substitution occurs. If "%x" occurs in the source, where x is not a digit or "%", the source is copied unchanged to the destination. The source and destination strings must not overlap in memory.

This function is particularly useful for displaying variable information in dialogs, menus, and other user-interface calls. Variable information can include such things as file names, which cannot be statically declared within resource files.

This function is called by the system while creating child windows in a dialog box. It allows the child windows to perform textual substitutions in their window text.

==Example Code==
This example shows how the substitution process works when the WinSubstituteStrings call is made.
<pre>
#define INCL_WINDIALOGS
#include <os2.h>

static MRESULT ClientWindowProc(HWND hwnd,ULONG msg,MPARAM mp1,MPARAM mp2);
test()
{
  HWND hwnd;
  char source[] = "This is the source string: %1";
  char result[22];
  MPARAM mp1;
  ULONG  msg;

  /* This function performs a substitution process on a text string, */
  /* replacing specific marker characters with text supplied         */
  /* by the application.                                             */
  WinSubstituteStrings(hwnd,
                       source,
                       sizeof(result),
                       result);

  /* WM_SUBSTITUTESTRING message is sent to the window  */
  /* defined by hwnd.                                         */
}
static MRESULT ClientWindowProc( HWND hwnd, ULONG  msg, MPARAM mp1, MPARAM mp2 )
{
  switch(msg)
  {
    case WM_SUBSTITUTESTRING:
    switch( (ULONG)mp1)
    {
      case 1:
      return(MRFROMP("A"));
      break;
    }
    break;
  }
}
</pre>

==Related Functions==
* WinCompareStrings
* WinLoadString
* WinNextChar
* WinPrevChar
* WinUpper
* WinUpperChar

==Related Messages==
* WM_SUBSTITUTESTRING

[[Category:Win]]