Tcl Windows API extension

Windows are identified using window handles. A window handle consisting of an empty string represents an invalid or non-existent window when returned from a command.

The commands get_toplevel_windows, get_descendent_windows and get_child_windows enumerate the windows on the system. get_desktop_window and get_shell_window return handles to the desktop window and the shell window respectively. find_windows returns a list of windows that satisfy matching multiple matching criteria. The command window_exists can be used to check if a specific window exists.

The commands get_parent_window, get_owner_window, get_first_child, get_next_sibling_window, get_prev_sibling_window, get_first_sibling_window, get_last_sibling_window retrieve handles to windows with the appropriate relationship to the specified window. The command window_is_child can be used to check parent-child relationships between windows.

The commands get_window_process and get_window_thread retrieve the process and thread respectively that own the specified window. get_window_application returns the application instance for the specified window.

The commands get_foreground_window, set_foreground_window and set_window_zorder deal with the position of windows in the display Z-order.

The commands show_window, hide_window, restore_window, minimize_window, maximize_window, show_owned_popups, and hide_owned_popups control the visibility of windows. The commands window_minimized, window_maximized, window_visible check the visibility state of a window. close_window closes the specified window.

The commands get_window_style, set_window_style, get_window_class, get_window_real_class, get_window_long, set_window_long get_window_userdata and set_window_userdata retrieve and modify various attributes associated with windows.

The visibility and buttons displayed on the title bar of a window can be controlled through the command configure_window_titlebar.

The command get_window_id returns the window id of the specified window.

redraw_window and redraw_window_frame cause the window and the frame of a window to be redrawn respectively.

The commands move_window, resize_window and arrange_icons can be used to position and resize windows. The commands get_window_client_area_size and get_window_coordinates can be used to get window location and size. The command get_window_at_location returns the window at a given screen location.

The commands set_active_window_for_thread, get_active_window_for_thread, get_focus_window_for_thread, get_active_window_for_current_thread deal with the active window state and focus for a particular thread.

The commands enable_window_input, disable_window_input and set_focus deal with controlling input to windows. The command window_input_enabled can be used to check if input to a window is enabled or not. window_unicode_enabled checks if a window is Unicode-enabled or not.

The command flash_window_caption can be used to grab the user's attention by flashing a window or generating a sound.

The commands get_window_text and set_window_text retrieve and modify the title bar of a window or the text associated with a control. In the latter case, only controls in the same application are supported.

The commands get_caret_blink_time, set_caret_blink_time, hide_caret, show_caret, get_caret_location and set_caret_location allow manipulation of the caret and its position.

The command get_desktop_workarea returns the actual usable desktop area (not used by the taskbar etc.). get_color_depth returns the color depth of the display.

The commands get_desktop_wallpaper and set_desktop_wallpaper can be used to manipulate the wallpaper setting for the desktop.

Displays

Command get_display_devices returns a list of display devices in the system. Command get_display_monitors returns a list of monitors in the system. The command get_display_size returns the size of the display.

The monitor corresponing to a window, virtual screen coordinates or virtual screen rectangle be obtained from get_display_monitor_from_window, get_display_monitor_from_point, get_display_monitor_from_rect respectively.

The command get_display_monitor_info returns location and attributes of a specific display monitor. get_multiple_display_monitor_info returns the same information for all display monitors in the system.

Commands

arrange_icons ?HWIN?

Arranges all the minimized (iconized) child windows of the specified window. If HWIN is not specified, it defaults to the desktop window. The command returns the height of one row of icons.

close_window HWIN ?options?

Closes the window specified by HWIN by sending it a WM_CLOSE message. The following options may be specified:

-block	If this option is specified, Windows will block the calling thread from processing any other requests until the command returns.
-wait TIMEOUT	Specifies the number of milliseconds to wait for the window to process the message (default 10 milliseconds).

configure_window_titlebar HWIN ?options?

Configures the title bar of the specified window to show or hide specific buttons. The following options control what buttons are displayed. If a particular option is not specified, the corresponding button is unaffected. Note however that the minimize, maximize and context help buttons are shown only if the system menu is also visible. Also, the minimize and maximize buttons are hidden and displayed as a single group. If one is configured to be hidden and the other is not, both buttons are shown but the hidden one is disabled.

