ShellExecute (Function)

ONLINE HELP
WINDEV, WEBDEV AND WINDEV MOBILE

Version:

Home | Sign in | English

Use in service mode
Required application feature
Running an APK file setup
Application in the background: Specific case from Android 10

WINDEV

WEBDEV

WINDEV Mobile

Others

See also

ShellExecute (Function)

In french: LanceAppliAssociée

Opens a document in its associated application. The application is opened first, then the specified document.

Remarks:

The application used to open the document is the one associated with the extension of the document in Windows (INI file or registry). This associated application may differ according to the configurations used.
This document is opened on the server. This function can be used on the development computer because this compute is considered as being the server.
This document must be found on the server or at any Internet address. This document is opened on the computer of the Web user.
The application used to open the document is the application corresponding to the MIME type associated with the file extension. If several applications correspond to the same type of file, a dialog box will be displayed to select the application to start.
ShellExecute is a blocking function: the application will continue to run when closing the document and its associated application. The document must be on the computer.
To display any page in a browser, you can also use BrowserRunApp.

Versions 16 and later

This function is now available for Android applications.

New in version 16

This function is now available for Android applications.

Versions 18 and later

This function is now available in Windows Store apps mode.

This function is now available in Android widget mode.

This function is now available for iPhone/iPad applications.

New in version 18

This function is now available in Windows Store apps mode.

This function is now available in Android widget mode.

This function is now available for iPhone/iPad applications.

This function is now available in Windows Store apps mode.

This function is now available in Android widget mode.

This function is now available for iPhone/iPad applications.

Versions 19 and later

This function is now available for Java applications.

New in version 19

This function is now available for Java applications.

Versions 21 and later

This function is now available in Universal Windows 10 App mode.

New in version 21

This function is now available in Universal Windows 10 App mode.

Example

// Open the "Functions.doc" document in Word
ShellExecute("C:\WDNEWS\Version\Functions.doc")
// Print the document
ShellExecute("C:\WDNEWS\Version\Functions.doc", "print")

// Open a site in the default browser
ShellExecute("http://www.windev.com")

// Start the default messaging
ShellExecute("mailto:pcsoft@windev.com")
// Start the messaging with parameters
// Parameters recognized by Outlook
ShellExecute("mailto:pcsoft@windev.com" + ...
"?subject=Subject: LST &body=Text: the summary of the LST")

// Open the "Invoice.doc" document from its shortcut
ShellExecute("""C:\Documents and Settings\Julia\Desktop\Shortcut to Invoice.doc.lnk""")

// Open a site in the current browser
ShellExecute("http://www.windev.com")

Syntax

<Result> = ShellExecute(<File name> [, <Verb>])

<Result>: Boolean

True if the document was opened,
False otherwise.
This parameter is not available. This function returns no result.
Returns False if the application is run with a Java virtual machine (JRE) earlier than version 1.6.

<File name>: Character string

Name and full (or relative) path of document to open. A UNC path can be used.
If space characters are found in the name or path of the document to open, the quotes found around this parameter must be tripled.
This parameter can also correspond to a Windows shortcut.
Versions 16 and later
This parameter can correspond to a full path, to a relative path or to a URI.
For example:
"/sdcard/photo.png"
"/sdcard/video.3gp".
"http://www.windev.com": starts the Web browser on the specified page.
"geo:1.44951,43.604363": starts Google Maps or equivalent.
"mailto:pcsoft@pcsoft.fr" starts the application for sending emails.
"sms:0612345678": starts the application for sending SMSs.
The files found in the application directory (or in one of its sub-directories) are not accessible by most of the external applications. It is recommended to use ShellExecute with files located on the external memory of the device (e.g.: sdcard) because they are accessible from all the applications.
New in version 16
This parameter can correspond to a full path, to a relative path or to a URI.
For example:
"/sdcard/photo.png"
"/sdcard/video.3gp".
"http://www.windev.com": starts the Web browser on the specified page.
"geo:1.44951,43.604363": starts Google Maps or equivalent.
"mailto:pcsoft@pcsoft.fr" starts the application for sending emails.
"sms:0612345678": starts the application for sending SMSs.
The files found in the application directory (or in one of its sub-directories) are not accessible by most of the external applications. It is recommended to use ShellExecute with files located on the external memory of the device (e.g.: sdcard) because they are accessible from all the applications.
This parameter can correspond to a full path, to a relative path or to a URI.
For example:
"/sdcard/photo.png"
"/sdcard/video.3gp".
"http://www.windev.com": starts the Web browser on the specified page.
"geo:1.44951,43.604363": starts Google Maps or equivalent.
"mailto:pcsoft@pcsoft.fr" starts the application for sending emails.
"sms:0612345678": starts the application for sending SMSs.
The files found in the application directory (or in one of its sub-directories) are not accessible by most of the external applications. It is recommended to use ShellExecute with files located on the external memory of the device (e.g.: sdcard) because they are accessible from all the applications.
Versions 18 and later
Only the files found in the "appdata" directory can be handled. No Internet URL can be specified.
New in version 18
Only the files found in the "appdata" directory can be handled. No Internet URL can be specified.
Only the files found in the "appdata" directory can be handled. No Internet URL can be specified.

