Tcl Windows API extension

The Windows shell identifies objects in its namespace, including non-file objects such as Control Panel applets and printers, using an item ID. Similar to a file system path, an object resides within the shell namespace object hierarchy and the entire path to the object is defined by item identifier list.

Folder Paths

The command get_shell_folder returns the path to the directory specified by a Windows Shell CSIDL.

File Operations

The command shell_execute allows invocation of any operation of a file or resource as from Windows Explorer, for example, opening a URL in a browser, searching a directory, starting a program and so on.

The commands recycle_file and recycle_files sends the specified file(s) to the Windows Recycle Bin.

Shell Dialogs

The command shell_object_properties_dialog displays the property page dialogs for the shell objects such as files, printers and volumes.

Themes

The commands OpenThemeData, CloseThemeData, IsThemeActive, IsAppThemed, GetCurrentThemeName, GetThemeColor and GetThemeFont provide access to information related to the current theme if the underlying platform supports themes. See the Windows SDK for documentation about these.

Shortcuts

The commands read_shortcut and write_shortcut allow reading and writing of shell shortcuts.

The commands read_url_shortcut and write_url_shortcut allow reading and writing of URL shortcuts. A URL shortcut can be invoked by invoke_url_shortcut.

Taskbar

TWAPI also provides commands to display and manage in the system tray (the Windows taskbar notification area). To display an icon in the system tray, application must first retrieve a handle to an icon using commands such as load_icon_from_file, load_icon_from_module or load_icon_from_system. This icon can then be displayed in the taskbar with the systemtray addicon command with optional callbacks when the icon is clicked or selected. Icons can be removed from the system tray via the systemtray removeicon command. Standard features like display of menus or balloons can be implemented either via the callbacks and systemtray modifyicon command.

Commands

get_shell_folder CSIDL ?-create?

Returns the path to the file system directory corresponding to the Windows shell folder identified by CSIDL. The path is always returned in native format.

CSIDL must be one of the following symbols or the corresponding integer values values as defined in the Windows SDK: csidl_admintools, csidl_common_admintools, csidl_appdata, csidl_cdburn_area, csidl_common_appdata, csidl_common_desktopdirectory, csidl_common_documents, csidl_common_favorites, csidl_common_music, csidl_common_pictures, csidl_common_programs, csidl_common_startmenu, csidl_common_startup, csidl_common_templates, csidl_common_video, csidl_cookies, csidl_desktopdirectory, csidl_favorites, csidl_history, csidl_internet_cache, csidl_local_appdata, csidl_mymusic, csidl_mypictures, csidl_myvideo, csidl_nethood, csidl_printhood, csidl_profile, csidl_profiles, csidl_programs, csidl_program_files, csidl_program_files_common, csidl_recent, csidl_sendto, csidl_startmenu, csidl_startup, csidl_system, csidl_templates, csidl_windows.

Refer to the documentation in the Windows SDK for the meaning of each of these identifiers.

If the option -create is specified, the folder will be created if it does not currently exist.

On some platforms, some of the above CSIDL's may be invalid. In this case, the command will attempt to return equivalent paths through other means such as environment variable settings.

The command will return an empty string if the CSIDL does not exist on the platform or if its value cannot be retrieved.

CloseThemeData

See Themes.

GetCurrentThemeName

See Themes.

GetThemeColor

See Themes.

GetThemeFont

See Themes.

invoke_url_shortcut SHORTCUTPATH ?options?

Invokes a URL shortcut. SHORTCUTPATH specifies the path of the URL shortcut itself. The following options may be specified.

-allowui	Allows user interaction.
-hwin HWIN	Specifies the parent window handle for user interaction. This is ignored if -verb is specified or if -allowui is not specified.
-verb VERB	Specifies the verb to invoke on the shortcut, for example open, edit etc.

IsAppThemed

See Themes.

IsThemeActive

See Themes.

OpenThemeData

See Themes.

read_shortcut SHORTCUTPATH ?options?

Reads a shortcut. SHORTCUTPATH specifies the path of the shortcut itself. The contents of the shortcut are returned as a keyed list with the following fields.