visible BOOLEAN	Controls whether the title bar is displayed.
sysmenu BOOLEAN	Controls whether the system menu button is displayed.
minimizebox BOOLEAN	Controls whether the minimize button is displayed.
maximizebox BOOLEAN	Controls whether the maximize button is displayed.
contexthelp BOOLEAN	Controls whether the context help button is displayed.

disable_window_input HWIN

Disables mouse and keyboard input to the specified window. Returns 1 if the window was previously disabled, else 0.

enable_window_input HWIN

Enables mouse and keyboard input to the specified window. Returns 1 if the window was previously disabled, else 0.

find_windows ?options?

Returns a list of handles corresponding to all windows that match the specified criteria.

The options below control the matching criteria. Note that the boolean options work in tri-state fashion. If the option is not specified, then the corresponding window attribute is not used in the matching at all. If the option value is specified as true, then only windows having that attribute are selected. If the option value is false, only windows without that attribute are selected.

-ancestor HWIN	The window with handle HWIN must be an ancestor of the window.
-caption BOOLEAN	The window must or must not have a caption/title bar depending on whether BOOLEAN is true or false.
-child BOOLEAN	The window must or must not be an child window depending on whether BOOLEAN is true or false.
-class CLASS	The window must belong to the specified class.
-match MATCHTYPE	Specifies the method used for matching PATTERN in the -text option. This may be one of string for an straight character match, glob for matching as in the string match command or regexp for regular expression based matching. In all cases, the comparisons are case-insensitive.
-maximize BOOLEAN	The window must or must not be maximized depending on whether BOOLEAN is true or false.
-maximizebox BOOLEAN	The window must or must not have a maximize box on the title bar depending on whether BOOLEAN is true or false.
-messageonlywindow BOOLEAN	The window must or must not be a message-only window depending on whether BOOLEAN is true or false.
-minimize BOOLEAN	The window must or must not be minimized depending on whether BOOLEAN is true or false.
-minimizebox BOOLEAN	The window must or must not have a minimize box on the title bar depending on whether BOOLEAN is true or false.
-overlapped BOOLEAN	The window must or must not be an overlapped window depending on whether BOOLEAN is true or false.
-pids PIDLIST	The window must be owned by a process whose id is in PIDLIST.
-popup BOOLEAN	The window must or must not be an popup window depending on whether BOOLEAN is true or false.
-single	Returns the first window found without looking for additional windows.
-style STYLE	The window must have the specified style. STYLE must be specified as a list of two integer values corresponding to the style and extended style for the window. See get_window_style.
-text PATTERN	The text associated with the window (generally the window title) must match PATTERN. The matching is done based on the -match option.
-toplevel BOOLEAN	The window must or must not be a toplevel window depending on whether BOOLEAN is true or false.
-visible BOOLEAN	The window must be visible if BOOLEAN is true and hidden if it is false.

Example: Find all windows for an application

Example: Find all windows with a given title

flash_window_caption HWIN ?-toggle?

Flashes the window's title bar. If -toggle is not specified, the window's title bar reverts back to the original state. If -toggle is specified, the title bar stays in the new state.

get_active_window_for_current_thread TID

Returns the current active window for the current thread. If the thread does not have a active window, returns $twapi::null_hwin.

get_active_window_for_thread TID

Returns the current active window for the thread with id TID. If the thread does not have a active window, returns $twapi::null_hwin.

get_caret_blink_time

Returns the blink time of the caret in milliseconds.

get_caret_location

Returns a list of two integers specifying the caret's coordinates. These are always with respect to the client area of the window that owns the caret.

get_child_windows HWIN

Returns a list of handles to all windows that are immediate child windows of the specified window.

get_color_depth ?HWIN?

Returns the number of bits per pixel in the device context of the window identified by HWIN. If HWIN is not specified, the color depth of the entire screen is returned.

get_descendent_windows HWIN

Returns a list of handles to all descendent windows of the specified window.

get_desktop_window

Returns a handle to the desktop window.

get_desktop_wallpaper

Returns the path to the file containing the current wallpaper for the desktop or an empty string if no wallpaper is in use.

