Scripting - Chapter 11: List of Functions

Legend of colour for the arguments

• Colours not currently showing up right now. They will be added soon.

Red: Required argument.

Orange : Required argument if further arguments are present, but can be left empty ("").

Blue : Optional argument, but in some cases required.

Green : Optional argument.

Start and stop the graphical interface

POL_GetSetupImages (4.0+)

Purpose:

Download custom images that will be displayed during the installation wizard.

Arguments:

1. Optional --force option to override any cached images
2. URL of top image.
3. URL of left image.
4. Name of the cache directory where to store the images (usually $TITLE).

Description:

To liven up installations, two images are currently displayed by PlayOnLinux/PlayOnMac installers:

- a 150 by 356 pixels image at the left of "presentation" introductory screen

- a 64 by 64 pixels "icon" image at the upper right corner for the remaining of the installation

Default images are normally displayed, but they can be replaced by custom images of the same resolution using this statement. Both JPEG and PNG file formats are supported, JPEG being the preferred format.

Downloaded images will be stored in a cache to avoid repeated downloads. There's no cache invalidation mechanism, so in case incorrect images may have been put into users' cache, you can:

- either preceed arguments with --force to override any cache content;

- change the name of the cache directory to a different value. Make sure you still use something unique to the script though, say "$TITLE_201510120640", etc.

Prerequisite:

This statement must be used before POL_SetupWindow_Init.

Example:

POL_GetSetupImages "http://files.playonlinux.com/resources/setups/AC2/top.jpg" "http://files.playonlinux.com/resources/setups/AC2/left.jpg" "$TITLE"

POL_SetupWindow_Init (4.0+)

Purpose:

Opens the installation wizard window.

Arguments:

None

Description:

Open the UI window that will be used by the PlayOnLinux installation wizard script.

While few initialization statements must be run before POL_SetupWindow_Init, most statements expect the installation window to be opened to either display some progression feedback, or report error cases; So this statement should be used very near the beginning of scripts.

Example:

POL_SetupWindow_Init

POL_SetupWindow_Close (4.0+)

Purpose:

Closes the installation wizard window.

Arguments:

None

Description:

Close the UI window; Well behaved installation scripts should use this statement before exiting. Since most statements expect the installation window to be opened to either display some progression feedback, so it is recommended to use POL_SetupWindow_Close as late as possible in the scripts.

If some error has been detected during the execution of the script by the embedded debugger (see "Debugging Commands" below), at this point PlayOnLinux/PlayOnMac will offer the user to send an automated bug report, containing a log of the script execution, and any comments (s)he wants to add about the issue.

Example:

POL_SetupWindow_Close

PlayOnLinux graphical interface

All the functions below need the command POL_SetupWindow_Init to be executed beforehand.

POL_SetupWindow_presentation (4.0+)

Purpose:

Display a standard introductory screen for the install script and the software it's about to install.

Arguments:

1. Software name (often $TITLE).
2. Software publisher.
3. Site of the publisher.
4. Script author.
5. Prefix name (usually $PREFIX).

Description:

This statement will display the name of the software the install script is about to install, along with basic informations about it, and the name of the script author, in a standardized format. If some "left image" has been setup with POL_GetSetupImages, it will be displayed at the same time.

This can be used right before the installation starts, so the user has one more chance to check what is about to be installed, and eventually cancel the installation.

Example:

POL_SetupWindow_presentation "$TITLE" "Mozilla" "http://www.mozilla.com" "SuperPlumus and NSLW" "$PREFIX"

POL_SetupWindow_free_presentation (4.0+)

Purpuse:

Display a free format introductory screen.

Arguments:

1. Software name (often $TITLE).
2. Message.

Description:

In case the standardized format of POL_SetupWindow_presentation introductory screen does not fit the needs of the install script, this statement let you use any text you want instead. If some "left image" has been defined with POL_GetSetupImages statement, it will be displayed at the same time.

