[VBA × Windows API] How to Use the SetWindowText Function

Contents

1. SetWindowText Function

SetWindowText Function

The SetWindowText function changes the text shown in the title bar (the caption) of a specified window. In VBA you can change a UserForm’s caption by writing UserForm.Caption = "New window title"; SetWindowText lets you do the same thing — set any window currently on screen to display the caption you choose.
Note: some applications guard their caption and will silently ignore SetWindowText.

Two functions are closely related to SetWindowText: GetWindowTextLength, which returns the length of the caption, and its mirror image GetWindowText, which reads the current caption of a given window.

Usage

Before calling SetWindowText, you must declare it at the top of your module.
Without the declaration the function cannot be used and will raise an error, so don’t forget it.

The declaration differs depending on whether your Office/VBA host is 32-bit or 64-bit. Place one of the following near the top of your module (just after Option Explicit) to make the function available inside that module.

64-bit

Declare PtrSafe Function SetWindowText Lib “user32" Alias “SetWindowTextA" _
(ByVal hwnd As LongPtr, ByVal lpString As String) As Long

32-bit

Declare Function SetWindowText Lib “user32" Alias “SetWindowTextA" _
(ByVal hwnd As Long, ByVal lpString As String) As Long

If you are not sure which one to use, paste the following block at the top of your module. It automatically selects the correct declaration at compile time.
In the VBE, the unused branch may be shown in red, but this does not affect execution.

#If VBA7 Then
    Declare PtrSafe Function SetWindowText Lib "user32" Alias "SetWindowTextA" (ByVal hwnd As LongPtr, ByVal lpString As String) As Long
#Else
    Declare Function SetWindowText Lib "user32" Alias "SetWindowTextA" (ByVal hwnd As Long, ByVal lpString As String) As Long
#End If

You can also prefix the declaration with Private or Public to control its scope.

・Private Declare PtrSafe Function … : callable only within the current module
・Public Declare PtrSafe Function … : callable from outside the module

Syntax

The syntax of the SetWindowText function is as follows.

SetWindowText function

lRet = SetWindowText(hWnd, lpString)

Arguments

hWnd (64-bit: LongPtr / 32-bit: Long)

Handle to the window whose caption you want to change.
There are several APIs that can produce a window handle, including FindWindow, GetActiveWindow, GetNextWindow, and GetParent.
The variable type depends on whether you’re running 32-bit or 64-bit VBA, so be careful when declaring the variable that holds the handle.
　

lpString (String)

The new caption text you want to set on the window.
　

Return value

lRet (Long)

On success, the return value is non-zero.
On failure, the return value is 0.

Sample Code

The sample below combines FindWindow with SetWindowText to change the caption of a specific window. As written, it grabs the frontmost Notepad window and rewrites its title. By replacing the class name "Notepad" you can target any other application.
For details on class names, see the FindWindow and GetClassName pages.

Declare PtrSafe Function FindWindow Lib "user32" Alias "FindWindowA" (ByVal lpClassName As String, ByVal lpWindowName As String) As LongPtr
Declare PtrSafe Function SetWindowText Lib "user32" Alias "SetWindowTextA" (ByVal hwnd As LongPtr, ByVal lpString As String) As Long

Sub main()

    Dim hwnd As LongPtr
    Dim lRet As Long
    
    ' Get the handle of the frontmost Notepad window
    hwnd = FindWindow("Notepad", vbNullString)
    
    ' Change the caption of that window
    lRet = SetWindowText(hwnd, "New window title")

End Sub