get_desktop_workarea

Returns the screen coordinates of the usable area of the desktop as a list of four integers corresponding to the left, top, right and bottom coordinates on the display. The usable area is that area that is not covered by the taskbar and any application desktop toolbars.

get_display_devices

Returns a list of display devices in the system. Each element in the list is a keyed list of key value pairs with the following fields:

-description	A string describing the device.
-desktop	If the value is true, the device is attached to the desktop.
-disconnect
-flags	An integer value containing the device flags. These are also returned as the boolean fields described here.
-id	The value is the device id for the device.
-key	The registry key for the device.
-mirroring	If true, the device is a mirroring pseudo driver such as that used for NetMeeting.
-modespruned	If true, not all the device modes are supported by its output.
-multidriver
-name	The device name.
-primary	If true, the primary desktop is displayed on this device.
-remote
-removable	If true, the device is removable.
-vgacompatible	If true, the device is VGA compatible.

get_display_monitor_from_point X Y ?-default DEFAULTMONITOR?

Returns a handle to the monitor corresponding the virtual screen coordinates (X,Y). If the coordinates lie outside the extents of any monitor, the command will generate an error unless the -default option is specified. If -default is specified with a value of primary, then a handle to the primary display monitor is returned. If the value is nearest, the handle of the monitor whose extent is closest to the screen coordinates is returned.

Note that the returned monitor handle is not a Win32 handle and should not be closed.

get_display_monitor_from_rect RECT ?-default DEFAULTMONITOR?

Returns a handle to the monitor that has the largest area of intersection with the rectangle specified by RECT. RECT indicates a virtual screen region and should be specified as a list of four integers indicating the coordinates of the left, top, right, bottom edges. If the rectangle does not intersect any monitor, the command will generate an error unless the -default option is specified. If -default is specified with a value of primary, then a handle to the primary display monitor is returned. If the value is nearest, the handle of the monitor whose extent is closest to the rectangle is returned.

Note that the returned monitor handle is not a Win32 handle and should not be closed.

get_display_monitor_from_window HWIN ?-default DEFAULTMONITOR?

Returns a handle to the monitor on which the window identified by HWIN is displayed. If the window is not displayed on any monitor, because it is iconified or is placed outside of any monitor extents for example, the command will generate an error unless the -default option is specified. If -default is specified with a value of primary, then a handle to the primary display monitor is returned if the window is not currently displayed. If the value is nearest, the handle of the monitor whose extent is closest to the window is returned.

Note that the returned monitor handle is not a Win32 handle and should not be closed.

get_display_monitors ?-device DEVICENAME? ?-activeonly?

Returns a list of display monitors in the system. If -device is specified, only monitors attached to the device with name DEVICENAME are returned. If -activeonly is specified, only monitors marked as active are returned.

Each element in the returned list is a keyed list of key value pairs with the following fields:

-active	The monitor is active.
-attached
-description	A string describing the device.
-flags	An integer value containing the display monitor flags. These are also returned as the boolean fields described here.
-id	The value is the device id for the device.
-key	The registry key for the device.
-name	The monitor name.

get_display_monitor_info HMONITOR

Returns information about the display monitor identified by HMONITOR which is a monitor handle. The following fields are returned in a keyed list:

-extent	A list of four integers indicating the monitor extent corresponding to the left, top, right and bottom edges of the monitor's display area in virtual screen coordinates.
-name	The name identifying the display monitor.
-primary	A boolean indicating whether the monitor is the primary display monitor.
-workarea	A list of four integers indicating the usable monitor extent corresponding to the left, top, right and bottom edges of the monitor's display area in virtual screen coordinates excluding any space taken up by desktop toolbars and the taskbar.

get_display_size

Returns a list of two integers specifying the width and height of the display.

get_first_child HWIN

Returns a handle to the child window of the specified window that is the first (highest) in the display Z-order.

get_first_sibling_window HWIN

Returns a handle to a sibling window (ie. having the same parent) of the specified window that is the highest in the display Z-order.

get_focus_window_for_thread TID

Returns the window which has the focus the thread with id TID. If the thread does not have a active window, returns $twapi::null_hwin.

