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

Arguments:

1. URL of top image.
2. URL of left image.
3. Name of the directory where to store the images (often $TITLE).

Description:

Download top and left images of the script from the PlayOnLinux site.

Prerequisite:

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

Description:

Opens the installation wizard window.

Example:

POL_SetupWindow_Init

POL_SetupWindow_Close

Description:

Closes the installation wizard window.

Example:

POL_SetupWindow_Close

PlayOnLinux graphical interface

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

POL_SetupWindow_presentation

Arguments:

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

Description:

Present the software.

Example:

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

POL_SetupWindow_free_presentation

Arguments:

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

Description:

Present the software with more freedom than POL_SetupWindow_presentation.

Example:

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

POL_SetupWindow_message

Arguments:

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

Description:

Display a message.

Example:

POL_SetupWindow_message "Hello world!" "$TITLE"

check_one - POL_SetupWindow_missing

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

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

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

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 start /unix "$POL_System_TmpDir/patch1.exe"
POL_SetupWindow_pulse "20" # meaning 20%
 
POL_SetupWindow_set_text "Installation of patch 2 in progress"
POL_Wine start /unix "$POL_System_TmpDir/patch2.exe"
POL_SetupWindow_pulse "40"
 
POL_SetupWindow_set_text "Installation of patch 3 in progress"
POL_Wine start /unix "$POL_System_TmpDir/patch3.exe"
POL_SetupWindow_pulse "60"
 
POL_SetupWindow_set_text "Installation of patch 4 in progress"
POL_Wine start /unix "$POL_System_TmpDir/patch4.exe"
POL_SetupWindow_pulse "80"
 
POL_SetupWindow_set_text "Installation of patch 5 in progress"
POL_Wine start /unix "$POL_System_TmpDir/patch5.exe"
POL_SetupWindow_pulse "100"

POL_SetupWindow_wait

Arguments:

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

Description:

Display an indeterminate progress bar.

Example:

POL_SetupWindow_wait "Please wait" "$TITLE"

POL_SetupWindow_textbox

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

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

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

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

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

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

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

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

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

Arguments:

1. File that must be present.

Description:

Check that the file specified exists on the CD/DVD. If it doesn't, 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

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_Shortcut

Arguments:

1. Executable filename.
2. Launcher name (often $TITLE).
3. Name of the icon to download from PlayOnLinux website.
4. Executable arguments.

Description:

Create a launcher in PlayOnLinux.

Prerequisite:

The command POL_Wine_SelectPrefix must have been used beforehand.

Example:

POL_Shortcut "firefox.exe" "$TITLE"

POL_Shortcut_InsertBeforeWine

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_Browser

Arguments:

1. URL to open.

Description:

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

Example:

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

POL_System_TmpCreate

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

Description:

Removes the script's temporary directory.

Example:

POL_System_TmpDelete

POL_System_SetArch

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"

POL_Call

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

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

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

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

Arguments:

1. Minimum amount of RAM required, in MB.

Description:

Ask the user how much (dedicated) RAM his videocard has.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_SetupWindow_VMS "128"

Set_OS

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 "win2k"

Set_Managed

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

Arguments:

1. alsa/oss/esd.

Description:

Set the audio driver Wine will use.

Note: 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

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

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

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

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

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

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

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

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

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

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

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_WaitExit

Arguments:

1. Program name.

Description:

Wait for the completion of the program started with the POL_Wine command.

Prerequisite:

The commands POL_Wine_SelectPrefix and POL_Wine_PrefixCreate must have been used beforehand.

Example:

POL_Wine_WaitExit "$TITLE"

POL_Wine_reboot

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

Description:

Start debugging system.

Example:

POL_Debug_Init

POL_Debug_Message

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

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

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

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