The following example shows how to define a Lisp function which calls a Win32 API function to change the title of the active window. It demonstrates the use of define-foreign-function and with-foreign-string to pass a Lisp string to a Windows function.
The first step involves defining a FLI type to correspond to the Windows
type, which is the window handle type.
The next step consists of the foreign function definitions. The first foreign function returns the window handle of the active window, by calling the Windows function
. It takes no arguments.
(fli:define-foreign-function (get-act-window "GetActiveWindow")
:documentation "Returns the window handle of the active window for the current thread. If no active window is associated with the current thread then it returns 0.")
The next foreign function uses the Windows function
to set the text of the active window titlebar. It takes a window handle and a pointer to a FLI string as its arguments.
(fli:define-foreign-function (set-win-text "SetWindowText" :dbcs)
:documentation "Sets the text of the window titlebar.")
The foreign function
returns a boolean to indicate whether it has successfully changed the title bar.
The required FLI data types and foreign functions have been defined. What is now required is a Lisp function which uses them to change the titlebar of the active window. The next function does this:
(defun set-active-window-text (new-text)
(let ((active-window (get-act-window))
(external-format (if (string= (software-type)
(unless (zerop active-window)
(fli:with-foreign-string (new-ptr element-count byte-count
(declare (ignore element-count byte-count))
(set-win-text active-window new-ptr)))))
takes a Lisp string as its argument, and does the following:
get-act-windowto set the variable
active-windowto be the handle of the active window. If no window is active, this will be zero.
external-formatis set to be
:unicodeif the operating system is Windows NT (which expects strings to be passed to it in unicode format), otherwise it is set to be
active-windowis zero, then there is no active window, and the function terminates, returning
active-windowis not zero, then it contains a window handle, and the following happens:
The function uses with-foreign-string to convert the Lisp string argument of the function into a FLI string, and a pointer to the FLI string is allocated, ready to be handed to the foreign function
that we defined earlier. The encoding of the string is
, which is the encoding suitable for the operating system running on the computer. Once the window title has been set, with-foreign-string automatically deallocates the memory that was allocated for the FLI string and the pointer. The function then terminates, returning
You can test that this is what happens by entering the command:
(set-active-window-text "A new title for the active window")
See with-foreign-string, for more details on the use of foreign strings.