get_foreground_window

Returns the current foreground window on the desktop.

get_last_sibling_window HWIN

Returns a handle to a sibling window (ie. having the same parent) of the specified window that is the lowest (least visible) in the display Z-order.

get_multiple_display_monitor_info

Returns a list containing information for every monitor in the system. The information is in the same format as that returned by get_display_monitor_info.

get_next_sibling_window HWIN

Returns a handle to a sibling window (ie. having the same parent) of the specified window that is next in the display Z-order.

get_owner_window HWIN

Returns a handle to the owner window of the specified window or null handle if the window does not have a owner.

get_parent_window HWIN

Returns a handle to the parent window of the specified window.

get_prev_sibling_window HWIN

Returns a handle to a sibling window (ie. having the same parent) of the specified window that is previous (immediately higher) in the display Z-order.

get_shell_window

Returns a handle to the Windows shell process' window.

get_toplevel_windows ?-pid PID?

Returns a list of handles to toplevel windows in the system. If no options are specified, this includes all toplevel windows. If the -pid option is specified with a numeric value of PID, then only toplevel windows owned by the process with id PID are returned. If PID is non-numeric, it is treated as a process name. In this case, the toplevel windows owned by all processes whose name is PID are returned.

get_window_application HWIN

Returns the application instance associated with the specified window.

get_window_at_location X Y

Returns the highest window in the X-order that contains the screen coordinates (X,Y). Windows that are disabled or hidden are not ignored.

get_window_class HWIN

Returns the class of a window. This is simple wrapper around the GetClassName Windows function.

get_window_client_area_size HWIN

Returns a list of two integers containing the width and height in pixels of the client area of the window.

get_window_coordinates HWIN

Returns the screen coordinates of the window as a list of four integers corresponding to the left, top, right and bottom sides of the window.

Example: Move mouse to system menu

get_window_id HWIN

Returns the window id of the specified window. Note that this is different than the window handles.

get_window_long HWIN INDEX

This is a direct call to the GetWindowsLong function. Refer to Windows SDK documentation for details. Several other TWAPI functions act as wrappers provide more straightforward access to the values retrieved by this function.

get_window_process HWIN

Returns the id of the process that owns the specified window.

get_window_real_class HWIN

Returns the real class of a window for classes that are wrapped by applications into their own set of classes. This is simple wrapper around the RealGetWindowClass Windows function. Windows function.

get_window_style HWIN

Returns a list containing the style and the extended style bits respectively followed by symbolic window style attributes corresponding to the style bits. The window styles attributes that may be returned are shown below. Refer to the Windows SDK documentation for the meaning of these styles.

overlapped	The window is an overlapped window - this is a toplevel window without a parent. This attribute is mutually exclusive with popup and child.
popup	The window is popup window like a dialog box. This attribute is mutually exclusive with overlapped and child.
child	The window is the child of some other window. This attribute is mutually exclusive with popup and overlapped.
caption	The window has a caption or title bar and a border.
border	The window has a normal border and no title bar.
dlgframe	The window has a double border as used for dialogs and no title bar.
dlgmodalframe	The window has a double border as used for a dialog and may have a caption as well.
minimize	The window is minimized. Windows with neither minimize or maximize attributes are normal windows.
minimizebutton	The window has a minimize button on the title bar.
maximize	The window is maximized. Windows with neither minimize or maximize attributes are normal windows.
maximizebutton	The window has a maximize button on the title bar.
visible	The window is visible. If this attribute is not present, the window is hidden.
disabled	The window is disabled and does not accept input.
clipsiblings	Indicates that the screen area occupied by sibling windows that overlap will not be overwritten when the window is drawn.
clipchildren	Indicates that the screen area occupied by child windows will not be overwritten when the window is drawn.
vscroll	The window displays a vertical scrollbar.
hscroll	The window displays a horizontal scrollbar.
sysmenu	The window displays a system menu.
thickframe	The window has a thick border that allows for resizing.
noparentnotify	The window is a child window that does not send WM_PARENTNOTIFY messages to its parent.
topmost	The window is a topmost window that is displayed above all non-topmost windows even when it is not active.
acceptfiles	The window accepts files that are dragged and dropped into it.
transparent	The window is transparent and does not obscure windows below it.
mdichild	The window is an MDI child window.
toolwindow	The window is a floating toolbar. The title bar and caption are shrunk. The window does not appear in the task bar and will not show up with the ALT-TAB hotkey.
windowedge	The window has a border with a raised edge.
clientedge	The window has a border with a sunken edge.
contexthelp	The window has a context help button in the caption bar.
controlparent	The window allows navigation between child windows using the TAB key.
staticedge	The window has a 3-D border.
appwindow	The window is forced on the task bar when visible. Note that this does not mean that windows without this attribute will not show up on the task bar. It does mean that windows with this attribute will definitely show up on the task bar.

