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

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. Optional name of the icon to download from PlayOnLinux website.
4. Optional executable arguments.
5. Optional list of categories the program belongs to

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, but in all cases each category must be terminated by a semicolon (;).

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_Shortcut_Document

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

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:

• 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

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.

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_WaitBefore

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

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

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