This can be used right before the installation starts, so the user has one more chance to check what is about to be installed, and eventually cancel the installation.

Example:

POL_SetupWindow_free_presentation "$TITLE" "Welcome to Mozilla Firefox installation wizard."

POL_SetupWindow_message (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).

Description:

Display a message.

Example:

POL_SetupWindow_message "Hello world!" "$TITLE"

check_one - POL_SetupWindow_missing (4.0-4.1.1)

Arguments for check_one:

1. Program that must be present.
2. Package that contains this program.

Description:

Check the availability of one or more programs required by the script.

Call check_one as many times as needed (once per program), then use POL_SetupWindow_missing.

Example:

check_one "p7zip" "p7zip"
POL_SetupWindow_missing

POL_SetupWindow_file (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. File to display.

Description:

Display the content of a file.

Example:

POL_SetupWindow_file "Changelog" "$TITLE" "$POL_System_TmpDir/changelog.txt"

POL_SetupWindow_licence (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. File to display.

Description:

Similar to the command POL_SetupWindow_file, but adds an "I agree" checkbox.

Useful for displaying licenses.

Example:

POL_SetupWindow_licence "Licence:" "$TITLE" "$POL_System_TmpDir/licence.txt"

POL_SetupWindow_pulsebar - POL_SetupWindow_pulse - POL_SetupWindow_set_text (4.0+)

Arguments for POL_SetupWindow_pulsebar:

1. Message.
2. Title (often $TITLE).

Arguments for POL_SetupWindow_pulse:

1. Percentage.

Arguments for POL_SetupWindow_set_text:

1. Current text.

Description:

Display a progression bar, from 0 to 100%.

POL_SetupWindow_pulsebar display the progression bar.

POL_SetupWindow_pulse changes the progression value, from 0 to 100%.

POL_SetupWindow_set_text modifies the current message (different from POL_SetupWindow_pulsebar message).

Useful for displaying licenses.

Example:

POL_SetupWindow_pulsebar "Installing patchs 1 to 5." "$TITLE"
 
POL_SetupWindow_set_text "Installation of patch 1 in progress"
POL_Wine "$POL_System_TmpDir/patch1.exe"
POL_SetupWindow_pulse "20" # meaning 20%
 
POL_SetupWindow_set_text "Installation of patch 2 in progress"
POL_Wine "$POL_System_TmpDir/patch2.exe"
POL_SetupWindow_pulse "40"
 
POL_SetupWindow_set_text "Installation of patch 3 in progress"
POL_Wine "$POL_System_TmpDir/patch3.exe"
POL_SetupWindow_pulse "60"
 
POL_SetupWindow_set_text "Installation of patch 4 in progress"
POL_Wine "$POL_System_TmpDir/patch4.exe"
POL_SetupWindow_pulse "80"
 
POL_SetupWindow_set_text "Installation of patch 5 in progress"
POL_Wine "$POL_System_TmpDir/patch5.exe"
POL_SetupWindow_pulse "100"

POL_SetupWindow_wait (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).

Description:

Display an indeterminate progress bar.

Example:

POL_SetupWindow_wait "Please wait" "$TITLE"

POL_SetupWindow_textbox (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Default value.

Description:

Display some window asking the user to type in something.

Return:

What the user typed is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_textbox "Votre pseudo :" "$TITLE"

POL_SetupWindow_textbox_multiline (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Default value.

Description:

Similar to POL_SetupWindow_textbox, but typing happens on several lines.

Return:

What the user typed is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_textbox_multiline "Enter a description for the program" "$TITLE"

POL_SetupWindow_browse (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Default value.

Description:

Ask the user to select a file.

Return:

The path of the file selected by the user is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_browse "Please select the program." "$TITLE"

POL_SetupWindow_question (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).

Description:

Ask a question to the user (that can be answered by Yes or No).

Return:

Answer is returned in the $APP_ANSWER variable (TRUE for Yes, FALSE for No).

Example:

POL_SetupWindow_question "Message" "Title"

POL_SetupWindow_menu (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Available choices.
4. Separator character (often ~ or -).

Description:

Display a menu to the user, asking him to select one entry among the choices provided.

Return:

The choice selected by the user is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_menu "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"

POL_SetupWindow_menu_num (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Available choices.
4. Separator character (often ~ or -).

Description:

Similar to the command POL_SetupWindow_menu except that instead of returning the name of the selected choice (Red for example), it returns the position of the selected choice in the list, as a number (0 being the 1st choice).

Return:

The choice selected by the user is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_menu_num "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"

$APP_ANSWER will contain 0 if the user selected Red, 1 for Green, or 2 for Blue.

POL_SetupWindow_menu_list (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Available choices.
4. Separator character (often ~ or -).
5. Default choice.

Description:

Similar to the command POL_SetupWindow_menu but displays a drop-down list.

Return:

The choice selected by the user is returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_menu_list "What's your favorite color?" "$TITLE" "Red~Green~Blue" "~"

POL_SetupWindow_checkbox_list (4.0+)

Arguments:

1. Message.
2. Title (often $TITLE).
3. Available choices.
4. Separator character (often ~ or -).

Description:

Show a list of options and checkboxen to the user, asking him to select the option(s) he wants.

Return:

The option(s) selected by the user are returned in the $APP_ANSWER variable.

Example:

POL_SetupWindow_checkbox_list "What are your favorite colors?" "$TITLE" "Red~Green~Blue" "~"
if [ "$(echo $APP_ANSWER | grep -o "Red")" != "" ]
then
    # Red was selected
fi
if [ "$(echo $APP_ANSWER | grep -o "Green")" != "" ]
then
    # Green was selected
fi
if [ "$(echo $APP_ANSWER | grep -o "Blue")" != "" ]
then
    # Blue was selected
fi

POL_SetupWindow_cdrom (4.0+)

Description:

Ask the user to select a loaded CD/DVD.

Return:

The path to the drive selected by the user is returned in the $CDROM variable.

Example:

POL_SetupWindow_cdrom

POL_SetupWindow_check_cdrom (4.0+)

Arguments:

1. 1, 2, etc. List of files that should be present.

Description:

Check, in order, if the files specified exist on the CD/DVD. If one is found, $CDROM_SETUP is set to the file path, and the script continues;

Otherwise, execute POL_SetupWindow_cdrom again.

Return:

Should be used right after POL_SetupWindow_cdrom.

Example:

POL_SetupWindow_check_cdrom "Data/32_icon.ico"

POL_SetupWindow_InstallMethod (4.0+)

Arguments:

1. Comma separated list of installation methods available.

Description:

Ask the user want installation method he wants, among the available choices.

Available installation methods:

LOCAL, CD, DVD, DOWNLOAD, STEAM, STEAM_DEMO.

Return:

The choice selected by the user is returned in the $INSTALL_METHOD variable.

Example:

POL_SetupWindow_InstallMethod "LOCAL,CD,STEAM"

POL_RequiredVersion (4.0.15+)

Arguments:

1. Minimum version.

Description:

Checks that the user is running a version of PlayOnLinux/PlayOnMac that is at least equal to the version provided as argument; If not, stops the script execution while alerting the user that (s)he needs to upgrade to run the script.

This is very useful to put near the top of scripts that use statements of features that only appeared in a relatively version of PlayOnLinux/PlayOnMac.

Remarks:

• The sweet spot to place POL_RequiredVersion is between POL_SetupWindow_Init (the interface must be ready to display a user warning) and POL_Debug_Init (so that the usage of an old version of PlayOnLinux/PlayOnMac does not trigger all the embedded debugger/bug reporting workflow);
• While POL_RequiredVersion can display warnings on its own, this function only appeared in PlayOnLinux 4.0.15, and PlayOnLinux 4.0.14 is still the default in some distributions (2013) ; So for the time being, it is recommended to complement it with a check that the statement itself exists, as shown in the example below.

Prerequisite:

The command POL_SetupWindow_Init must have been used beforehand.

Example:

POL_RequiredVersion 4.0.18 || POL_Debug_Fatal "$TITLE won't work with $APPLICATION_TITLE $VERSION\nPlease update"

POL/POM and maximum Wine versions supported

• 4.2.2: Wine 3.0.3, and 3.20
• 4.2.12: Wine 3.0.3, and 3.20
• 4.3.4: Wine 3.0.5, 3.21, and 5.x

POL_AdvisedVersion (4.0.15+)

Arguments:

1. Minimum version.

Description:

Very similar to POL_RequiredVersion (see POL_RequiredVersion), but do not stop the script execution after having alerted the user.

The script should be able to run on older versions of PlayOnLinux/PlayOnMac, even if in some kind of degraded mode.

All remarks about POL_RequiredVersion apply; If you use both in the same script, put POL_RequiredVersion first.

Prerequisite:

The command POL_SetupWindow_Init must have been used beforehand.

Example:

NEEDED=4.0.18
POL_AdvisedVersion $NEEDED || POL_Debug_Message "$TITLE works better with $APPLICATION_TITLE $NEEDED\nPlease update"

POL_Shortcut (4.0+)

Arguments:

1. Executable filename.
2. Launcher name (often $TITLE).
3. Optional name of the icon to download from PlayOnLinux website.
4. Optional executable arguments.
5. Optional list of categories the program belongs to (4.2+)

Description:

Create a launcher in PlayOnLinux. If some path is specified before the executable filename, it will be interpreted relative to the "drive_c" subdirectory of the prefix. Note that Wine, like Windows, translates the name of the "Program Files" directory according to the user locale, so you should always use the special variable $PROGRAMFILES instead of its name in your own locale.

If no path is specified (recommended), the executable filename is looked up using a case insensitive glob search, so you can use wildcards as needed; On the other hand if the program filename contains special characters they may require quoting to avoid being interpreted as wildcards.

PlayOnLinux can also create entries in system menus, but only if category(ies) is(are) provided. The list of valid categories can be found on freedesktop.org site (see main and additional categories). More than one category can be provided, the list separated (and optionally terminated) by semicolons (;).

Prerequisite:

The command POL_Wine_SelectPrefix must have been used beforehand.

Example:

POL_Shortcut "firefox.exe" "$TITLE"

POL_Shortcut_InsertBeforeWine (4.0+)

Arguments:

1. Launcher name (often $TITLE).
2. Command to add.

Description:

Allows to run an extra command each time a program will be about to start.

Example:

POL_Shortcut_InsertBeforeWine "Jedi Knight II" "export __GL_ExtensionStringVersion=17700"

POL_Shortcut_QuietDebug (4.0.17+)

Arguments:

1. Launcher name (often $TITLE).

Description:

Avoid displaying "This program may have crashed" dialog box when the program launched by a shortcut exits with a non-zero exitcode.

This is a bandaid for programs exiting with meaningless exitcodes, as it sometimes happens since it's of little consequence under Windows.

Example:

POL_Shortcut_QuietDebug "Sam and Max S2E1: Ice Station Santa"

POL_Shortcut_Document (4.0.15+)

Arguments:

1. Launcher name (often $TITLE).
2. Path to some documentation file

Description:

Link some documentation file to an existing PlayOnLinux shortcut; The documentation will be available using Right-click on shortcut > Read the manual.

Document file is looked up using the same rules POL_Shortcut uses to find executables.

Prerequisite:

The command POL_Wine_SelectPrefix must have been used beforehand.

Example:

POL_Shortcut_Document "$TITLE" "README.txt"

POL_Browser (4.0+)

Arguments:

1. URL to open.

Description:

Opens a URL in the user's default Internet browser.

Example:

POL_Browser "http://www.playonlinux.com"

POL_Download (4.0+)

Arguments:

1. URL to download.
2. (Optional) Expected MD5 digest of the downloaded file

Description:

Download a URL to a local file. The file will be created in the current directory, named after the last component of the URL.

If an expected MD5 digest is provided (recommended), the downloaded file will then be run thru the MD5 digest algorithm, and the result compared to the expected value. If they differ, it will be assumed the download broke and the user will be asked if (s)he wants the download to be reattempted.

This is a very effective way to ensure that the downloaded content is the expected one, however some URLs lead to resources that are very often updated, in which case providing an up-to-date MD5 digest can be impractical.

Example:

POL_Download "http://repository.playonlinux.com/divers/QuickTime.qtp" "417f9bf5ec52d3bfa5826b4905658dac"

POL_Download_Resource (4.0+)

Arguments:

1. URL to download.
2. Expected MD5 digest of the downloaded file
3. (Optional) Subfolder to download the file to

Description:

Download a URL to the local file cache, if not already present. The file will be created in $POL_USER_ROOT/ressources directory (unless some subfolder is provided, in which case it will be created under $POL_USER_ROOT/ressources/<subfolder>, creating the subfolder if needed), and named after the last component of the URL.

Contrary to POL_Download, the MD5 digest is mandatory for POL_Download_Resource, as it will not only be used to validate the download (see POL_Download), but is also used, if some file already exists in the cache, to check that it has the expected content.

Beware that files stored in the cache will potentially stay there for a very long time, since PlayOnLinux never does any kind of cache cleanup, based on time or size; So you should only use POL_Download_Resource for files that are likely to be reused, possibly because they're necessary for several install scripts.

Example:

POL_Download_Resource "http://downloads.sourceforge.net/ffdshow-tryout/ffdshow_beta7_rev3154_20091209.exe" "c3f75f29521f749f9c9fc5489544cb04"

POL_System_TmpCreate (4.0+)

Arguments:

1. Name of the temporary directory (often $PREFIX).

Description:

Creates the temporary directory dedicated to the script.

Return:

$POL_System_TmpDir will contain the path of the created temporary directory.

Example:

POL_System_TmpCreate "$PREFIX"

POL_System_TmpDelete (4.0+)

Description:

Removes the script's temporary directory.

Example:

POL_System_TmpDelete

POL_System_SetArch (4.0+)

Arguments:

1. Supported architectures (see below).

Description:

Set the (Wine) architectures supported by the script.

Allowed values:

• auto: Use the version of Wine matching the system architecture (Wine x86 on x86 and Wine x64 on amd64).

• x86: Use the x86 version of Wine for installation (useful if the program doesn't work well with the x64 version).

• amd64: Use the x64 version of Wine for installation (if the system architecture is x86, the script stops).

Example:

POL_System_SetArch "auto"

Prerequisite:

The command POL_Wine_PrefixCreate must be located after.

POL_Call (4.0+)

Arguments:

1. Function name.
2. 2, 3, etc.: Function arguments, if necessary (very few functions take arguments).

Description:

Download and execute a script from the Functions category (the list of functions and their basic information for each can be found here: Components and Functions).

Prerequisite:

For most functions, the commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Call POL_Install_vcrun6

Wine-related functions

POL_Wine_SelectPrefix (4.0+)

Arguments:

1. Prefix name (often $PREFIX).

Description:

Select the prefix that will be used by Wine (mandatory, even if the prefix hasn't been created yet).

Example:

POL_Wine_SelectPrefix "$PREFIX"

POL_Wine_PrefixExists (4.0+)

Arguments:

1. Prefix name (often $PREFIX).

Description:

Check if a prefix exists (useful for game extensions and patches).

Return:

The function displays True if the prefix exists, and False otherwise.

Example:

if [ "$(POL_Wine_PrefixExists "$PREFIX")" = "False" ]
then
    # The préfixe doesn't exist
fi

POL_Wine_PrefixCreate (4.0+)

Arguments:

1. Wine version.

Description:

Creates or updates a prefix. It is possible to use a version of Wine different from the one installed system wide on user's computer, by specifying this version as first argument.

Prerequisite:

The command POL_Wine_SelectPrefix must have been used beforehand.

Example:

POL_Wine_PrefixCreate "1.3.4"

POL_Wine (4.0+)

Arguments:

• Program pathname.
• 2, 3, etc.: program arguments, if any.

Description:

This command will run the given program; It works exactly like the "wine" command, but uses the Wine versions management and logging facilities of PlayOnLinux.

While most programs started that way will behave synchronously (in other words, will block the script until they're finished), some don't and the POL_Command will need to be followed by a POL_Wine_WaitExit command to prevent the rest of the script from being executed before the program has finished.

See POL_Wine_WaitBefore and POL_Wine_WaitExit.

Note: Using start /unix before the program name can fix issues of access and installation paths with several CD/DVD. However, the use of start /unix makes POL_Wine asynchronous, and since asynchronous programs are not automatically killed if the script is aborted from PlayOnLinux side, it should only be used when necessary.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

POL_SetupWindow_VMS (4.0+)

Arguments:

1. Minimum amount of onboard video memory required, in MB.

Description:

Ask the user how much (dedicated) RAM his videocard has, since it is actually very difficult to determine this value in a portable way.

If the value is lower than the minimum argument value, the user is warned that the program being installed is likely not to work correctly. In all cases, the script goes on and the value is written in the Wine registry.

The user reply is cached so that it doesn't need to be asked again during the next installations. In case of mistake, or if the amount of video memory changes, the cached value can be erased by opening the PlayOnLinux console, and typing "POL_Config_Delete VMS" (for a lack of GUI support at the moment).

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_SetupWindow_VMS "128"

Set_OS (4.0+)

Arguments:

1. Windows version to emulate.
2. Service pack.

Description:

Modifies the Windows version emulated by Wine.

Default value: winxp (Windows XP).

Allowed values:

Windows versions: win7, vista, win2003, winxp, win2k, winnt, winme, nt40, win98, win95, win31.

Services packs: sp1, sp2, sp3.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

Set_OS "winxp"

Set_Managed (4.0+)

Arguments:

1. On/Off.

Description:

Set if the window manager will be allowed to manage Wine windows.

Default value: On.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

Set_Managed "Off"

Set_SoundDriver (4.0+)

Arguments:

1. alsa/oss/esd.

Description:

Set the audio driver Wine will use.

This command does nothing under PlayOnMac, since it is useless in that environment.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

Set_SoundDriver "alsa"

POL_Wine_Direct3D (4.0+)

Arguments:

1. Setting to create/modify.
2. New setting value.

Description:

Creates or modifies a registry setting below key [HKEY_CURRENT_USER\Software\Wine\Direct3D].

Allowed values:

See WineHQ's Wiki.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_Direct3D "UseGLSL" "disabled"

POL_Wine_X11Drv (4.0.14+)

Arguments:

1. Setting to create/modify.
2. New setting value.

Description:

Creates or modifies a registry setting below key [HKEY_CURRENT_USER\Software\Wine\X11 Driver].

Allowed values:

See WineHQ's Wiki.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_X11Drv "DXGrab" "Y"

POL_Wine_DirectSound (4.0+)

Arguments:

1. Setting to create/modify.
2. New setting value.

Description:

Creates or modifies a registry setting below key [HKEY_CURRENT_USER\Software\Wine\DirectSound].

Allowed values:

See WineHQ's Wiki.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_DirectSound "HardwareAcceleration" "Emulation"

POL_Wine_DirectInput (4.0+)

Arguments:

1. Setting to create/modify.
2. New setting value.

Description:

Creates or modifies a registry setting below key [HKEY_CURRENT_USER\Software\Wine\DirectInput].

Allowed values:

See WineHQ's Wiki.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_DirectInput "MouseWarpOverride" "force"

POL_Wine_GetRegValue (4.0+)

Arguments:

1. Setting to read (the key is not required).

Description:

This function returns the value of a setting from the registry.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Return:

The function displays the value of the specified setting.

Example:

VALUE="$(POL_Wine_GetRegValue "MouseWarpOverride")"

Set_Desktop (4.0+)

Arguments:

1. On/Off.
2. Virtual desktop width (if it is enabled).
3. Virtual desktop height (if it is enabled).

Description:

Sets the Wine virtual desktop settings.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

Set_Desktop "On" "1024" "768"

Set_WineWindowTitle (4.0+)

Arguments:

1. Virtual desktop name.

Description:

Set the title of the virtual desktop window (purely aesthetic effect).

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

Set_WineWindowTitle "$TITLE"

POL_Wine_InstallFonts (4.0+)

Description:

This command installs standard (but not installed by default) fonts into the prefix.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_InstallFonts

POL_Wine_SetVideoDriver (4.0+)

Description:

Set correct video driver (when Wine fails to do it properly).

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_SetVideoDriver

POL_Wine_OverrideDLL (4.0+)

Arguments:

1. Mode of override.
2. 3, 4, etc.: DLL names (without .dll suffix).

Description:

Set the override mode for one or more dynamic library(ies).

Allowed override modes:

"native", "builtin", "native,builtin", "builtin,native", or empty value ("") to disable the DLL(s).

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_OverrideDLL "native" "msvcrt"
POL_Wine_OverrideDLL "" "msvcrt" # To disable the DLL

POL_Wine_OverrideDLL_App (4.0+)

Arguments:

1. Executable name.
2. Mode of override.
3. 3, 4, etc.: DLL names (without .dll suffix).

Description:

Set the override mode for one or more dynamic library(ies), but only for a specific program.

Allowed override modes:

"native", "builtin", "native,builtin", "builtin,native", or empty value ("") to disable the DLL(s).

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_OverrideDLL_App "firefox.exe" "native" "msvcrt"
POL_Wine_OverrideDLL_App "firefox.exe" "" "msvcrt" # To disable the DLL

POL_Wine_WaitBefore (4.0.15+)

Arguments:

1. Program name.

Description:

Placed before a POL_Wine command that starts a program synchronously (ie a "blocking" POL_Wine command), it will display a standard wait message while it runs.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_WaitBefore "$TITLE"

POL_Wine_WaitExit (4.0+)

Arguments:

1. Program name.

Description:

Placed after a POL_Wine command that starts a program asynchronously (ie a "non-blocking" POL_Wine command), it will display a standard wait message while it runs and wait for its completion.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_WaitExit "$TITLE"

POL_Wine_reboot (4.0+)

Description:

Emulate a Windows reboot.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_reboot

Debugging commands

POL_Debug_Init (4.0+)

Description:

Start debugging system.

Example:

POL_Debug_Init

POL_Debug_Message (4.0+)

Arguments:

1. Message.

Description:

Write a message to the installation log (not shown to the user).

Prerequisite:

The command POL_Debug_Init must have been used beforehand.

Example:

POL_Debug_Message "Modifying config.cfg file."

POL_Debug_Warning (4.0+)

Arguments:

1. Message.

Description:

Write a warning message to the installation log (not shown to the user).

Prerequisite:

The command POL_Debug_Init must have been used beforehand.

Example:

POL_Debug_Warning "File config.cfg did not exist, creating one."

POL_Debug_Error (4.0+)

Arguments:

1. Message.

Description:

Write an error message to the installation log (not shown to the user).

Prerequisite:

The command POL_Debug_Init must have been used beforehand.

Example:

POL_Debug_Error "Error while modifying config.cfg file"

POL_Debug_Fatal (4.0+)

Arguments:

1. Message.

Description:

Raises a fatal error (the script is immediately aborted).

Prerequisite:

The command POL_Debug_Init must have been used beforehand.

Example:

POL_Debug_Fatal "Error while modifying config.cfg file"

Previous: Chapter 10: Script Translation