From e12df9b8f56171a778ac3369849e71e607ea7b21 Mon Sep 17 00:00:00 2001 From: Charles Milette Date: Tue, 21 Jan 2020 23:11:57 -0500 Subject: [PATCH 1/3] Clarify behavior of GetWindowTextLength towards zero-length titles I've recently hit that undocumented case myself, so I thought it would be great to add them to the docs to make the behavior of the function less confusing. --- .../content/winuser/nf-winuser-getwindowtextlengtha.md | 4 +++- .../content/winuser/nf-winuser-getwindowtextlengthw.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md index 3dc84456e11e..38fcae3c7be4 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md +++ b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md @@ -80,7 +80,9 @@ Type: Type: int If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section. -If the window has no text, the return value is zero. To get extended error information, call GetLastError. +If the window has no text, the return value is zero. To get extended error information, call GetLastError. + +If the length of the text is zero and the function succeeds, the return value is zero, but the function does not clear the last error information. To determine success or failure, clear the last error information by calling SetLastError with 0, then call GetWindowTextLength. Function failure will be indicated by a return value of zero and a GetLastError result that is nonzero. diff --git a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md index 907663bd62fa..2d81f6f4164c 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md +++ b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md @@ -80,7 +80,9 @@ Type: Type: int If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section. -If the window has no text, the return value is zero. To get extended error information, call GetLastError. +If the window has no text, the return value is zero. To get extended error information, call GetLastError. + +If the length of the text is zero and the function succeeds, the return value is zero, but the function does not clear the last error information. To determine success or failure, clear the last error information by calling SetLastError with 0, then call GetWindowTextLength. Function failure will be indicated by a return value of zero and a GetLastError result that is nonzero. From 9a9b2370ec02d1275e67dd7eec0ecaeebc6073c3 Mon Sep 17 00:00:00 2001 From: KB Date: Wed, 22 Jan 2020 13:13:56 -0800 Subject: [PATCH 2/3] Update nf-winuser-getwindowtextlengtha.md revised --- .../winuser/nf-winuser-getwindowtextlengtha.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md index 38fcae3c7be4..b87cf3fac7ee 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md +++ b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengtha.md @@ -73,24 +73,19 @@ A handle to the window or control. ## -returns +Type: int +If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value might be greater than the length of the text (see Remarks). -Type: Type: int - - -If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section. - -If the window has no text, the return value is zero. To get extended error information, call GetLastError. - -If the length of the text is zero and the function succeeds, the return value is zero, but the function does not clear the last error information. To determine success or failure, clear the last error information by calling SetLastError with 0, then call GetWindowTextLength. Function failure will be indicated by a return value of zero and a GetLastError result that is nonzero. - +If the window has no text, the return value is zero. +Function failure is indicated by a return value of zero and a GetLastError result that is nonzero. +> [!NOTE] +> This function does not clear the most recent error information. To determine success or failure, clear the most recent error information by calling SetLastError with 0, then call GetLastError. ## -remarks - - If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH message to be sent to the specified window or control. Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a window whose window procedure is ANSI. For more information on ANSI and ANSI functions, see Conventions for Function Prototypes. From d4edbb16c17da5d3ab870203e73b0b8efbdbf8a9 Mon Sep 17 00:00:00 2001 From: KB Date: Wed, 22 Jan 2020 13:22:13 -0800 Subject: [PATCH 3/3] Update nf-winuser-getwindowtextlengthw.md revisions --- .../winuser/nf-winuser-getwindowtextlengthw.md | 17 ++++++----------- 1 file changed, 6 insertions(+), 11 deletions(-) diff --git a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md index 2d81f6f4164c..06f8d4220b76 100644 --- a/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md +++ b/sdk-api-src/content/winuser/nf-winuser-getwindowtextlengthw.md @@ -73,24 +73,19 @@ A handle to the window or control. ## -returns +Type: int +If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value might be greater than the length of the text (see Remarks). -Type: Type: int - - -If the function succeeds, the return value is the length, in characters, of the text. Under certain conditions, this value may actually be greater than the length of the text. For more information, see the following Remarks section. - -If the window has no text, the return value is zero. To get extended error information, call GetLastError. - -If the length of the text is zero and the function succeeds, the return value is zero, but the function does not clear the last error information. To determine success or failure, clear the last error information by calling SetLastError with 0, then call GetWindowTextLength. Function failure will be indicated by a return value of zero and a GetLastError result that is nonzero. - +If the window has no text, the return value is zero. +Function failure is indicated by a return value of zero and a GetLastError result that is nonzero. +> [!NOTE] +> This function does not clear the most recent error information. To determine success or failure, clear the most recent error information by calling SetLastError with 0, then call GetLastError. ## -remarks - - If the target window is owned by the current process, GetWindowTextLength causes a WM_GETTEXTLENGTH message to be sent to the specified window or control. Under certain conditions, the GetWindowTextLength function may return a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode. It can also occur when an application uses the ANSI version of GetWindowTextLength with a window whose window procedure is Unicode, or the Unicode version of GetWindowTextLength with a window whose window procedure is ANSI. For more information on ANSI and ANSI functions, see Conventions for Function Prototypes.