Windows NT      Yes
Win95           Yes
Win32s          Yes
Import Library  shell32.lib
Header File     shellapi.h
Unicode         WinNT
Platform Notes  None

Функция

ShellExecute

unit ShellApi

Описание:

function ShellExecute(hWnd: HWnd; Operation, FileName, Parameters, Directory: PChar; ShowCmd: Integer): HINST; stdcall;

Функция ShellExecute открывает или выводит на печать указанный файл. Файл может быть исполнимымым файлом или файлом документа. Смотри также ShellExecuteEx.

Параметры:

hwnd

- Хендл родительского окна. Определяет родительское окно. Это окно получает любые окна сообщений, которые генерирует приложение. Например, приложение может сообщать об ошибке при помощи окна сообщений.

Operation

- Указатель на строку, определяющую операцию для выполнения. Строка должна завершаться нулевым символом.
Допустимы следующие значения:

Строка	Описание
"open"	Функция открывает файл, указанный в параметре FileName. Файл может быть как исполнимым файлом, так и файлом документа. Файл может быть папкой, которую нужно открыть.
"print"	Функция открывает файл, указанный в параметре FileName. Файл должен быть файлом документа. Если файл является исполнимым файлом, функция открывает файл, как если бы было указано значение "open".
"explore"	Функция исследует папку, указанную в параметре FileName, експлорером.

FileName

Указатель на строку, определяющую имя файла для открытия или печати, или имя папки для открытия. Строка должна завершаться нулевым символом.

Parameters

- Указатель на строку параметров исполнимого файла. Если файл, заданный в параметре FileName является исполнимым файлом, то Parameters указывает на строку параметров, передаваемых приложению. Строка должна завершаться нулевым символом.

Directory

- Указатель на строку, определяющую директорию по умолчанию. Строка должна завершаться нулевым символом.

ShowCmd

- Определяет как файл будет показываться когда откроется. Если файл, заданный в параметре FileName является исполнимым файлом, то ShowCmd определяет как приложение будет показваться когда оно откроется.
Этот параметр может иметь одно из следующих значений (значения констант определены в модуле Windows):

Константа	Значение	Описание
SW_HIDE	0	Скрывает окно приложения и активирует другое окно.
SW_MAXIMIZE	3	Разворачивает указанное окно на весь экран.
SW_MINIMIZE	6	Сворачивает указанное окно и активирует следующее по порядку окно.
SW_RESTORE	9	Активирует и показывает окно. Если окно было свернуто или развернуто на весь экран, Windows восстанавливает окно до енго нормальных размеров и позиции. Приложение должно указывать этот флаг когда восстанавливает свернутое окно.
SW_SHOW	5	Активирует окно и отображает его в текущем размере и позиции.
SW_SHOWDEFAULT	10	Устанавливает режим показа основываясь на SW_флаге указанном в структуре STATUPINFO, передаваеммой для функции CreateProcess программой, которая запускает приложение. Приложение должно вызвать ShowWindow с этим флагом для установки начального режима отображения своего окна.
SW_SHOWMAXIMIZED	3	Активирует окно и отображает его в развернутом виде.
SW_SHOWMINIMIZED	2	Активирует окно и отображает его в свернутом виде.
SW_SHOWMINNOACTIVE	7	Отображает окно в свернутом виде. Активное окно остается активным.
SW_SHOWNA	8	Отображает окно в его текущем состоянии. Активное окно остается активным.
SW_SHOWNOACTIVATE	4	Отображает окно в его самом последнем размере и позиции. Активное окно остается активным.
SW_SHOWNORMAL	1	Активирует и отображает окно. Если окно было свернуто или развернуто на весь экран, Windows восстанавливает его начальные размеры и позицию. Приложение должно указывать этот флаг когда впервые отображает свое окно.

Если файл, заданный в параметре FileName является файлом документа, параметр ShowCmd должен быть нулевым.

Возвращаемое значение:

Если функция прошла успешно, возвращаемое значение представляет хендл экземпляра объекта приложения, которое было запущено или хендл динамического обмена данными (DDE) серверного приложения.