-args	Command line arguments for the link.
-desc	Description of the shortcut. This is the string that is visible to the user as the label of the shortcut.
-hotkey	The hotkey associated with the shortcut. This is an integer as described in the documentation of the IShellLink::Hotkey command in the Platform SDK.
-iconindex	The index of the icon within the icon file specifies by the -iconpath field.
-iconpath	The path to the file from which the icon for the shortcut is to be taken.
-idl	The item identifier list for the object pointed to by the shortcut.
-path	The file system path in the case that the shortcut points to a file.
-runas	A boolean value that indicates whether the target program is invoked as a different user or not.
-showcmd	The initial state of the window.
-workdir	The working directory of the shortcut.

Note that the field names are the same as the options for the write_shortcut command so you can modify a shortcut by reading it, changing the specific fields and passing the same list to write_shortcut.

The content format and operation of the command may be controlled through the following options.

-hwin HWIN	Identifies the window to be used as the parent of the dialog box that pops up to ask the user for more information when the shortcut cannot be resolved.
-install	Calls the MSI installer if the shortcut is an advertised shortcut and the target has not been installed yet.
-nolinkinfo	Disables distributed link tracking.
-nosearch	Normally, the command will search for the target if it cannot be found in the location pointed to by the shortcut. Specifying this option disables this search.
-notrack	Specifies that distributed link tracking to be not used.
-noui	Specifies that no dialog box should be displayed even if the link cannot be resolved.
-rawpath	Normally, the command resolves any embedded environment variables contained in the returned -path field and verifies the path exists. Specifying this option disables both these features and returns raw path contained in the shortcut.
-shortnames	The path contained in the returned -path field uses short name (8.3) format.
-timeout TIMEOUT	Specifies the timeout, in milliseconds, for resolving the link. This option has no effect unless the -noui is also specified.
-uncpath	The path contained in the returned -path field is in UNC format.

read_url_shortcut SHORTCUTPATH

Returns the URL pointed to by a URL shortcut. SHORTCUTPATH specifies the path of the URL shortcut itself.

recycle_file FILENAME ?-confirm BOOLEAN? ?-showerror BOOLEAN?

Sends the specified file to the Windows Recycle Bin. Returns true on success and false if user aborted the command. Any errors will generate a Tcl exception.

-confirm BOOLEAN	If true, a confirmation dialog is displayed to the user. Default is false.
-showerror BOOLEAN	If true, an error dialog is displayed to the user in case of errors. Default is false.

recycle_files FILENAMES ?-confirm BOOLEAN? ?-showerror BOOLEAN?

Sends the specified files to the Windows Recycle Bin. Returns true on success and false if user aborted the command. Any errors will generate a Tcl exception.

-confirm BOOLEAN	If true, a confirmation dialog is displayed to the user. Default is false.
-showerror BOOLEAN	If true, an error dialog is displayed to the user in case of errors. Default is false.

shell_execute ?options?

The shell_execute command is a wrapper around the Windows ShellExecuteEx function that allows invocation of various operations on file and other resources in the same manner as exposed by Windows Explorer as shown in the examples below.

The command supports the options shown in the table below and returns an empty string unless the -getprocesshandle option is specified.