get_window_text HWIN

Gets the title of a window or the text associated with a control. In the latter case, the control must belong to the same application.

get_window_thread HWIN

Returns the id of the thread that owns the specified window.

get_window_userdata HWIN

Returns the longword associated as user data with the specified window. This maps to the Windows GetWindowLong call with an argument of GWL_USERDATA.

hide_caret

Hides the caret. Note that calls to hide_caret or twapi::HideCaret must be matched by an equivalent number of calls to show_caret or twapi::ShowCaret.

hide_owned_popups HWIN

Hides all popup windows that are owned by the specified window.

hide_window HWIN ?-sync?

Hides the specified window so it does not appear on the display or as an icon. If option -sync is specified, the command will execute synchronously and only return when the window procedure of the target window has handled the request. Note that if the target window is hung, the command will never return.

Returns 1 if the window was previously visible, else 0. The return value is valid only if the -sync option is specified.

Example: Hide all windows for an application

invalidate_screen_region ?options?

Marks a region of the screen as invalid. If no options are specified, all windows are marked invalid, forcing them to be redrawn. The following options may be used with the command:

-hwin HWIN	Indicates the specific window whose client region is to be invalidated.
-rect RECT	If specified, this should be a list of four integers indicating the coordinates of the left, top, right, bottom sides of the region in the window's client area that is to be invalidated. If unspecified or an empty list, the entire client region is marked invalid.
-bgerase	If specified, the background within the invalidated region is erased. Otherwise, it remains unchanged.

maximize_window HWIN ?-sync?

Maximizes the specified window. If option -sync is specified, the command will execute synchronously and only return when the window procedure of the target window has handled the request. Note that if the target window is hung, the command will never return.

The command returns 1 if the window was previously visible, else 0. The return value is valid only if the -sync option is specified.

minimize_window HWIN ?options?

Minimizes the specified window.

-sync	If specified, the command will execute synchronously and only return when the window procedure of the target window has handled the request. Note that if the target window is hung, the command will never return.
-activate	If specified, in addition to being shown, the window is also activated.
-shownext	If specified, the next window in the Z-order is activated.

The command returns 1 if the window was previously visible, else 0. The return value is valid only if the -sync option is specified.

Example: Minimize all windows for an application

move_window HWIN X Y ?-sync?

Moves the specified window such that it's left side is at position X and its top side is at position Y. The window is moved asynchronously unless the -sync option is specified. Note that in this case, the command will never return if the target window is hung.

Example: Move a window to top left corner of the screen

redraw_window HWIN ?-force?

This command causes the invalidate regions of the specified window to be redrawn. If -force is specified, the entire window is redrawn.

redraw_window_frame HWIN

This command causes the frame of the specified window to be redrawn.

resize_window HWIN W H ?-sync?

Resizes the specified window to be W pixels in width and H pixels in height. The resizing is done asynchronously unless the -sync option is specified. Note that in this case, the command will never return if the target window is hung.

restore_window HWIN ?options?

Restores a window to its original size and position if it is maximized or minimized. The command returns 1 if the window was previously visible, else 0. The return value is valid only if the -sync option is specified.

-sync	If specified, the command will execute synchronously and only return when the window procedure of the target window has handled the request. Note that if the target window is hung, the command will never return.
-activate	In addition to being shown, the window is also activated.

set_active_window_for_thread HWIN

Sets the specified window to be the active window for its owning thread. The window is brought to the foreground if the owning thread belongs to the foreground application. Returns the handle of the window that was previously active.