Если функция не прошла, возвращаемое значение представляет значение ошибки, которое меньше или равно 32.
Следующая таблица представляет список этих ошибок (значения констант определены в модуле ShellAPI):

Константа	Значение	Описание
0	0	Оперативной системе не хватает памяти или ресурсов.
ERROR_FILE_NOT_FOUND	2	Указаный файл не найден.
ERROR_PATH_NOT_FOUND	3	Указаный путь не найден.
ERROR_BAD_FORMAT	11	.EXE файл не рабочий (не Win32 .EXE или ошибка в .EXE образе).
SE_ERR_ACCESSDENIED	5	Операционная система отказывает в доступе к указаному файлу.
SE_ERR_ASSOCINCOMPLETE	27	Имя ассоциированного файла не полное или не правильное.
SE_ERR_DDEBUSY	30	Транзакция динамического обмена данными (DDE transaction) не может быть завершена потому что выпоняются другие DDE транзакции.
SE_ERR_DDEFAIL	29	Транзакция динамического обмена данными провалилась.
SE_ERR_DDETIMEOUT	28	Транзакция динамического обмена данными не может быть завершена потому что истекло время ожидания ответа.
SE_ERR_DLLNOTFOUND	32	Указаная DLL библиотека не найдена.
SE_ERR_FNF	2	Указаный файл не найден.
SE_ERR_NOASSOC	31	Нет приложений ассоциированных с данным расширением файла.
SE_ERR_OOM	8	Не достаточно памяти для завершения операции.
SE_ERR_PNF	3	Указаный путь не найден.
SE_ERR_SHARE	26	Нарушение совместного доступа.

Примечания:

Файл, указаный в параметре FileName может быть файлом документа или исполнимым файлом. Если это файл документа, функция ShellExecute открывает его или выводит на печать, основываясь на значении параметра Operation. Если же файл является исполнимым файлом, функция ShellExecute открывает его, даже если в параметре Operation задана печать.

Вы можете использовать ShellExecute чтобы открыть папку или исследовать ее с помощью эксплорера.

Чтобы открыть папку, используйте один из следующих вызывов:

ShellExecute(handle,nil,путь_для_папки,nil,nil,SW_SHOWNORMAL);

или

ShellExecute(handle,'open',путь_для_папки,nil,nil,SW_SHOWNORMAL);

(См. Рис. 1)

Чтобы исследовать папку с помощью эксплорера используйте следующий вызов:

ShellExecute(handle,'explore',путь_для_папки,nil,nil,SW_SHOWNORMAL);

(См. Рис. 2)

Если Operation - nil, функция открывает файл указаный в параметре FileName. Если Operation - 'open' или 'explore' функция будет приудительно открывать окно или эксплорер.

Рис.1 Так открываеся папка, если в параметре Operation значение nil или 'open'

Рис.2 А так открываеся папка,если в параметре Operation значение 'explore'

И напоследок. В shell32.dll функции ShellExecute нет. Вместо нее имеются функции ShellExecuteA (работает с параметрами в ANSI) и ShellExecuteW (работает с параметрами в unicode):

• function ShellExecuteA(hWnd: HWnd; Operation, FileName, Parameters, Directory: PAnsiChar; ShowCmd: Integer): HINST; stdcall;
• function ShellExecuteW(hWnd: HWnd; Operation, FileName, Parameters, Directory: PWideChar; ShowCmd: Integer): HINST; stdcall;

А из модуля ShellApi под именем функции ShellExecute вызывается функция ShellExecuteA. Поэтому, если вы не хотите подключать модуль ShellApi к проекту, а желаете обращаться к shell32.dll напрямую, используйте одну из этих функций.

См. также: FindExecutable, ShellExecuteEx

Платонов А.Н.
09.07.2009

Список литературы:

1. Delphi 7 Help
2. Delphi 7 Win32 Programmer's Reference
3. Delphi 7 ShellAPI.pas
4. Delphi 7 Windows.pas