-asyncok BOOLEAN	Indicates that the execution may be performed on a background thread. See the description in Windows SDK of the SEE_MASK_ASYNCOK flag in the SHELLEXECUTEINFO structure.
-class CLASS	The file specified by the -path option is handled based on its extension by default. The -class option may be used to change the handler for the file. CLASS can be a file extension, a ProgID, a URI protocol scheme or a registry path under HKEY_CLASSES_ROOT that contains Shell verbs. See below for examples.
-dir PATH	Path of the working directory. Defaults to the current directory.
-getprocesshandle BOOLEAN	Normally, the command returns an empty string. If this option is specified, the command returns a handle to the process, if any, that was created by the shell to handle the request. If no such process was required to be created, or was already running, an empty string is returned. If a non-empty handle is returned, it must be closed by calling close_handle.
-hmonitor HANDLE	Specifies a handle to a monitor on multiple-monitor systems. Cannot be used with the -hicon option.
-hwin HWND	Specifies the parent window handle, if any, for dialogs that are displayed. By default, no parent window is specified.
-idl IDL	TBD
-invokeidlist BOOLEAN	Normally, the shell will look up the registry for the list of verbs applicable for a file. If this option is specified as true, the shell will look up verbs dynamically added by shell extensions. See examples below. Default is false.
-logusage BOOLEAN	If true, the invocation will add to the counter maintained by Windows for determining the applications that show up on the Start menu. Default is false. Requires Windows XP or later and will generate an error on earlier versions of Windows.
-noconsole BOOLEAN	If true, the current process is not used for any processes created for the operation. A new console window is created if required. Default is false.
-noui BOOLEAN	If true, no user interaction, such as error display is done. Default is false.
-params STRING	Contains the parameter string to be passed to the invoked application. Use standard Windows syntax for separating parameters using spaces and quotes.
-path STRING	Path of the file or object on which the action is to be invoked. If unspecified, defaults to the current directory. Note that some handlers require the full path in native format to be be specified.
-show STRING	Specifies how the application invoking the action is to be displayed. Must be one of hide, shownormal, normal, showminimized, showmaximized, maximize, shownoactivate, show, minimize, showminnoactive, showna, restore, showdefault, or forceminimize. See the Windows SDK documentation of ShellExecute for details. Default is normal.
-substenv BOOLEAN	If true, any environment variables present in the values of the -path and -dir options are expanded. Default is false.
-unicode BOOLEAN	Specify this flag as true for a Unicode application.
-verb ACTION	Specifies the action to invoke on the resource, for example open, edit etc. If ACTION is runas, the program is started in elevated mode. See other examples below for other values of ACTION.
-wait BOOLEAN	Wait for the action to complete before returning. The exact effect of this depends on the action being invoked and the application handling the action. Default is false.
-waitforinputidle BOOLEAN	If specified as true, the command will wait up to one minute for any processes that are created as part of the invocation to enter the idle loop. Default is false.

Examples: Start up an application (notepad.exe):

shell_execute -path notepad.exe

Start up an application with parameters:

shell_execute -path notepad.exe -params {sample.txt}

Invoke the default action for a particular document. In most cases, this will open the application associated with the document type:

shell_execute -path sample.doc

Invoke a non-default action on a document (printing using the associated application):

shell_execute -path sample.doc -verb print

Invoke a non-default action (search) on a directory:

shell_execute -path c:/temp -verb find

Open a document in the home directory using environment variables:

shell_execute -path {%HOMEDRIVE%\%HOMEPATH%\My Documents\darknet.pdf} -substenv true

Launch a browser for a URL:

shell_execute -path http://www.google.com

Compose a email message:

shell_execute -path mailto:[email protected]

Invoke a dynamic action on a file. This will bring up the property sheet for notepad.exe instead of executing it.

shell_execute -path notepad.exe -verb properties -invokeidlist true

Start a text file using the handler for .html files instead of the handler for .txt files (Notepad by default). Note how the full file path is passed.

shell_execute -path [file nativename [file normalize foo.txt]] -class .html

Similar to above except the htmlfile registry key is used.

shell_execute -path [file nativename [file normalize foo.txt]] -class htmlfile

shell_object_properties_dialog OBJECTPATH ?options?

Displays the shell property dialog for the specified object which may be a file, a printer or a volume. OBJECTPATH is the path or the name of the object. The following options may be specified:

-hwin HWIN	If specified, HWIN is the handle to the window to be used as the parent for the dialog.
-type file\|printer\|volume	Specifies the type of the object identified by OBJECTPATH. Defaults to file.

systemtray addicon HICON ?CMDPREFIX?

Adds the icon referenced by handle HICON to the system tray and returns an identifier to be used with the systemtray modifyicon and systemtray removeicon commands.

If argument CMDPREFIX is specified and is not empty, it is invoked in response to user interface events (such as mouse clicks) related to the displayed icon. Four additional arguments are appended to CMDPREFIX before it is invoked - the associated identifier (as returned by this command), the notification event, the location of the mouse (as a pair of X,Y coordinates) when the event occured, and the clock ticks (as returned by the Windows GetClockTicks API) at the time of the event.

The notification event indicates the event and is one of the following constants:

select	Sent when the user selects the icon with the mouse (generally by clicking the left mouse button).
keyselect	Sent when the user selects the icon with the keyboard.
contextmenu	Sent when the user clicks the right mouse button.
mousemove	Sent when the mouse cursor is moved within the icon display area.
lbuttondown	Sent when the left mouse button is pressed.
lbuttonup	Sent when the left mouse button is released.
lbuttondblclk	Sent on a left button double-click.
rbuttondown	Sent when the right mouse button is pressed.
rbuttonup	Sent when the right mouse button is released.
rbuttondblclk	Sent on a right button double-click.
mbuttondown	Sent when the middle mouse button is pressed.
mbuttonup	Sent when the middle mouse button is released.
mbuttondblclk	Sent on a middle button double-click.
mousewheel	Sent when the mouse wheel is rotated.
xbuttondown	Sent when the x mouse button is pressed.
xbuttonup	Sent when the x mouse button is released.
xbuttondblclk	Sent on a x button double-click.
balloonshow	Sent when the balloon help associated with the icon is displayed.
balloonhide	Sent when the balloon icon is hidden.
balloontimeout	Sent when the balloon is hidden after a timeout.
balloonuserclick	Sent when the user clicks on the balloon.

Generally, applications should need to only handle the select, keyselect and contextmenu events. If the double-click events are also used, applications should be aware that select and button up/down events will also be sent and filter these appropriately.

For future compatibility, applications should ignore any notification events not listed above.

systemtray modifyicon ICONID ?options?

Modifies the specified system tray icon as per the specified options. ICONID is the identifier for the icon as returned by systemtray addicon. The following options may be specified:

-hicon HICON	Sets the icon to that specified by the handle HICON.
-tip STRING	Sets the tooltip that displayed when the mouse hovers over the icon. Truncated to 127 characters.
-balloon BALLOONTEXT	Displays BALLOONTEXT in the balloon tool tip for the icon. The balloon is removed after a timeout based on system setting. BALLOONTEXT is truncated to 255 characters.
-balloontitle BALLOONTITLE	Sets the title of the balloon, truncated to 63 characters.
-balloonicon BALLOONICON	Sets the icon displayed in the balloon tooltip. BALLOONICON must be one of info, warning, error, user, or none (default). The icon is not displayed if the balloon title is not specified.
-silent BOOLEAN	If true, sounds associated with the balloon (based on the icon type), are not played. Default is false (sounds are enabled).

systemtray removeicon ICONID

Removes the specified icon from the system tray. ICONID is the identifier for the icon as returned by systemtray addicon.

write_shortcut SHORTCUTPATH ?options?

Writes or creates a shortcut. SHORTCUTPATH must be the full absolute path of the shortcut. The following options control the contents of the shortcut.

-args ARGUMENTS	Specifies the command line arguments for the link.
-desc DESCRIPTION	Specifies the description of the shortcut. This is the string that is visible to the user as the label of the shortcut.
-hotkey HOTKEY	Specifies the hotkey to be associated with the shortcut. HOTKEY should be an integer as described in the documentation of the IShellLink::Hotkey command in the Platform SDK or a symbolic string as described in the register_hotkey command.
-iconindex INDEX	Specifies INDEX as the index of the icon within the icon file specifies by the -iconpath option.
-iconpath ICONPATH	Specifies ICONPATH as the path to the file from which the icon for the shortcut is to be taken.
-idl IDL	Specifies that the shortcut should point to the object identified by the item identifier list IDL. This is useful in cases where the target of the short cut is not a file.
-path TARGETPATH	Specifies TARGETPATH as the file system path to which the shortcut points. This must be a full absolute path else Windows will return an error.
-runas BOOLEAN	If BOOLEAN as true, the command will be invoked as a different user (effect depends on version of Windows).
-showcmd WINDOWSTATE	Specifies the initial state of the window. WINDOWSTATE should be one of minimized, maximized or normal.
-workdir DIRPATH	Specifies DIRPATH as the working directory of the shortcut.

write_url_shortcut SHORTCUTPATH URL ?-missingprotocol usedefault|guess?

Writes or creates a URL shortcut. SHORTCUTPATH specifies the path of the URL shortcut itself. URL is the URL to which the shortcut should point.

If the -missingprotocol option is specified, the system will attempt to fill in the protocol if URL itself does not specify a protocol. If the value of this option is guess, the system will attempt to guess the protocol based on the URL string. If the option value is usedefault, the system will use the default protocol scheme.

Windows Shell

SYNOPSIS

DESCRIPTION

Item Identifiers

Folder Paths

File Operations

Shell Dialogs

Themes

Shortcuts

Taskbar

Commands

COPYRIGHT

TWAPI 4.6.0 Documentation