set_caret_blink_time MILLISECONDS

Sets the blink time of the caret to MILLISECONDS milliseconds.

set_caret_location POINT

Sets the caret's location to POINT which must be a list of two integers specifying the caret's coordinates.

set_desktop_wallpaper PATH ?-persist?

Sets the desktop wallpaper to that specified by the file PATH. The file must be in BMP format. If PATH is specified as an empty string or none, no wallpaper is displayed on the desktop. If PATH is default, the default wallpaper is restored to the desktop. If the option -persist is specified, the new setting is written to the user's profile.

set_focus HWIN

Sets the focus to the specified window. The window, or its parent, is also activated. The command returns the window that previously had the focus.

set_foreground_window HWIN

Sets the specified window to be the foreground window. Returns 1 if successful, and 0 otherwise.

Example: Bring a window to the foreground

set_window_long HWIN INDEX VALUE

This is a direct call to the SetWindowsLong function. Refer to Windows SDK documentation for details. Several other TWAPI functions act as wrappers and provide more straightforward access to the values set by this function.

set_window_style HWIN style exstyle

Sets the style and extended style bits for the specified window. style and exstyle are bitmasks. Refer to the Windows SDK documentation for details.

Example: Remove the title bar from a window

set_window_text HWIN TEXT

Sets the title of a window or the text associated with a control. In the latter case, the control must belong to the same application.

Example: Change the title bar of a window

set_window_userdata HWIN INTEGER

Sets the longword associated as user data with the specified window. This maps to the Windows SetWindowLong call with an argument of GWL_USERDATA.

set_window_zorder HWIN POS

Sets the position of the specified window in the Z-order. POS may be either a window handle or a keyword. In the former case, the window is placed right after the window specified by POS. Otherwise, POS must be one of the following keywords:

top	Places the window at the top of the Z-order.
bottom	Places the window at the bottom of the Z-order.
toplayer	Refer to explanation of HWND_TOPMOST in the documentation of the function SetWindowsPos in the Windows SDK.
bottomlayer	Refer to explanation of HWND_NOTOPMOST in the documentation of the function SetWindowsPos in the Windows SDK.

Example: Keep a window on top

show_caret

Shows the caret. Note that calls to hide_caret or twapi::HideCaret must be matched by an equivalent number of calls to show_caret or twapi::ShowCaret to make the caret visible.

show_owned_popups HWIN

Shows all popup windows owned by the specified window that were hidden by a previous call to hide_owned_popups. Note that popups that were hidden using other functions such as hide_window will not be shown by this call.

show_window HWIN ?options?

Makes the specified window visible. Note that a visible window may still be obscured by other windows or clipped. The command returns 1 if the window was previously visible, else 0. The return value is valid only if the -sync option is specified.

-sync	If specified, the command will execute synchronously and only return when the window procedure of the target window has handled the request. Note that if the target window is hung, the command will never return.
-activate	In addition to being shown, the window is also activated.
-normal	If a window is minimized or maximized, restores it to its original position.
-startup	Shows the window based on the contents of the STARTUPINFO structure when the process was created.

If both -normal and -startup are specified, -startup takes precedence. If neither is specified, the window is shown in its current form, which may be minimized, maximized or normal.

Example: Show all windows for an application

window_exists HWIN

Returns 1 if the specified window exists, else 0.

window_input_enabled HWIN

Returns 1 if the specified window has mouse and keyboard input enabled, else 0.

window_is_child PARENTHWIN CHILDHWIN

Returns 1 if the window CHILDHWIN is a child of the window PARENTHWIN, else 0.

window_maximized HWIN

Returns 1 if the specified window is maximized, else 0.

window_minimized HWIN

Returns 1 if the specified window has been minimized, else 0.

window_visible HWIN

Returns 1 if the specified window is visible, else 0. Note that visible does not imply user can actually see the window (it may be obscured or clipped).

window_unicode_enabled HWIN

Returns 1 if the specified window is a native Unicode window, else 0.

Window management

SYNOPSIS

DESCRIPTION

Window Management

Displays

Commands

COPYRIGHT

TWAPI 2.2.3 Documentation