<Verb>: Optional character string

Verb that must be used to start the document. The verbs are defined for each application, to indicate the actions that can be performed. The most common verbs are open or print. If this parameter is not specified, the verb used will be the default verb for the type of document.
This parameter is not available.

Versions 16 and later
This parameter is not available.
This parameter is not available.
New in version 16
This parameter is not available.
This parameter is not available.
This parameter is not available.
This parameter is not available.

Remarks

Use in service mode

When ShellExecute is used in service mode, it runs the associated application but the interface of this application is not visible.

Versions 21 and later

Required application feature

When this function is used, an application feature is declared in the application generation wizard.

Required feature: Family and corporate networks

This feature allows the applications to use incoming and outgoing accesses to the family and corporate networks.

New in version 21

Required application feature

When this function is used, an application feature is declared in the application generation wizard.

Required feature: Family and corporate networks

This feature allows the applications to use incoming and outgoing accesses to the family and corporate networks.

Required application feature

When this function is used, an application feature is declared in the application generation wizard.

Required feature: Family and corporate networks

This feature allows the applications to use incoming and outgoing accesses to the family and corporate networks.

Versions 24 and later

Running an APK file setup

From Android 8, to run the setup of an APK file with ShellExecute, it is necessary to modify the permissions required by the application.

Required permission: REQUEST_INSTALL_PACKAGES.

This permission is used to install packages.

For more details (especially for previous versions of WINDEV Mobile), see FAQ 16927: What to do on Android 8 if the setup of an APK file with ShellExecute is no longer allowed?.

New in version 24

Running an APK file setup

From Android 8, to run the setup of an APK file with ShellExecute, it is necessary to modify the permissions required by the application.

Required permission: REQUEST_INSTALL_PACKAGES.

This permission is used to install packages.

For more details (especially for previous versions of WINDEV Mobile), see FAQ 16927: What to do on Android 8 if the setup of an APK file with ShellExecute is no longer allowed?.

Running an APK file setup

From Android 8, to run the setup of an APK file with ShellExecute, it is necessary to modify the permissions required by the application.

Required permission: REQUEST_INSTALL_PACKAGES.

This permission is used to install packages.

For more details (especially for previous versions of WINDEV Mobile), see FAQ 16927: What to do on Android 8 if the setup of an APK file with ShellExecute is no longer allowed?.

Versions 25 and later

Application in the background: Specific case from Android 10

From Android 10, it is no longer possible to open a window when the application is in the background.

ShellExecute can open a window. If this function is used while the application is in the background, a fatal error will occur.

Tips:

It is possible to determine if the application is in the background using InBackgroundMode.
If an application needs to interact with the user while it is in the background, the solution is to display a notification (via the Notification type). The application will be brought back to the foreground when the notification is clicked, if the ActivateApplication property is set to True. You can also open a window from the procedure passed to the ActionClick property.

For more details, see Android 10: Behavior of applications in the background.

New in version 25

Application in the background: Specific case from Android 10

From Android 10, it is no longer possible to open a window when the application is in the background.

ShellExecute can open a window. If this function is used while the application is in the background, a fatal error will occur.

Tips:

It is possible to determine if the application is in the background using InBackgroundMode.
If an application needs to interact with the user while it is in the background, the solution is to display a notification (via the Notification type). The application will be brought back to the foreground when the notification is clicked, if the ActivateApplication property is set to True. You can also open a window from the procedure passed to the ActionClick property.

For more details, see Android 10: Behavior of applications in the background.

Application in the background: Specific case from Android 10

From Android 10, it is no longer possible to open a window when the application is in the background.

ShellExecute can open a window. If this function is used while the application is in the background, a fatal error will occur.

Tips:

It is possible to determine if the application is in the background using InBackgroundMode.
If an application needs to interact with the user while it is in the background, the solution is to display a notification (via the Notification type). The application will be brought back to the foreground when the notification is clicked, if the ActivateApplication property is set to True. You can also open a window from the procedure passed to the ActionClick property.

For more details, see Android 10: Behavior of applications in the background.

Business / UI classification: Neutral code

Component: wd270std.dll